Meeting Hugo
For general flow, first hugo check files int he original folders and files, structures and so on.
If there is nothing on this files, Hugo searchs in theme/ folder. Pending to update image.
graph LR; A–>B;
Notes: For create new site:
hugo new site <name>
For create new theme:
hugo new theme <name>
For create a new list page on content folder:
hugo new post/_index.md
For create a new single page on content folder:
hugo new post/customizing-your-theme.md
For general flow, first hugo check files int he original folders and files, structures and so on. If there is nothing on this files, Hugo searchs in theme/ folder. Pending to update image.
Importing a theme:
cd themes
git clone path-to-git-repo.git
For use this them, you need to specify on config.toml file:
+++
…
Theme = “your-theme-name”
…
+++
Folder structure:
- archetypes: Site generator
- content: Content web site, web pages
- data: database of web site, json files, data you are goint to use
- layaots: header templates, same folder in all web sites, etc. It is a skeleton
- static: store images, js files, css files. Files which cannot be changed.
- themes: pre-build themes you want to load. If you want to use a theme, all of this files will be here.
- config.toml: configuration files. settings for your web site. This file controls universal aspects of the website.
Content Organization
There are three types of content: Home, List, Single
- Home: Content in the homepage. It is the landing page which is the most important page in the website.
- Single page: It is like a single post, article. It is the good ingredient for static web site.
- List pages: It links to single content pages. It is the _index file in a folder of files which are single pages. It is like a secctions.
hugo new \_index.md // home page
hugo new post/_index.md // list page
hugo new post/post1.md // single page
hugo new post/post2.md // single page
hugo server -D // For run draft pages.
Layouts is the skeleton of how this single pages, list pages, home page will be displayed.
Front Matter
Front Matter is a list of information that describe the attributes about content page. It is what we call meta-data, it’s data about data. When you think about it, human beings have their own type of front matter, things like name, age, height weight social security number, all describe us. In a way all of these things are our front matter.
But for a hugo content page, front matters let’s us give each individual page certain attributes that we can use elsewhere (like in layouts) to make the website more complex.
Front Matter can be encoded in 3 different markup languajes like YAML, TOML, JSON.
example:
<html>
<head>
<meta charset="UTF-8">
<title>{{ .Params.Title }}</title>
</head>
<body>
<p>Written By : {{ .Params.Author }}</p>
{{ .Content }}
</body>
</html>
Notice in the code above that we’re inserting the title parameter into the HTML title tags and the Author parameter into the Written By paragraph. To access page front matter you open and close two sets of curly braces, and access the variable. In this case we’re using .Params.Title and .Params.Author to access this data. .Params gives you access to all parameters in the front matter, and you can specify which one you want by using it’s name.
Front Matter is defined in the config.toml file and these parameters will be used in layaots. For example, those parameter will be accessed by .Params.name and this name is a configuration on config.toml file.
Archetypes
Basically, archetypes is the default template for front matter. When we create a new page, it will inherit all the parameters which is configure in the default template located in archetype folder.
We can create diferent archetypes according each seccion. For example, we can create an archetypes for post seccion whcih include autor parameter, but for project seccion not.
Built-in Shortcodes
In your content files, a shortcode can be called by calling a Shortcode parameters are space delimited, and parameters with internal spaces can be quoted.
Taxonomies
It is related how we group content together using tag keyword or categories keyword
One example for content md files:
---
title: Getting started
description: Getting started with personal-web
date: "2019-05-03T09:37:55+02:00"
publishDate: "2019-05-03T09:37:55+02:00"
tag: ["tag1", "tag2", "tag2"]
categories: ["cat1", "cat2"]
moods:["Happy", "Upbeat"]
---
And some of taxonomies are created by default and this configuration needs to be done on config.toml:
[taxonomies]
tag = "tags" # This is default taxonomy. It does not need to be declarated here.
category = "categories" # This is default taxonomy. It does not need to be declarated here.
mood = "moods" # This is new taxonomy
languages = "languages" # This is new taxonomy
Taxonomies also can be used for group different folders with different contents. We only need to range(iterate over) .Site.Taxonomies.
{{ range .Site.Taxonomies.languages.english }}
// in here we can access the page’s information
{{ .Title }}
{{ .Description }}
{{ end }}
Template basics
Hugo templates is related to html, css coding.
Templates in hugo needs to differentiate 2 things:
list pages: home directory, post directory, sections, single pages: article, a particula page on a directory.
all list pages use the same template, but the content is different. all single pages use the same template, but the content of each article is different.
Each especific template has one unique sketleton. Any template is store in layour forder:_default folder, partial folder
layout directory
{{ partial "header" .}}
<h1 id="title"> {{ .Title }}</h1>
<p>{{ .Content }}</p>
<ul id="list">
{{ range .Pages }}
{{ .Render "li" }}
{{ end }}
</ul>
{{ partial "footer" .}}
List page templates
Template for list pages:
First part: Inside each directory of content directory, there is a _index.md file which is the content of the list pages referenced by {{.Content}}.
Second part: Inside the layout directory, there is _default directory which contain list.html file which define the skeleton of list pages
{{ partial "header" .}} // this part uses partial for header
<h1 id="title"> {{ .Title }}</h1>
<p>{{ .Content }}</p> // Here specify the content of _index.md files
<ul id="list">
{{ range .Pages }} // range is like a for. It is an iterative instruccion to go for all single pages and extract or .Render each one.
{{ .Render "li" }}
{{ end }}
</ul>
{{ partial "footer" .}} // this part uses partial for footer
Single page templates
Template for single pages:
First part: Inside each directory of content directory, for example post directory, there is a post.md file which is the first article and it’s content is referenced by {{.Content}}.
Second part: Inside the layout directory, there is _default directory which contain single.html file which define the skeleton of single pages
{{ partial "header" .}}
<h1>{{ .Title | markdownify }}</h1> // Display the title of the post.md file related to the front matter.
{{ .Content | markdownify }} // Display the content of the post.md file
{{ partial "footer" .}}
Home page templates
The home template is a list template but has an especial file which control it. It is store on layout folder and in the file index.html:
{{ partial "header" .}}
<h1>{{ .Title | markdownify }}</h1>
{{ .Content }}
<h2>{{ .Site.Params.main.latestPublishHeader | default "My Latest Job" }}</h2>
{{ $pages := where site.RegularPages "Type" "in" .Site.Params.mainSections }}
{{ range first 1 $pages }}
{{ if in .Site.Params.mainSections "portfolio" }}
{{ partial "portfolio/item" .}}
{{ else if in .Site.Params.mainSections "post" }}
{{ partial "post/item" .}}
{{ end }}
{{ end }}
{{ partial "footer" .}}
Section templates
Section template is for creating an specific list or single page for a seccion like post folder.
Block templates
This is block that acts as the overarching template for the entire hugo website. It is located on layout/_default/baseof.html
<!DOCTYPE html>
<html>
{{- partial "head.html" . -}}
<body>
{{- partial "header.html" . -}}
<div id="content">
{{- block "main" . }}{{- end }}
</div>
{{- partial "footer.html" . -}}
</body>
</html>
And this block can be referenced by {{block “main” .}} and {{end}} and this has to be put on the list or single pages.
Variables
Variables is a piece of your information. Variables only can be used on layaout folder inside single.html or list.html.
sintax:
{{ <name of variable>}}
example:
{{ .Title }}
{{ .Date }}
{{ .URL }} // display the URL of the page
//For access a custom front matter variable
//we need to use ".Params" parameter following of custom variable ".myVar".
{{ .Params.myVar }}
// Custom variable
{{ $myVarName := "astring" }}
// The usage of this variable
{{ $myVarName }}
// we use the new variable inside html code
<h1> {{ $myVarName }} </h1>
// "color" is a new custom variable on front matter(config.toml).
<h1 style = "color: {{ .Params.color }};"> {{ $myVarName }} </h1>
Site Variables
Hugo provides built-in variables for convenient access to global values in your templates.
// array of all content ordered by date.
.Site.Pages
// a shortcode to the regutar page collection
// .Site.RegularPages is equivalent to where .Site.Pages "Kind" "page"
.Site.RegularPages
// It is a container holding the values from the params section of your site configuration.
.Site.Params
// config.toml:
[params]
author = 'Nikola Tesla'
description = "Tesla's Awesome Hugo Site"
// usage:
<meta name="description"
content="{{if .IsHome}}
{{ $.Site.Params.description }}
{{else}}
{{.Description}}
{{end}}" />
The .Site.Pages has an special meaning:
-
A regular page is a “post” page or a “content” page.
- A leaf bundle is a regular page.
-
A list page can list regular pages and other list pages. Some examples are: homepage, section pages, taxonomy (/tags/) and term (/tags/foo/) pages.
- A branch bundle is a list page.
-
.Site.Pages:
Collection of all pages of the site: regular pages, sections, taxonomies, etc. – Superset of everything! -
.Site.RegularPages:
Collection of only regular pages.
Compared to .Pages and .RegularPages:
- .Pages:
Collection of regular pages and only first-level section pages under the current list page. - .RegularPages
Collection of only regular pages under the current list page. This excludes regular pages in nested sections/list pages (those are subdirectories with an _index.md file.
Functions
Piece of code pre-rended.
sintax:
{{funcName param1 param2}}
examples:
{{ truncate 10 "You are my love or loves"}} // truncate at 10 letters
{{ sub 1 5}} // substract 1-5=-4
{{ singularize "dogs"}}
#######################
// range function:
{{ range .Pages }} // .Pages all pages in the current section
{{ .Title }} <br>
{{ end }}
#######################
// delimit function:
// loops through any array, slice, or map and returns a
// string of all the values separated by a delimeter
sintax:
delimit COLLECTION DELIMIT LAST
or
{{ delimit array/slice/map delimiter optionallastdelimiter}}
//config.toml
+++
title: I love Delimit
tags: [ "tag1", "tag2", "tag3" ]
+++
//usage:
<p>Tags: {{ delimit .Params.tags ", " }}</p>
//output:
<p>Tags: tag1, tag2, tag3</p>
#######################
// where function:
// filters an array to only the elements containing a matching value for a given field.
sintax:
where COLLECTION KEY [OPERATOR] MATCH
{{ range where .Pages "Section" "foo" }}
{{ .Content }}
{{ end }}
// with config.toml:
+++
series: golang
+++
// usage:
{{ range where .Site.Pages "Params.series" "golang" }}
{{ .Content }}
{{ end }}
// with logical operators:
// = iqual, != different and so on.
{{ range where .Pages "Section" "!=" "foo" }}
{{ .Content }}
{{ end }}
#######################
// markdownify function:
// runs the provided string through the markdown processor:
sintax:
markdownify INPUT
// usage:
{{ .Title | markdownify }}
#######################
// .Render function:
// takes a view to apply when rendering content
sintax:
.Render LAYOUT
// note: the view is an alternative layout and should
// be binded to a file name that points to a template.
// This example could render a piece of content
// using the content view located at /layouts/_default/summary.html:
// usage:
{{ range .Pages }}
{{ .Render "summary"}}
{{ end }}
#######################
// .Get function:
// Accesses positional and ordered paramters n shortcode declaration
sintax:
.Get INDEX
.Get KEY
{{ $quality := default "100" (.Get 1) }}