Hugo Cheat Sheet

Note

This site is built with Hugo (extended) and the Hextra theme, pulled in as a Hugo module. Everything below is written against that setup.

Daily commands

Task	Command
Dev server with drafts, auto-reload	`hugo server -D`
Dev server reachable from another machine	`hugo server --bind 172.20.150.182 --baseURL http://172.20.150.182`
Dev server with future-dated pages	`hugo server -D -F`
Production build (what the host runs)	`hugo --gc --minify -b https://kalman.bokors.net/`
Clean build (drop cached resources)	`rm -rf public resources/_gen && hugo --gc --minify`
Show config as Hugo sees it	`hugo config`
List all pages with draft/future flags	`hugo list all`
Hugo and Go versions	`hugo version`

Creating content

# a new article in the knowledge base
hugo new knowledge-base/infra/your-post-title.md

# a new section (gets an _index.md)
hugo new knowledge-base/infra/newsection/_index.md

archetypes/default.md fills in date, title and draft: true. Flip draft to false when the page is ready; drafts are only visible with hugo server -D.

Warning

A page whose date is in the future is silently skipped in a normal build. If a new page doesn’t appear, check the date (and the server’s clock) before anything else.

Front matter used on this site

---
date: '2026-10-18T09:00:00+02:00'
lastmod: '2026-10-18'        # shows "Last updated on …" (KB articles only)
title: 'BGP Cheat Sheet'
linkTitle: 'BGP'             # optional shorter name for menus/sidebar
description: "One line used by cards, search and link previews."
icon: globe-alt              # Hextra icon name, used by the child cards
weight: 2                    # ordering within a section (lower first)
cheatsheet: true             # lists the page under "Cheat sheets & tools" on the landing page
draft: false
---

Section pages (_index.md) additionally use:

image: /images/home/routing.svg   # illustration for the section hero and parent card
breadcrumbs: false
cascade:
  type: docs                      # children inherit the docs layout
sidebar:
  hide: true                      # no left tree (About, HomeInfra, Privacy use this)

Icon names come from Hextra’s bundled set (Heroicons v1). Handy ones: cube, globe-alt, shield-check, server, key, lock-closed, identification, calculator, switch-horizontal, document-text, folder, map, user.

Shortcodes

Hextra’s own

{{< callout type="info" >}} Text {{< /callout >}}       <!-- info | warning | error | important -->

{{< cards cols="3" >}}
  {{< card link="/projects/hay-list/" title="The Hay-List" subtitle="…" image="/images/haylist/logo-cast.jpg" >}}
{{< /cards >}}

{{< figure src="/images/x.svg" alt="…" caption="…" >}}
{{< icon "github" >}}
{{< tabs items="IOS,Junos" >}} {{< tab >}} … {{< /tab >}} {{< /tabs >}}
{{< details title="Show config" >}} … {{< /details >}}

GitHub-style alerts also work in plain Markdown: > [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT].

Site-specific (in layouts/shortcodes/)

Shortcode	What it does
`{{< section-hero image="/images/home/vpn.svg" >}} intro text {{< /section-hero >}}`	Illustration + intro panel at the top of a section page
`{{< child-cards cols="3" >}}`	Cards for every direct child page/section, from their `title`, `description`, `icon`/`image`
`{{< cheat-sheets >}}`	Shortcuts to every page with `cheatsheet: true` (landing page)
`{{< recent-pages limit="6" >}}`	Most recently updated articles by `lastmod`

Raw HTML is allowed in Markdown here (markup.goldmark.renderer.unsafe: true), which is how the About page, the subnet calculator and the cookie notice are built.

Hextra as a Hugo module

hugo mod get -u github.com/imfing/hextra       # update to latest
hugo mod get github.com/imfing/[email protected]  # pin a version
hugo mod tidy                                  # clean go.mod / go.sum
hugo mod graph                                 # what is loaded, and version warnings
hugo mod vendor                                # copy the theme into _vendor/ to read its templates
hugo mod clean                                 # drop the module cache if a fetch is corrupt

To change a theme template, copy it from _vendor/github.com/imfing/hextra/layouts/… to the same path under layouts/ in this repo; Hugo prefers the local copy. Overrides currently in place: partials/components/last-updated.html, partials/components/analytics/google-analytics.html, plus the partials/custom/ hooks (head-end.html, footer.html).

Styling goes in assets/css/custom.css; Hextra appends it after its own CSS, so plain overrides win without !important. Theme colours live on :root (--primary-hue) and the two background tokens --hx-color-white / --hx-color-dark.

Config essentials (`hugo.yaml`)

baseURL: https://kalman.bokors.net/
module:
  hugoVersion: { min: "0.146.0", extended: true }   # Hextra 0.12+ requirement
  imports: [{ path: github.com/imfing/hextra }]
frontmatter:
  lastmod: [lastmod]            # "Last updated" only from explicit front matter, never git
params:
  images: ["images/og-image.jpg"]   # Open Graph card
  page: { width: wide }
  navbar: { width: wide }
  footer: { width: wide }
services:
  googleAnalytics: { ID: G-XXXXXXXX }   # loaded only after cookie consent

Deployment

The host builds main with hugo --gc --minify -b https://kalman.bokors.net/. Pull-request branches get a preview build. The Hugo version is set by the HUGO_VERSION environment variable separately for Production and Preview; keep both on the same version or previews break with “template for shortcode not found”.

Troubleshooting

Symptom	Usual cause
`template for shortcode "cards" not found`	Theme didn’t load: Hugo older than the theme’s minimum, or module fetch failed
`Module "…hextra" is not compatible with this Hugo version`	Bump `HUGO_VERSION` on the host
Page missing from the build	`draft: true`, or `date` in the future
Edit to `custom.css` not showing	Hard-refresh; in dev, restart `hugo server` if the file was created while it ran
Sidebar order wrong	Set `weight` on the pages; ties fall back to title
“Last updated” wrong	It comes from the page’s `lastmod` line, not git; edit the line
Search index stale in dev	Restart `hugo server`; the FlexSearch index is built at startup

Last updated on October 18, 2026