Learning - Hugo - Static Site Generator
Installation
Windows
hugo version
MacOS
-
Install Homebrew
-
Install hugo
brew install hugo
hugo version
Create a new site
hugo new site <site_name>
Then the folder created.
Site contents
- archetypes - data type
- content
- data
- layouts
- static
- themes
- config.toml
Theme
theme = "ga-hugo-theme"
Create content
hugo new a.md
hugo new dir1/b.md
Run hugo in draft mode
hugo server -D
Single content
Display one page content.
List content
List other single contents in the page. The list page for Level 1 directories are automatically created hugo.
Manually create list page
Force hugo create list page, create _index.md file in the directory, and update the content of _index.md file will show on the list page
hugo new dir1/dir2/_index.md
Front Matter
YAML
---
title: "title"
date: 2017-...
draft: true
---
TOML
+++
title = "title"
date = 2017-...
draft = true
+++
Archetypes
The file archetypes/default.md has the template of new files.
---
tltle: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---
The template file can be named as directory name, such as dir1.md, it will be used for contents created in dir1
hugo new dir1/b.md
Shortcodes
The predefined shortcodes can be found in hugo shortcode page, it also can be customized using shortcode template.
{{< youtube w7Ft2ymGmfc >}}
Taxonomies
Tags and categories
---
tags: [ "tag1", "tag2", "tag3"]
categories: [ "cat1"]
---
The tags and categories will be shown in contents if using learning theme.
Access tags and categories from page
https://localhost:1313/tags/tag1/
https://localhost:1313/categories/cat1/
Custome taxonomy
In content file
---
Moods: [ "Happy", "Upbeat" ]
---
In config.toml file
[taxonomies]
tag = "tags"
category = "categories"
mood = "moods"
Note: If taxonomies session exists in config.toml file, then tag and category also must be included.
Template Basics
Theme template
Templates are in themes/ga-hugo-theme/layouts/_default. The list.html is for list page, the single.html is for single page.
Custome template
List page
Create in layouts/_default/list.html
<html>
<head>
<meta charset="UTF-8">
<title>Document</title>
</head>
<body>
{{.Content}}
<ul>
{{ range .Pages }}
<li><a href="{{.URL}}">{{.Title}}</a></li>
{{end}}
</ul>
</body>
</html>
Single page
Create in layouts/_default/page.html
<html>
<head>
<meta charset="UTF-8">
<title>Document</title>
</head>
<body>
<h1>Header</h1>
<h3>{{.Title}}</h3>
<h4>{{.Date}}</h4>
{{.Content}}
<h2>Footer</h2>
</body>
</html>
Home page
Home page is a special list page. Create in layouts/index.html.
Section template
Create in layouts/_default/<dir_name>/single.html, which replace the template for files in <dir_name>.
Base Templates & Blocks
Create in layouts/_default/baseof.html, it is the template for all pages.
<html>
<head>
<meta charset="UTF-8">
<title>Document</title>
</head>
<body>
Top of baseof
<hr>
{{ block "main" . }}
{{end}}
{{ block "footer" . }}
<br>
{{end}}
<hr>
Bottom of baseof
</body>
</html>
The create layouts/_default/single.html
{{ define "main" }}
This is the single template
{{end}}
{{ define "footer" }}
This is the single footer
{{end}}
The create layouts/_default/list.html
{{ define "main" }}
This is the list template
{{end}}
Note: no overwrite in layouts/_default/list.html for footer.
Variables
Hugo variables only can be used in templates in layout.
For example:
<h1 style="color: {{ .Params.color }}">Single Template</h1><hr><br>
{{ .Title }} {{ .Date }} {{ .URL }}
{{ .Params.myVar }}
The myVar and color are custom variables defined in markdown file
---
myVar: "myValue"
color: "blue"
---
Define in template
{{ $myVarName := "string value" }}
<h1>{{ $myVarName }}</h1>
https://gohugo.io/variables
Function
Hugo functions only can be used in templates in layout.
{{ funcName param1 param2 }}
For example:
{{ truncate 10 "This is a very long string" }}
{{ add 1 5 }}
{{ sub 1 5 }}
{{ singularize "dogs" }}
{{ range .Pages }}
{{ .Title }} <br>
{{ end }}
https://gohugo.io/functions
If Statements
{{ $var1 := "dog" }}
{{ $var2 := "cat" }}
{{ if not (eq $var1 $var2) }}
True
{{ else if ... }}
{{ else }}
False
{{ end }}
{{ if and (lt $var1 $var2) (lt $var1 $var3) }}
eq
lt
le
gt
ge
not
{{ $title := .Title }}
{{ range .Site.Pages }}
<li><a href="{{.URL}}" style="{{ if eq .Title $title }} background-color:yellow; {{end}}">{{.Title}}</a></li>
{{ end }}
Data Files
The JSON, YAML, TOML files, for example, data/states.json
{{ range .Site.Data.states }}
{{.name}} <br> {{.capital}}
{{end}}
Partial Templates
Header, footer, etc. Create file in layouts/partials/header.html
<h1>{{.Title}}</h1>
<p>{{.Date}}</p>
<hr>
<br>
In layouts/_default/single.html
{{ partial "header" . }}
<h1>Single Template</h1><hr><br>
Note: The . after "header" is indicating the entire scope of variables.
Custom dictionary
<h1>{{.myTitle}}</h1>
<p>{{.myDate}}</p>
<hr>
<br>
In layouts/_default/single.html
{{ partial "header" (dict "myTitle" "myCustomTitle" "myDate" "myCustomDate")}}
<h1>Single Template</h1><hr><br>
Note: It is the same as myTitle := myCustomTitle, myDate := myCustomDate
Shortcode Templates
Shortcode is used in markdown file, created in layouts/shortcodes.
Using variable name
For example, layouts/shortcodes/myshortcode.html
This is my shortcode file.
<p style="color: {{.Get `color`}}">This is the frameworks text</p>
Note: the " is replaced to "`"
In markdown file
{{< myshortcode color="blue">}}
Using variable number
For example, layouts/shortcodes/myshortcode.html
This is my shortcode file.
<p style="color: {{.Get 0}}">This is the frameworks text</p>
Note: the " is replaced to "`"
In markdown file
{{< myshortcode blue >}}
Multiple lines
In markdown file
{{< myshortcode >}}
This is the text inside the shortcode tags
{{< /myshortcode >}}
In template file
<p style="background-color: yellow;">{{.Inner}}</p>
If you want to use markdown in shortcode, do follow
{{% myshortcode %}}
**bold text**
{{% /myshortcode %}}
Building your site
huge server -D
If you just want to build the site into public folder
huge
Note: delete public folder first.
References
Hugo - Static Site Generator | Tutorial
