Day: December 28, 2021

Learning – Hugo – Static Site Generator

Posted on by Bian Xi Leave a Comment on Learning – Hugo – Static Site Generator

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.

  • Restart hugo server

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