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: {[0xc0014ee580] [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:0xc0014ee480 directory-structurehttpsgohugoiogetting-starteddirectory-structure:0xc0014ee5c0 draft-future-and-expired-contenthttpsgohugoiogetting-startedusagedraft-future-and-expired-content:0xc0014eed80 front-matterhttpsgohugoiocontent-managementfront-matter:0xc0014eed00 frontmatter-accessors:0xc0014eeec0 layouts_defaultsbaseofhtml:0xc0014ee740 layouts_defaultshomehtml:0xc0014eea40 layouts_defaultslisthtml:0xc0014ee840 layouts_defaultssinglehtml:0xc0014ee940 layoutspartialsmenuhtml:0xc0014eec40 layoutspartialstermshtml:0xc0014eeb40 page-methodshttpsgohugoiomethodspage:0xc0014eee00 themes:0xc0014eef80 types:0xc0014ee6c0 union-file-systemhttpsgohugoiogetting-starteddirectory-structureunion-file-system:0xc0014ee640]}
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.