Feature Gallery

This page is a working reference for page features enabled in this Hugo-based site, intended as a reference for me. Each section briefly says what the feature does, then uses it. It is the Hugo port of the MkDocs feature gallery that I had in place; where the syntax differs from MkDocs, the section says so.

Markdown#

Hugo renders Markdown with Goldmark (CommonMark plus GitHub extensions): headings, paragraphs, links, emphasis, blockquotes, lists, and code.

Blockquotes are useful for quoted material, pull notes, or short excerpts.

• Unordered lists handle quick scan items.
• Nested structure should stay shallow for readability.

1. Ordered lists work for procedures.
2. They render with stable numbering.

Inline code looks like hugo --gc --minify, while links work like Hugo.

Abbreviations And Tooltips#

Goldmark has no abbreviation extension, so the theme’s content post-processor reads MkDocs-style *[TERM]: definition lines (plus site-wide ones in data/abbreviations.yaml) and wraps each term in <abbr>. Hover over HTML.

HTML is expanded through an abbreviation definition.

You can also attach a tooltip with a link title: hover me.

Definition Lists#

Definition lists are a Goldmark extension (definitionList). They are useful for glossary-style reference pages.

Cipherpunk

A culture and design style centered on cryptography, privacy, networks, and adversarial systems.

Palette

A named color scheme selected through the palette menu or browser preference.

Footnotes#

Footnotes are a Goldmark extension (footnote). They keep source notes out of the main flow.¹

Formatting Extensions#

Goldmark’s extras extension adds highlights, insertions, and deletions. Keyboard keys and critic markup are shortcodes; smart symbols come from the typographer plus the content post-processor.

• Highlighted text: important phrase
• Inserted text: new text (MkDocs used ^^new text^^)
• Deleted text: old text
• Keyboard shortcut: Ctrl+Alt+Del
• Smart symbols: copyright ©, trademark ™, arrows → ← ↔, fractions ½ ¾, ± and ≠
• Critic markup: remove this add this oldnew review this review thiswith a reviewer comment

Icons And Emoji#

Emoji shortcodes are built into Hugo (enableEmoji). Icon shortcodes like :material-console: are handled by the content post-processor, which inlines the SVG. Material Design Icons, Font Awesome, Octicons, and Simple Icons are all available and fetched at build time.

🚀

Task Lists#

Task lists are a Goldmark extension (taskList); the theme styles the checkboxes.

• Add the theme.
• Validate with strict builds.
• Pick final favorite palettes.

Blocks And Layout#

Structured blocks for callouts, grouping, and layout.

Admonitions#

Admonitions use GitHub-style alert syntax (> [!NOTE] Title) rendered by a blockquote render hook. Any Material type works: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, and quote, plus GitHub’s important and caution.

Buttons And Attributes#

Goldmark doesn’t support attributes on inline links, so buttons are a shortcode.

Primary button Secondary button

Block attributes still work on regular Markdown, like this paragraph with a custom class.

Collapsible Details#

Collapsible blocks are alerts with a trailing - (starts collapsed) or + (starts open), like > [!EXAMPLE]- Title. They are useful when the explanation is helpful but not always needed.

Hidden detail can still be copied.

Content Tabs#

Content tabs are the tabs and tab shortcodes. Tabs with the same label are linked across the page, and the choice is remembered between pages.

print("hello from Python")

printf '%s\n' 'hello from shell'

Fine Print#

The fineprint shortcode sets text at footnote size for notes that have nothing in the text to anchor a footnote to, like disclosures or credits. The body is Markdown.

A single paragraph can get the same style with a block attribute on the line after it:

This one uses { .fine-print }.

Grids And Cards#

Cards are a plain HTML wrapper around Markdown. CommonMark ends an HTML block at a blank line, so the Markdown inside is parsed normally.

Tables#

Tables are a Goldmark extension (markup.goldmark.extensions.table). Use them for compact comparisons.

Code#

Highlighted code, code from elsewhere, and code that runs at build time.

Code Blocks#

Hugo highlights code with Chroma at build time. The code block render hook adds titles, copy buttons, and annotations; line numbers, line anchors, and highlighted lines are Chroma options set in the fence attributes.

1
2
3
4
5

def greet(name: str) -> str:
    message = f"hello, {name}"  # (1)
    return message

print(greet("kag"))

1. Code annotations attach explanatory notes to specific lines.

Inline highlighting uses a shortcode: print("hello").

Gists#

The gist shortcode downloads a GitHub gist at build time and highlights it like any other code block, so no GitHub script runs in the browser. Hugo’s own gist shortcode was removed in v0.156; this one replaces it with the same syntax.

