Hugo on Bitsy Wiki

Content Organization

Mon, 01 Jan 0001 00:00:00 +0000

The content/ directory is the site map. Hugo derives every URL from the file path: content/docs/guide/alpha.md is served at /docs/guide/alpha/, with the content/ prefix and the .md suffix dropped and a directory containing index.html written for it. There is no routing table and no place to declare a URL other than the file’s own location, which is what makes renaming a page a link-breaking operation rather than a configuration change.

Template Lookup

Mon, 01 Jan 0001 00:00:00 +0000

Every page Hugo renders is matched against an ordered list of candidate template paths, and the first one that exists wins. The list is generated from the page itself — its kind, its type, its section, its output format, its language, and any layout in its front matter — so nothing declares which template a page uses. The page’s attributes and the set of files on disk decide it between them.

Themes and Modules

Mon, 01 Jan 0001 00:00:00 +0000

A Hugo theme is a project directory with the same shape as yours — layouts/, assets/, static/, i18n/, data/, archetypes/, and often content/ — mounted underneath your own. Hugo merges the two trees into one filesystem before the build starts, so from a template’s point of view there is a single layouts/ and a single assets/. Every question about “how do I change this theme” reduces to a question about that merge.

Shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

A shortcode is a template callable from inside Markdown. Markdown has no syntax for a figure with a caption, a tabbed panel, or a list of child pages; a shortcode supplies one, keeping the content file readable while the HTML lives in a template where it can be changed once for every page that calls it.

`1`	`{{< section >}}`

That line, at the bottom of 28 of this wiki’s 35 section indexes, renders the list of child pages. The template behind it is layouts/_shortcodes/section.html in the hugo-book theme, whose first statement is a warnf announcing its own deprecation — a shortcode is a template like any other, and a theme can retire one by printing a warning from inside it.

Render Hooks

Mon, 01 Jan 0001 00:00:00 +0000

A render hook is a template that replaces Goldmark’s output for one kind of Markdown construct, everywhere it appears. Write layouts/_markup/render-image.html and every image on the site — in every page, from every author, past and future — renders through it. The content files do not change and do not learn anything about the site’s HTML.

{{/* layouts/_markup/render-image.html */}}
<figure>
  <img src="{{ .Destination | safeURL }}" alt="{{ .PlainText }}" loading="lazy">
  {{ with .Title }}<figcaption>{{ . }}</figcaption>{{ end }}
</figure>

The hooks#

File	Fires on
`render-link.html`	inline links
`render-image.html`	images
`render-heading.html`	headings
`render-blockquote.html`	blockquotes, including alert syntax
`render-codeblock.html`	fenced code blocks
`render-codeblock-<lang>.html`	fenced blocks with that language tag
`render-table.html`	tables
`render-passthrough.html`	passthrough snippets, typically math

All of them live in layouts/_markup/, in the project or in a theme, and follow the same lookup rules as any other template — a project file at the same path shadows the theme’s.

Hugo Pipes

Mon, 01 Jan 0001 00:00:00 +0000

Hugo Pipes is the asset pipeline: files under assets/ are fetched as resource objects, passed through transformations, and published under a name the pipeline chooses. Nothing here is a separate build step or a watch process. It is a chain of template functions evaluated while the page that references the asset is rendered.

1
2

{{ $css := resources.Get "css/main.scss" | css.Sass | minify | fingerprint }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}">

That produces:

1
2
3

<link rel="stylesheet"
      href="/css/main.min.ce323643df844223c686fbca413cedc8c01bb90845c8224e83a37497388d84ac.css"
      integrity="sha256-zjI2Q9+EQiPGhvvKQTztyMAbuQhFyCJOg6N0lziNhKw=">

The Sass was transpiled, the result minified, and the published filename given a SHA-256 digest of the contents. fingerprint also fills .Data.Integrity with the same digest in the format the integrity attribute wants — subresource integrity (SRI), which makes the browser refuse a stylesheet that does not hash to the expected value.

Internal Links

Mon, 01 Jan 0001 00:00:00 +0000

Hugo does not validate internal links. A Markdown link to a page that does not exist is copied into the HTML exactly as written, the build succeeds, and the exit status is zero:

`1`	`[dead](/docs/guide/nope)`

`1`	`<a href="/docs/guide/nope">dead</a>`

No warning is logged. Forcing on the embedded link render hook does not change the outcome — it resolves destinations it recognizes and passes the rest through untouched, so [q](nope.md) also ships as href="nope.md". Resolution and validation are different jobs, and Hugo only does the first.

Building and Deploying

Mon, 01 Jan 0001 00:00:00 +0000

hugo writes the finished site into public/ and stops. There is no deploy step in Hugo, and no server component to install: the artefact is a directory of files, and every host that can serve a directory of files can serve it. Deployment is therefore a copy, and the hosting bill is bandwidth.

hugo                          # build into public/
hugo --minify                 # minify HTML, XML, CSS, JS on the way out
hugo --gc                     # prune unreferenced cache entries afterwards
hugo --cleanDestinationDir    # delete output files no longer generated
hugo -d dist                  # write somewhere other than public/

--cleanDestinationDir matters after a rename. Hugo writes what the content produces and leaves everything else alone, so a page moved from /wiki/old/ to /wiki/new/ leaves the old directory sitting in public/ and, on a host that syncs rather than replaces, sitting in production. public/ is safe to delete before any build for the same reason.