a short introduction to Hugo
Recently Andreas has migrated our website from Wordpress to Hugo and after that i have written this small introduction for a TLUG workshop. The article describes the basic installation and configuration steps plus the creation of the first content.
- static website generator that
- supports separation of content and code with themes
- renders your content into static html pages with css and optional javascript integration
- can be fully automated with the tool (Ansible, Jenkins, Helm etc.) of your choice
- is written in Go and released as static binary
- to simplify webserver infrastructures by avoiding
- databases like MySQL
- server side program languages like PHP
- caching components like Redis
- the official documentation describes the installation
- from source
- using a Github release for several operating systems and cpu infrastructures
- for Windows and other operating systems with the related package managers
- with homebrew for MacOS
brew install hugo
- create the website folder structure
- choose a theme and create the folder for it
- download and extract the theme into the folder
hugo new site --source ./ test.batchworks.de
mkdir -p test.batchworks.de/themes/hugo-geekdoc/
curl -sL https://github.com/thegeeklab/hugo-geekdoc/releases/download/v0.19.1/hugo-geekdoc.tar.gz | tar -xz -C test.batchworks.de/themes/hugo-geekdoc/
- extend the hugo configuration (config.toml) with the desired options
- this also includes some theme related options
- Theme options are not namespaced. This makes it sometimes hard to switch between them
baseurl = "http://test.batchworks.de/"
languageCode = "en-us"
title = "test.batchworks.de"
theme = "hugo-geekdoc"
[permalinks]
posts = "/:title/"
page = "/:slug/"
## geekdoc theme settings
# Required to get well formatted code blocks
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
enableGitInfo = false
[markup]
[markup.goldmark.renderer]
unsafe = true
[markup.tableOfContents]
startLevel = 1
endLevel = 9
[taxonomies]
author = "authors"
tag = "tags"
## geekdoc theme settings end
# Theme variables
#
[params]
# Site author
author = "Birk Bohne"
geekdocBreadcrumb = false
# Format dates with Go's time formatting
date_format = "Mon Jan 02, 2006"
- Hugo pages or posts are written in Markdown with some theme specific header config
- create the first page in the test.batchworks.de/content/_index.md file and add the content
---
title: Welcome to the test site
geekdocDescription: This is the start page.
weight: 10
---
# The start page
Welcome to the start page
- start hugo in server mode to locally render the content
hugo server --source test.batchworks.de/ --baseUrl http://localhost
Start building sites …
hugo v0.88.1+extended darwin/amd64 BuildDate=unknown
| EN
-------------------+------
Pages | 7
Paginator pages | 0
Non-page files | 0
Static files | 105
Processed images | 0
Aliases | 2
Sitemaps | 1
Cleaned | 0
Built in 31 ms
- check the result within a browser by opening http://localhost:1313/
- paste the content of the README.md below the theme config section in the test.batchworks.de/content/_index.md file
- check your browser
- create a test.batchworks.de/content/sub/ folder and an _index.md file in it
- add the content
---
title: Sub content
geekdocDescription: focus on other topics
weight: 10
---
the sub page
- check your browser again
- the Geekdoc theme supports Mermaid for the rendering of different chart types
- create a test.batchworks.de/content/sub/mermaid.md file
- add the content
---
title: Mermaid charts
geekdocDescription: render charts with mermaid markup code
weight: 10
---
{{< mermaid class="text-center">}}
flowchart TD
A[Start] --> B{Is it?};
B -->|Yes| C[OK];
C --> D[Rethink];
D --> B;
B ---->|No| E[End];
{{< /mermaid >}}
- check your browser again
- Hugo can read data structures for instance from JSON or YAML
- this can be used to populate tables or other html structures
- First we have to create the html template
- create a test.batchworks.de/layouts/shortcodes/data_table.html file
- add the content
{{ $arg0 := .Get 0 }}
{{ $data := index .Site.Data.content $arg0 }}
{{ $.Scratch.Set "count" 0 }}
<table>
<thead>
<tr>
<th>Name</th>
<th>Function</th>
</tr>
</thead>
<tbody>
{{ range $datacontent := $data }}
<tr>
<td>{{ $datacontent.name }}</td>
<td>{{ $datacontent.function }}</td>
</tr>
{{ end }}
</tbody>
</table>
- Next we have to create the data source
- create a test.batchworks.de/data/content/data.yaml file
- add the content
- name: "json"
function: "read JSON"
- name: "csv"
function: "read CSV"
- Now we create the page that should render the table
- create a test.batchworks.de/content/sub/table.md file
- add the content
---
title: Data tables
geekdocDescription: render tables
weight: 20
---
## Data sources
{{< data_table "data" >}}
- check your browser again
- use Hugo to render the static pages
- they can than be served by the webserver of your choice without further dependencies
- create a target and a tmp dir
- call hugo to render the pages
mkdir -p tmp/ www/
hugo --source ${PWD}/test.batchworks.de/ --cacheDir ${PWD}/tmp --destination ${PWD}/www --baseURL http://test.batchworks.de
- maintain the Hugo config and content in a source code management system
- maintain the rendered pages in an SCM too
- upload the www folder to your web server
- use automation tools like Ansible, Jenkins etc. to automate the workflow