<!-- image -->
<figure {{ if isset .Params "class" }}class="{{ index .Params "class" }}"{{ end }}>
    {{ if isset .Params "link"}}<a href="{{ index .Params "link"}}">{{ end }}
        <img src="{{ index .Params "src" }}" {{ if or (isset .Params "alt") (isset .Params "caption") }}alt="{{ if isset .Params "alt"}}{{ index .Params "alt"}}{{else}}{{ index .Params "caption" }}{{ end }}"{{ end }} />
    {{ if isset .Params "link"}}</a>{{ end }}
    {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
    <figcaption>{{ if isset .Params "title" }}
        <h4>{{ index .Params "title" }}</h4>{{ end }}
        {{ if or (isset .Params "caption") (isset .Params "attr")}}<p>
        {{ index .Params "caption" }}
        {{ if isset .Params "attrlink"}}<a href="{{ index .Params "attrlink"}}"> {{ end }}
            {{ index .Params "attr" }}
        {{ if isset .Params "attrlink"}}</a> {{ end }}
        </p> {{ end }} 
    </figcaption>
    {{ end }}
</figure>
<!-- image -->

Markdown Exec#

Hugo can’t run code while it builds, so scripts/exec-blocks.py runs fenced blocks marked exec=true before the build and caches their output in data/exec.json. The code block render hook then renders the cached output. Keep examples deterministic and safe.

markdown-exec rendered this before the Hugo build

source and result can be shown in tabs

```python {exec=true result=ansi}
print("source and result can be shown in tabs")
```

Diagrams And Math#

Rendered from text in the page.

Math#

Math is captured by Goldmark’s passthrough extension and rendered to HTML at build time with KaTeX (transform.ToMath), so no math JavaScript runs in the browser.

Inline math renders as $E = mc^2$.

Mermaid Diagrams#

Mermaid diagrams are rendered by a mermaid code block render hook. The Mermaid script only loads on pages that contain a diagram, and diagrams redraw when the palette changes.

flowchart LR
  Draft[Draft] --> Build[hugo build]
  Build --> Review[Review page]
  Review --> Publish[Publish]

Images And Video#

Pictures, generated images, and embedded video.

Images, Captions, And Lightbox#

Images resolve from the page bundle, get a caption from the figure shortcode (or from a Markdown image title), and open in GLightbox. Click the image to open it in the lightbox.

QR Codes#

Hugo’s built-in qr shortcode draws a QR code at build time.

Responsive Images#

Raster images (JPEG, PNG, WebP) get WebP copies at several widths and a srcset, so phones download a small file and the lightbox gets the full one. Images also carry their width and height so the page doesn’t jump while they load. This works for plain Markdown images and the figure shortcode; SVGs and GIFs are left as they are.

Video Embeds#

The youtube and vimeo shortcodes show the video’s thumbnail, downloaded at build time, and load the player only when the reader clicks play. Until then the page makes no requests to YouTube, Google, or Vimeo. They replace Hugo’s built-in shortcodes and take the same parameters, plus start (seconds). YouTube plays from youtube-nocookie.com and Vimeo in do-not-track mode.

Hugo in 100 Seconds (Fireship) Play loads the video from YouTube Play video: Hugo in 100 Seconds (Fireship)

Overview (Planetary Collective) Play loads the video from Vimeo Play video: Overview (Planetary Collective)

Templating#

Shortcodes and content adapters: reuse, computed values, and pages from data.

Content Adapters#

A content adapter (_content.gotmpl) creates pages from data instead of Markdown files. Projects is built from data/projects.yaml: each entry becomes a page with its own URL, tags, and search entry.

Cross-References#

ref and relref turn a content path into the page’s URL and fail the build if the page doesn’t exist. Plain Markdown links like the About page get the same resolution and checking from the link render hook.

• ref gives an absolute URL: About
• relref gives a site-relative one: Docs

Macros#

Shortcodes take the place of the macros plugin: they inject config values or computed text during the build.

This site name comes from hugo.toml: Kyle A. George.

Other Built-In Shortcodes#

A few more ship with Hugo:

• param prints a page parameter, falling back to the site’s: this page’s description is “Examples of the Markdown, render hook, shortcode, and build features available on this site.”
• highlight highlights code, as an alternative to a fenced block:

1package main
2
3func main() {}

Snippets#

Snippets include shared Markdown from assets/snippets/.

This paragraph came from assets/snippets/feature-snippet.md via the snippet shortcode.

Use snippets for repeated callouts, boilerplate, warnings, or shared page fragments.

Site And Blog#

Features that span pages rather than living in one.

Blog Features#

These show up on blog posts. The Blog Feature Demo post (content/blog/feature-demo/) uses all of them; it’s a draft, so it only appears locally with make serve.

Cover images

A post bundle image named cover.* (or set with cover: in front matter) appears above the post, as the thumbnail on the blog index, and as the social preview image in place of the generated card.

Series

series: [Name] in front matter groups posts. Each part shows a “Part N of M” box listing the whole series, and the series gets its own page.

Related posts

Posts list up to three related posts, ranked by shared series, tags, and categories ([related] in hugo.toml).

Updated dates

The “updated” date comes from a lastmod: in front matter if there is one, otherwise from the file’s last git commit, otherwise from date. Posts show it next to the date; other pages, like this one, show “Last updated” at the bottom.

New posts

hugo new blog/my-post creates content/blog/my-post/index.md from archetypes/blog/index.md, as a folder so images can sit next to the post.

Navigation Features#

The theme has header tabs from the main menu, a sticky header, section navigation, breadcrumbs, instant navigation (browser prerendering through Speculation Rules), previous and next links in the footer, a table of contents that follows the scroll position, and a back-to-top button.

Redirects#

aliases: in front matter keeps old URLs working after a page moves. This page used to be at /feature-gallery/, which now redirects here. Hugo writes a small HTML page with a redirect at each old URL.

Search#

Hugo writes a search index (search.json) as a custom output format, and MiniSearch queries it in the browser. It supports highlighting on the target page, shareable search links, and suggestions. Try searching for Mermaid, markdown-exec, or Cipherpunk.

Tags#

Tags are a Hugo taxonomy, indexed from front matter with a page per tag. This page declares docs, hugo, and reference.

Build#

What happens when the site is built.

Build-Time Features#

Some MkDocs plugins do not create obvious inline syntax on a page, but they affect output. This is where each one landed in Hugo:

Link Checking#

The link render hook resolves internal links and logs a warning when one points at a page, file, or heading that doesn’t exist. make build runs Hugo with --panicOnWarning, so broken links fail the build, as they did with mkdocs build --strict.

Last updated October 9, 2026