Hugo
Creating a basic skeleton
At time of writing, this is a bit of a schlep because the recommended command
hugo new site whatever_name
does not produce any basic layouts files to get a newbie started. So rather run
hugo new theme whatever_name
which will produce themes/whatever_name. Then do
mv themes/whatever_name .
rmdir themes
then
cd whatever_name
hugo server
will bring up a simple Hugo site on http://localhost:1313 you can start altering to your taste.
Understanding where Hugo is fetching the title, menu, summaries etc from requires diving into the basic directory structure.
Directory structure
A cool recent feature of Hugo is it’s ability to render ASCII art as SVG using GoAT, and I’ve used that to prettify the output of tree.
The starting project created as above looks like so:
Union file system
If you think you need a symbolic link in your project directory, use Hugo’s union file system instead.
I discovered the above the hardway. I wanted to use common layout files across several sites, and thought I’d do this the traditional Unix way with symbolic links. While this worked for layouts, when I tried to do this with content I got weird bugs because some “softlinked” files were ignored by Hugo.
Exactly what I wanted to achieve is covered by Hugo’s modules which I initially found incomprehensible because it’s built on Go’s module system, requiring a go.mod file and complicated pathnames like github.com/my/repo which is weird if you’re not using github.
Anyways, it turns out none of that is necessary if you simply add a {"module": { "mounts": ...}} section to your site configuration file as described in Union file system.
An advantage over symbolic links is global files can be kept in the module’s directories and local files in the given site’s directories.
Types
Object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
layouts/_defaults/baseof.html
<!DOCTYPE html>
<html lang="{{ or site.Language.LanguageCode site.Language.Lang }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
<head>
{{ partial "head.html" . }}
</head>
<body>
<header>
{{ partial "header.html" . }}
</header>
<main>
{{ block "main" . }}{{ end }}
</main>
<footer>
{{ partial "footer.html" . }}
</footer>
</body>
</html>
layouts/_defaults/list.html
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ .Content }}
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ end }}
{{ end }}
layouts/_defaults/single.html
{{ define "main" }}
<h1>{{ .Title }}</h1>
{{ $dateMachine := .Date | time.Format "2006-01-02T15:04:05-07:00" }}
{{ $dateHuman := .Date | time.Format ":date_long" }}
<time datetime="{{ $dateMachine }}">{{ $dateHuman }}</time>
{{ .Content }}
{{ partial "terms.html" (dict "taxonomy" "tags" "page" .) }}
{{ end }}
layouts/_defaults/home.html
{{ define "main" }}
{{ .Content }}
{{ range site.RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ end }}
{{ end }}
layouts/partials/terms.html
{{- /*
For a given taxonomy, renders a list of terms assigned to the page.
@context {page} page The current page.
@context {string} taxonomy The taxonony.
@example: {{ partial "terms.html" (dict "taxonomy" "tags" "page" .) }}
*/}}
{{- $page := .page }}
{{- $taxonomy := .taxonomy }}
{{- with $page.GetTerms $taxonomy }}
{{- $label := (index . 0).Parent.LinkTitle }}
<div>
<div>{{ $label }}:</div>
<ul>
{{- range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{- end }}
</ul>
</div>
{{- end }}
layouts/partials/menu.html
{{- /*
Renders a menu for the given menu ID.
@context {page} page The current page.
@context {string} menuID The menu ID.
@example: {{ partial "menu.html" (dict "menuID" "main" "page" .) }}
*/}}
{{- $page := .page }}
{{- $menuID := .menuID }}
{{- with index site.Menus $menuID }}
<nav>
<ul>
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
</ul>
</nav>
{{- end }}
{{- define "partials/inline/menu/walk.html" }}
{{- $page := .page }}
{{- range .menuEntries }}
{{- $attrs := dict "href" .URL }}
{{- if $page.IsMenuCurrent .Menu . }}
{{- $attrs = merge $attrs (dict "class" "active" "aria-current" "page") }}
{{- else if $page.HasMenuCurrent .Menu .}}
{{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
{{- end }}
{{- $name := .Name }}
{{- with .Identifier }}
{{- with T . }}
{{- $name = . }}
{{- end }}
{{- end }}
<li>
<a
{{- range $k, $v := $attrs }}
{{- with $v }}
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
{{- end }}
{{- end -}}
>{{ $name }}</a>
{{- with .Children }}
<ul>
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
</ul>
{{- end }}
</li>
{{- end }}
{{- end }}
Front Matter
Draft, future, and expired content
Something I and probably many other newbies tripped over was that getting the values wrong in any of these 4 key-value pairs prevents the page from rendering.
- The draft value is true
- The date is in the future
- The publishDate is in the future
- The expiryDate is in the past
Page Methods
Frontmatter Accessors
PAGE.Date 2024-01-15 13:34:29 +0200 +0200
PAGE.ExpiryDate 0001-01-01 00:00:00 +0000 UTC
PAGE.PublishDate 2024-01-15 13:34:29 +0200 +0200
PAGE.Lastmod 2024-04-12 11:09:09 +0200 +0200
PAGE.Draft false
PAGE.GetTerms "artists" Pages(0)
PAGE.Title Hugo
PAGE.LinkTitle hugo
PAGE.Params map[date:2024-01-15 13:34:29 +0200 +0200 draft:false iscjklanguage:false lastmod:2024-04-12 11:09:09 +0200 +0200 linktitle:hugo publishdate:2024-01-15 13:34:29 +0200 +0200 title:Hugo]
PAGE.Sitemap { -1 sitemap.xml false}
PAGE.Aliases []
Links
PAGE.Permalink https://frontiersoftware.co.za/html-tools/hugo/
PAGE.RelPermalink /html-tools/hugo/
PAGE.GitInfo
.AuthorDate 2024-04-12
.CommitDate 2024-04-12
.AuthorEmail robert.joeblog@gmail.com
.AuthorName Robert Laing
.Subject added jq section
PAGE.CodeOwners: []
PAGE.Kind: section
PAGE.Type: html-tools
PAGE.BundleType: branch
PAGE.AllTranslations: Pages(1)
PAGE.AlternativeOutputFormats: [{alternate {rss application/rss+xml index alternate false false true false false false false 0} /html-tools/hugo/index.xml https://frontiersoftware.co.za/html-tools/hugo/index.xml}]
PAGE.Content
PAGE.CurrentSection: /home/roblaing/webapps/frontiersoftware/content/html-tools/hugo/_index.md
PAGE.Data
PAGE.Eq
PAGE.File: _index
PAGE.FirstSection: /home/roblaing/webapps/frontiersoftware/content/html-tools/_index.md
PAGE.Fragments: {[0xc0026898c0] [creating-a-basic-skeleton directory-structurehttpsgohugoiogetting-starteddirectory-structure draft-future-and-expired-contenthttpsgohugoiogetting-startedusagedraft-future-and-expired-content front-matterhttpsgohugoiocontent-managementfront-matter frontmatter-accessors layouts_defaultsbaseofhtml layouts_defaultshomehtml layouts_defaultslisthtml layouts_defaultssinglehtml layoutspartialsmenuhtml layoutspartialstermshtml page-methodshttpsgohugoiomethodspage themes types union-file-systemhttpsgohugoiogetting-starteddirectory-structureunion-file-system] map[creating-a-basic-skeleton:0xc0026897c0 directory-structurehttpsgohugoiogetting-starteddirectory-structure:0xc002689900 draft-future-and-expired-contenthttpsgohugoiogetting-startedusagedraft-future-and-expired-content:0xc0020a0280 front-matterhttpsgohugoiocontent-managementfront-matter:0xc0020a0200 frontmatter-accessors:0xc0020a03c0 layouts_defaultsbaseofhtml:0xc002689a80 layouts_defaultshomehtml:0xc002689ec0 layouts_defaultslisthtml:0xc002689cc0 layouts_defaultssinglehtml:0xc002689dc0 layoutspartialsmenuhtml:0xc0020a0140 layoutspartialstermshtml:0xc0020a0040 page-methodshttpsgohugoiomethodspage:0xc0020a0300 themes:0xc0020a0480 types:0xc002689a00 union-file-systemhttpsgohugoiogetting-starteddirectory-structureunion-file-system:0xc002689980]}
PAGE.FuzzyWordCount : 0
PAGE.GetPage PATH
PAGE.HeadingsFiltered: []
PAGE.OutputFormats: [{canonical {html text/html index canonical false true false false false false true 10} /html-tools/hugo/ https://frontiersoftware.co.za/html-tools/hugo/} {alternate {rss application/rss+xml index alternate false false true false false false false 0} /html-tools/hugo/index.xml https://frontiersoftware.co.za/html-tools/hugo/index.xml}]
PAGE.Resources: [skeleton_home.png]
Pages Methods
Sort Orders
Inserting strings is called interpolation. Extracting substrings could be called extrapolation.
Some common synonyms of interpolate are insert, insinuate, intercalate, interject, interpose, and introduce. While all these words mean “to put between or among others,” interpolate applies to the inserting of something extraneous or spurious. https://www.merriam-webster.com/thesaurus/interpolate
Themes
assets
Global resources are kept in the assets directory.
I initially didn’t get the advantage of putting CSS and JS files in the assets directory rather than the static directory and found it a little confusing that the reason is explained in Hugo Pipes which are unrelated to the | operator in template functions which are called Go Pipes.
Before discovering the advantages of the assets folder over static, I had a problem that browsers wouldn’t load upload style and script files. Filenames in the assets folder get a unique fingerprint (aka hashes) when they are changed. It also allows translation of style and JS files from other languages if desired, and minification.
modules
Modules
A Hugo module is a go module, so requires the same steps:
mkdir mymod
cd mymod
hugo mod init mymod
go: creating new go.mod: module mymod
Hugo Modules: everything you need to know!
Working with Hugo Module Locally
hugo mod init github.com/gohugoio/myShortcodes
Configuration
{
"module": {
"noProxy": "none",
"noVendor": "",
"private": "*.*",
"proxy": "direct",
"replacements": "",
"vendorClosest": false,
"workspace": "off",
"hugoVersion": {
"extended": false,
"max": "",
"min": ""
},
"imports": [
{
"disable": false,
"ignoreConfig": false,
"ignoreImports": false,
"path": "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
},
{
"path": "my-shortcodes"
}
],
"mounts": [
{
"source": "content",
"target": "content"
},
{
"source": "static",
"target": "static"
},
{
"source": "layouts",
"target": "layouts"
},
{
"source": "data",
"target": "data"
},
{
"source": "assets",
"target": "assets"
},
{
"source": "i18n",
"target": "i18n"
},
{
"source": "archetypes",
"target": "archetypes"
}
]
}
}
path Can be either a valid Go Module module path, e.g. github.com/gohugoio/myShortcodes, or the directory name for the module as stored in your themes folder.
menus
Directory traversal
I’ve developed my own homegrown way of recursively walking a Hugo site’s content tree as described in this discourse thread since the official way of putting the menu in the site config file isn’t what I want as I add and remove pages.
With more experience, I changed the deprecated template with an inline partial
My code for layouts/partials/menu.html looks like this:
<nav>
{{ partial "inline/walk.html" (dict "dir" .Site.Home.Pages) }}
{{ define "partials/inline/walk.html" }}
<ol>
{{ range .dir }}
{{ if (eq .BundleType "branch") }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a>
{{ partial "inline/walk.html" (dict "dir" .Pages) }}
</li>
{{ else }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
{{ end }}
</ol>
{{ end }}
</nav>
Section menu
Hugo’s default menu system requires everything to be manually entered into the system configuration file.
branch
Sections vs Taxonomies
An imortant difference between content/mysection and content/mytaxonony is there may not be an _index.md file in a taxonomy whereas there should be for a section.
leaf
Files named index.md (as opposed to _index.md) are leaves, and use layouts/single.html as their template.