Installation

Install the theme, its required toolchain and the optional renderers used by your content.

Install the theme as a pinned Hugo Module. The core site needs Hugo Extended, Go, Git and—when Tailwind utilities are enabled—Node.js. Graphics renderers are capability-based: install only the command-line tools used by your content.

Requirements#

Check the toolchain before installing:

hugo version
go version
git --version
node --version
npm --version

Install the theme#

Create a site and initialize its module if necessary:

hugo new site example-docs
cd example-docs
hugo mod init example.com/example-docs
npm init -y
npm install --save-dev @tailwindcss/cli@^4.1.0

Add the theme to hugo.toml:

[module]
  [[module.imports]]
    path = "github.com/projectious-work/brand-theme-hugo-vanilla"

[build]
  [build.buildStats]
    enable = true

Pin a release and commit both module files:

hugo mod get github.com/projectious-work/brand-theme-hugo-vanilla@v0.4.0
hugo mod tidy

Production sites should use a release tag rather than a moving branch.

Optional graphics tools#

Browser renderers require no global executable. Mermaid, D3, Observable Plot, JSXGraph, WaveDrom, SMILES Drawer and pseudocode.js are loaded only on pages that use them, from the exact versions in data/cdn.yaml or a self-hosted mirror.

Generated SVG fences need the corresponding executable when their cached output does not exist:

Confirm only the tools selected by your content:

d2 --version
dot -V
typst --version

The integrated build discovers source fences and assets, invokes only missing renderers, and caches their SVG. CI should install and pin every renderer used by the site so a clean checkout can reproduce the documentation.

Local theme development#

Clone the theme beside the consuming site and retain the normal module import. Add a temporary replacement to the site’s go.mod:

replace github.com/projectious-work/brand-theme-hugo-vanilla => ../brand-theme-hugo-vanilla

Remove machine-specific replacements and run hugo mod tidy before releasing.

Offline and restricted-network builds#

Set params.selfHostAssets = true and mirror the pinned files listed in data/cdn.yaml under static/vendor/<package>/. Vendor remote D2 icons and any URL-loaded diagram source as local project files. Tectonic-style package downloads are not part of this theme’s Typst pipeline; Typst Universe packages must already be cached or vendored for a completely offline clean build.

Verify the installation#

hugo mod graph
hugo server --disableFastRender

Open the address printed by Hugo, then verify navigation, search, light/dark mode and any renderer used by the site. Continue with Getting started to create the initial content and copy the complete output configuration.

Update or remove#

Review release notes before updating:

hugo mod get github.com/projectious-work/brand-theme-hugo-vanilla@v0.4.0
hugo mod tidy

To remove the theme, delete its module import and run hugo mod tidy. Remove the Tailwind dependency only when no other part of the site uses it.

Admin page

Member management, roles, status badges and a responsive data table.

Getting started

Create a Hugo site from scratch, install the theme from a release or local checkout, configure its outputs and run it.

This is a from-scratch walkthrough for a new site. Complete Installation first; this page concentrates on creating and configuring the initial documentation rather than repeating platform-specific tool installation.

1. Install the tools#

Install Hugo 0.128.0 or newer, Go, Node.js/npm and Git. Install D2, Graphviz or Typst only when the site uses their generated-SVG features. Confirm the core tools before creating files:

hugo version
go version
node --version
npm --version
git --version

The example is verified with Hugo 0.165.0. Use Hugo Extended because the CSS pipeline invokes Tailwind through Hugo Pipes.

See Installation for renderer commands, browser-only dependencies and offline builds.

2. Create an empty site#

hugo new site example-docs
cd example-docs
git init
hugo mod init example.com/example-docs
npm init -y
npm install --save-dev @tailwindcss/cli@^4.1.0

Allow Hugo to invoke Tailwind while retaining its standard executable policy:

[security.exec]
  allow = ["^(dart-)?sass$", "^go$", "^git$", "^node$", "^postcss$", "^tailwindcss$"]

Hugo 0.165 and later reject css.TailwindCSS when tailwindcss is absent from this allowlist.

hugo new site creates hugo.toml, content/, layouts/, static/ and other standard Hugo directories. hugo mod init creates go.mod, which records the theme dependency.

3. Choose how to install the theme#

Released Hugo Module — recommended#

Add the module import to the new site’s hugo.toml:

[module]
  [[module.imports]]
    path = "github.com/projectious-work/brand-theme-hugo-vanilla"

Fetch and pin a released version:

hugo mod get github.com/projectious-work/brand-theme-hugo-vanilla@v0.3.3
hugo mod tidy

Commit go.mod and go.sum. Production sites should use a release tag, not a moving branch.

Local checkout — offline development or theme changes#

Clone or unpack the theme beside the site:

workspace/
├── brand-theme-hugo-vanilla/
└── example-docs/

Keep the same module import, then add a local replacement to the site’s go.mod:

replace github.com/projectious-work/brand-theme-hugo-vanilla => ../brand-theme-hugo-vanilla

Hugo now reads the local checkout without downloading the module. Do not commit a machine-specific replace line in a production site; remove it and run hugo mod tidy before releasing.

4. Configure the feature outputs#

Copy the complete commented configuration from Configuration into the site’s root hugo.toml—the file created by hugo new site. The output-format blocks enable search, print views, page Markdown and llms.txt; the markup block enables class-based syntax highlighting, heading tables of contents and math.

5. Create the first pages#

content/
├── _index.md
└── docs/
    ├── _index.md
    └── first-page.md

+++
title = "Example documentation"
tagline = "Documentation for the example product."
+++

+++
title = "Documentation"
description = "Product and operations documentation."
weight = 10
+++

+++
title = "First page"
description = "The first page in the documentation set."
weight = 10
icon = "book"
+++

Write the page in ordinary Markdown.

6. Run and verify locally#

hugo server --disableFastRender

Open the URL printed by Hugo. Check the sidebar, search, language and appearance menus, code colours and keyboard focus. A production build is hugo --minify.

Next steps#

1. Read Configuration and set site identity and integrations.
2. Follow the Content authoring guide.
3. Review the feature map.
4. Adopt the maintenance workflow before the first release.

Site-wide configuration

Configure Hugo, outputs, Markdown, menus, languages and theme parameters.

Configure the theme in layers. Start with Hugo’s site configuration, add theme parameters for presentation and integrations, then use front matter for page-level choices. Do not edit theme templates for settings that already have a parameter.

Which configuration files exist?#

The example at src/content/hugo.toml is executable test material. The copyable equivalent is included below so a site creator does not need to browse the theme repository.

Minimum site configuration#

baseURL = "https://docs.example.com/"
title = "Example documentation"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
enableRobotsTXT = true

[module]
  [[module.imports]]
    path = "github.com/projectious-work/brand-theme-hugo-vanilla"

[build.buildStats]
  enable = true

baseURL must include any deployment prefix. The theme resolves internal links through Hugo so /project-name/ deployments work correctly.

Complete copyable configuration#

Paste this into the site-root hugo.toml created by hugo new site, then replace the example identity and repository values. Comments mark optional settings.

baseURL = "https://docs.example.com/" # Canonical URL, including any path prefix.
title = "Example documentation"       # Site name used in metadata and the header.
defaultContentLanguage = "en"         # English is served when no language is specified.
defaultContentLanguageInSubdir = false # Keep the default language at the site root.
enableRobotsTXT = true                 # Ask Hugo to generate the theme's robots.txt.

[module] # Install the theme as a versioned Hugo Module.
  [[module.imports]]
    path = "github.com/projectious-work/brand-theme-hugo-vanilla" # Theme module.

[build.buildStats] # Let Tailwind discover classes emitted by Hugo templates.
  enable = true

[security.exec] # Permit only the build tools the site intentionally invokes.
  allow = ["^(dart-)?sass$", "^go$", "^git$", "^node$", "^postcss$", "^tailwindcss$"]

[outputFormats.SearchIndex] # Local full-text search data at /index.json.
  mediaType = "application/json" # JSON response type.
  baseName = "index"              # Output filename without extension.
  isPlainText = true              # Do not wrap the generated JSON in HTML.
  notAlternative = true           # Keep this out of alternate-format metadata.

[outputFormats.Print] # Printable aggregate for each section.
  mediaType = "text/html" # Browser-renderable output.
  baseName = "print"      # Produces print.html.
  isHTML = true            # Enable Hugo's HTML processing.
  notAlternative = true    # Do not advertise it as an alternate page.
  permalinkable = true     # Give the output a stable URL.

[outputFormats.LLMS] # Machine-readable discovery document at /llms.txt.
  mediaType = "text/plain" # Plain UTF-8 text.
  baseName = "llms"        # Output filename without extension.
  isPlainText = true        # Do not apply an HTML wrapper.
  notAlternative = true    # Keep it out of alternate-format metadata.

[outputFormats.Markdown] # Clean Markdown representation of pages and sections.
  mediaType = "text/markdown" # Standard Markdown response type.
  isPlainText = true           # Do not apply an HTML wrapper.
  permalinkable = true         # Give every representation a stable URL.

[outputs] # Select the formats generated for each Hugo page kind.
  home = ["HTML", "RSS", "SearchIndex", "LLMS"] # Site-level discovery outputs.
  section = ["HTML", "RSS", "Print", "Markdown"] # Section aggregates and copies.
  page = ["HTML", "Markdown"] # Reader page plus clean Markdown.

[markup.goldmark.renderer] # Markdown-to-HTML safety policy.
  unsafe = false # Reject raw HTML from content files.
[markup.goldmark.extensions.passthrough] # Preserve formulas for KaTeX.
  enable = true
[markup.goldmark.extensions.passthrough.delimiters] # Accepted LaTeX delimiters.
  block = [["\\[", "\\]"], ["$$", "$$"]] # Display formulas.
  inline = [["\\(", "\\)"]]              # Formulas inside prose.
[markup.highlight] # Hugo Chroma syntax highlighting.
  noClasses = false # Emit semantic classes so the theme controls colours.
  guessSyntax = true # Highlight an unlabelled fence when detection succeeds.
[markup.tableOfContents] # Headings used by the right-hand navigation.
  startLevel = 2 # Begin with H2.
  endLevel = 3   # Include H3, but not deeper headings.

[[menus.main]] # Add a link to the primary header navigation.
  name = "Documentation" # Reader-facing label.
  pageRef = "/docs"       # Hugo page reference; checked during the build.
  weight = 10              # Lower weights appear first.

[params] # Public theme settings; defaults are documented below.
  description = "Documentation for the example product." # Site metadata summary.
  github = "https://github.com/example/example-docs" # Repository header link.
  editURL = "https://github.com/example/example-docs/edit/main/content/" # Edit base URL.
  version = "v1.0"             # Current label in the version menu.
  codeTheme = "adaptive"       # Adapt code panels to light and dark modes.
  sidebarSections = ["docs"]   # Top-level sections that receive the docs rail.
  sidebarOpenDepth = 0          # Initially expanded sidebar levels.

  [params.brand] # Optional product identity; every key has this default.
    home = "/"
    wordmark = "projectious.work"
    markLight = "logo/icon-light.svg"
    markDark = "logo/icon-dark.svg"
    favicon32 = "logo/icon-light.svg" # high-contrast mark for light browser chrome
    appleTouchIcon = "logo/apple-touch-icon-180.png"

  [[params.versions]] # One published documentation version.
    label = "v1.0"   # Menu label.
    url = "/"        # Deployment-relative root for this version.
    note = "latest"  # Optional status annotation.

The packaged defaults use the latest mark-5a logo. Every supplied colour and monochrome variant is also shipped under logo/theme/, so a site can select a different approved mark without copying or modifying the theme.

Required output formats#

HTML works without custom outputs. The integrated search, printing, Markdown copy and llms.txt features require the [outputFormats] and [outputs] blocks from the example configuration.

Add SearchIndex and LLMS to outputs.home; add Print and Markdown to sections; add Markdown to pages. The example configuration shows the exact media types and filenames.

Markdown configuration#

Copy the example [markup] block to enable:

• Goldmark passthrough delimiters for KaTeX;
• class-based Chroma syntax highlighting;
• H2/H3 tables of contents; and
• safe Markdown rendering with raw HTML disabled.

Turn markup.goldmark.renderer.unsafe on only when your own trusted content needs raw HTML. The theme itself does not require it.

Theme parameters#

Place these below [params] in hugo.toml:

The table is the complete public parameter set. Scalar parameters are assigned below [params]; tables and arrays use the TOML shapes shown in their detailed pages.

Menus and languages#

Define primary links under menus.main; use pageRef for local pages. Define each language under [languages.<code>] with label and weight. See Header and navigation and Internationalization for complete examples.

Edit and feedback integrations#

See Editing and feedback for repository URL mapping, the request payload, the browser’s one-vote-per-page behavior and the security requirements for an optional receiving service.

Notebook conversion#

Notebook conversion is an optional pre-build operation:

python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
./scripts/notebooks.sh

It writes shared Markdown below content/_notebooks/ and images below static/notebooks/. The shortcode checks a page resource first, then the shared path. Notebook basenames must be unique.

Search engines and llms.txt#

robots.txt gives compliant web crawlers crawl instructions. Set enableRobotsTXT = true; Hugo then asks the theme to publish /robots.txt. The theme allows canonical content while excluding generated search indexes and print variants that duplicate it. For example:

User-agent: *
Disallow: /search/
Disallow: /*/print.html
Sitemap: https://docs.example.com/sitemap.xml

llms.txt is a discovery document, not a crawler rule. Enable it by defining the LLMS output format and adding "LLMS" to outputs.home, as in the copyable configuration. It contains page titles, descriptions and links to clean Markdown representations, without repeated header, sidebar and footer controls:

# Example documentation
## Documentation
- [Getting started](https://docs.example.com/docs/getting-started/index.md): Create a site.

Neither file is access control. Private information must not be published; use authentication at the hosting layer when content requires access restrictions.

Validate configuration changes#

Run ./scripts/verify.sh. It builds twice, compares artifacts, rejects project-base URL escapes and runs desktop/mobile browser tests. A configuration change is not complete until that command passes without warnings.

Versioned documentation

Publish separate documentation builds and connect them with the version menu.

Each documentation version is a separate Hugo build. Publish the newest release at the stable site root and older builds below prefixes such as /v0.2/. Never add a version-menu entry until that URL exists.

Add an archived version step by step#

1. Check out the source tag for the older documentation, for example v0.2.0.

2. Build that checkout with a base URL ending in /v0.2/:

   sh Copy

   hugo --baseURL https://docs.example.com/v0.2/ --destination public/v0.2

3. Publish the entire generated public/v0.2/ tree. It contains that release’s index.html, section/page directories, CSS, JavaScript, fonts, search index and other static assets—not Markdown source files copied by hand.

4. Verify https://docs.example.com/v0.2/ and representative child pages.

5. Return to the current source and add the selector entry shown below.

6. Deploy current documentation without deleting the already-published v0.2/ directory.

[params]
  version = "v0.3"
  versionMenuLabel = "Releases" # Optional independent control label.

  [[params.versions]]
    label = "v0.3"
    url = "/"
    note = "latest"

  [[params.versions]]
    label = "v0.2"
    url = "v0.2/"

versionMenuLabel changes only the trigger and menu heading. The footer and selected entry continue to use version.

The menu normally appends the current page path so readers stay on the same topic. Set params.versionProbe = false, or probe = false on one entry, when versions have different structures. Older builds display a banner linking to the first configured version.

This repository lists archived tags in scripts/docs-archives.txt and the complete cross-version navigation catalog in scripts/docs-versions.toml. The deployment script rebuilds every listed immutable tag below its matching prefix and injects the current catalog before it publishes the current root. A clean checkout thus reproduces the complete version menu in every archived site without relying on state left by an earlier deployment. Consumers can use the same pattern or retain their archived generated trees by another deployment method.

Dashboard page

Operational metrics, activity trends and current pipeline state.

Page configuration (front matter)

Control navigation, cards, tables of contents and optional page capabilities.

Front matter is the TOML block between +++ delimiters at the beginning of a Markdown file. These values affect only that page or section.

+++
title = "API reference"       # Required page title.
linkTitle = "API"             # Optional shorter navigation label.
description = "HTTP API."     # Summary, metadata and search excerpt.
weight = 20                    # Navigation and previous/next order.
icon = "code"                 # Icon on a generated child-page card.
toc = true                     # Show the right-hand table of contents.
cards = true                   # Generate cards for child pages on a section.
hidden = false                 # Include this child in generated cards.
math = false                   # Load KaTeX only when this page needs it.
private = false                # Include the page in search and sitemap.
cover = "/img/api.png"         # Optional article cover image.
coverAlt = "API response"      # Required alternative text for the cover.
+++

Complete key reference#

Use quotes for strings, plain integers for weights, and true or false for booleans. The values shown in the type column are defaults, not placeholders.

Template authoring guide

Move from Markdown authoring to your first upgrade-safe Hugo shortcode and layout, step by step.

This guide starts with the knowledge needed to create ordinary Markdown pages. You do not need to know Go, HTML templating or Tailwind beforehand. By the end, you will have created a reusable status-panel component and will understand when and how to change a complete page layout.

1. Understand what changes when Markdown is not enough#

A Markdown file supplies content: headings, paragraphs, lists, images and front matter. A template supplies the HTML around that content. Hugo combines the two when it builds the site.

For example, this Markdown:

+++
title = "Service status"
+++

The service is available.

becomes a complete HTML page because the theme supplies the header, sidebar, main content area and footer. You only need to author a template when you want reusable presentation that Markdown and the theme’s existing shortcodes do not already provide.

Hugo has three relevant building blocks:

Start with a shortcode for a component used in content. It is the smallest and safest first customization. Do not copy a complete theme layout merely to add a box to one page.

2. Know which project you are editing#

The theme is a dependency of your Hugo site. Your site should have a structure similar to this:

my-site/
├── assets/
├── content/
│   └── docs/
├── layouts/
├── hugo.toml
├── go.mod
└── package.json

All paths in this guide are relative to my-site/, the directory containing your site’s hugo.toml. Create assets/ or layouts/ if they do not exist. Do not edit the downloaded theme in Hugo’s module cache. Hugo checks your local site first, so a local file can add to or override the theme without changing the dependency.

Before changing templates, make sure the ordinary site still builds:

hugo

If this command fails, first complete the from-scratch installation.

3. Learn the small amount of template syntax you need#

Hugo templates are HTML with instructions between {{ and }}. These are called template actions. The first example uses only five ideas:

A leading or trailing hyphen, as in {{- or -}}, only trims surrounding whitespace in the generated HTML. It does not change the value.

4. Create your first shortcode without styling#

Create layouts/shortcodes/status-panel.html in your site:

<aside>
  <h2>{{ .Get "title" }}</h2>
  <div>{{ .Inner | .Page.RenderString }}</div>
</aside>

This is a paired shortcode because it accepts content between an opening and a closing tag. .Page.RenderString tells Hugo to render Markdown such as emphasis and links inside that content.

Use the shortcode in any Markdown page:

{{< status-panel title="Release status" >}}
The **documentation build** passed all checks.
{{< /status-panel >}}

Run the development server and open the page containing the shortcode:

hugo server

At this stage the component is intentionally plain. Confirm that its heading and bold text render before adding styling. If Hugo reports failed to extract shortcode, check the filename, paired closing tag and quotation marks.

5. Enable the theme’s Tailwind integration#

Tailwind turns utility names in class="..." attributes into CSS. The theme already owns the stylesheet and exposes a documented set of semantic utilities. Your site must let Hugo record the class names found in your local templates.

In the site-root hugo.toml, add or merge this setting:

[build.buildStats]
  enable = true

Do not create a second [build.buildStats] table if one already exists; add enable = true to the existing table.

If you build the theme CSS in the consuming project, install the same major Tailwind CLI version and commit package.json and the generated lockfile:

npm install --save-dev @tailwindcss/cli@^4.1.0

The theme reads Hugo’s generated hugo_stats.json. This is how utility classes used by local templates become visible to Tailwind. Run the repository’s normal build command after adding a class; hugo server alone may not rebuild CSS in a custom build setup.

6. Style the shortcode with theme utilities#

Replace the simple shortcode with this styled version:

{{- $kind := .Get "kind" | default "info" -}}
{{- $classes := dict
  "info" "border-default bg-subtle text-hi"
  "important" "border-accent bg-surface text-hi"
-}}
<aside class="my-6 rounded-lg border p-6 {{ index $classes $kind }}">
  <h2 class="font-display text-accent">{{ .Get "title" }}</h2>
  <div class="font-sans text-hi">{{ .Inner | .Page.RenderString }}</div>
</aside>

Use it from Markdown:

{{< status-panel title="Release status" kind="important" >}}
The documentation build passed all checks.
{{< /status-panel >}}

Read it from top to bottom:

1. $kind reads an optional argument and falls back to info.
2. $classes maps the two supported values to complete class strings.
3. index selects one class string for the <aside> element.
4. .Get "title" writes the heading supplied by the author.
5. .Inner | .Page.RenderString renders the enclosed Markdown.

Use complete, literal class names in the map. Do not construct a class such as bg-{{ .Get "colour" }}. Tailwind cannot reliably discover dynamically assembled names, and allowing arbitrary presentation values makes the component harder to maintain.

7. Choose theme-safe colours, spacing and typography#

Use the documented utilities—font-display, font-sans, font-mono, bg-page, bg-surface, bg-subtle, bg-terminal, text-hi, text-lo, text-accent, border-default and border-accent. For custom CSS, prefer semantic variables such as --color-surface, --color-text-primary, --color-border, --space-5 and --radius-lg.

See Tailwind and design tokens for the complete mapped surface. Avoid depending directly on internal component selectors or raw palette steps when a semantic token exists.

The semantic names adapt to light mode, dark mode and accessibility settings. A hard-coded class such as bg-black may look correct in one mode but remain black in all modes. Test semantic utilities before adding custom CSS.

8. Add an icon only when it conveys useful information#

Place an additional Tabler outline SVG at assets/icons/<name>.svg; Hugo’s merged asset filesystem makes it available to the theme partial and shortcode:

{{ partial "icon.html" (dict "name" "chart-bar" "class" "ico--lg" "label" "Usage chart") }}

Decorative icons omit label and become aria-hidden. Icon-only controls need an accessible name on the control itself. See Icons and Tabler.

If the icon is purely decorative, omit label. If it communicates meaning that is not already present in nearby text, provide a short label. Do not use an icon as the only way to communicate status or severity.

9. Decide whether you really need a page layout#

The shortcode above adds a component inside .Content; it does not move the sidebar, breadcrumbs or page title. A layout is appropriate only when the HTML structure of a whole page type must change.

Before overriding one, identify the exact upstream file:

1. Find the layout that renders the page in the theme’s layouts/ directory.
2. Copy that one file into the identical path below your site’s layouts/.
3. Make the smallest possible change.
4. Keep a note of the theme version from which it was copied.

Copy the relevant theme layout into the same path in the consuming site, for example layouts/docs/single.html. Preserve the base template contract:

{{ define "main" }}
<div class="docs">
  {{ partial "sidebar.html" . }}
  <main id="main" class="docs__main">
    {{ partial "breadcrumbs.html" . }}
    <article class="prose">
      <h1>{{ .Title }}</h1>
      {{ .Content }}
    </article>
  </main>
</div>
{{ end }}

Start from the exact version of the upstream file you consume. Record the source tag in a comment or commit message so future maintainers can compare it.

The line {{ define "main" }} fills a named area supplied by the theme’s base template. The dot passed to a partial, as in {{ partial "sidebar.html" . }}, is the current page context. .Title comes from front matter and .Content is the rendered Markdown body.

If all you need is a component inside Markdown, stop at the shortcode. A copied layout follows the theme less automatically and therefore needs upgrade review.

10. Diagnose common first-time problems#

Hugo error messages normally include the template path and line number. Start at the first reported error; later errors can be consequences of the first one.

11. Verify behavior and accessibility#

Run a production build and the consuming site’s tests:

hugo --minify

Check light and both dark surfaces, 200% text size, keyboard focus, reduced motion, mobile layout, print output and every supported language. Confirm that links keep the deployment base path and that the generated CSS contains the new utilities.

For the status-panel, verify at least:

• the default form and kind="important";
• Markdown links and emphasis inside the panel;
• light and dark colour modes;
• keyboard navigation when the content contains a link;
• narrow mobile width and 200% browser zoom; and
• a production build with no template warning.

12. Maintain your customization#

When upgrading the theme:

1. Read release notes for template and token changes.
2. Diff every local override against the same upstream path in the new tag.
3. Remove an override when upstream now provides the required extension point.
4. Re-run visual and accessibility tests before committing go.mod and go.sum.

Local overrides are intentionally your responsibility; keeping them small and tested is the best protection against upgrade drift.

The safest progression is therefore: Markdown first, an existing theme shortcode second, a small local shortcode third, and a complete layout override only when the page structure truly has to change.

Tokens and public API

Inspect the stable semantic CSS tokens and Tailwind namespaces generated from the theme source.

The tables below are generated from the theme’s CSS during the Hugo build. Use semantic tokens and documented Tailwind namespaces in site-owned templates; palette steps, component selectors and internal behavior attributes may change.

The root API.md defines the complete compatibility contract. For practical authoring examples, see Tailwind and design tokens.

Settings page

Grouped form controls, validation, switches and save actions.

Terminal recordings

Record and embed copyable terminal sessions with asciinema.

asciinema records terminal text and timing data rather than video. Recordings stay sharp, remain copyable, and are usually much smaller than screen video.

Install the recorder, run asciinema rec theme-tour.cast, and put the resulting file in a page bundle or under static/casts/.

{{< asciinema src="/casts/theme-tour.cast" rows="8" cols="80"
     idleTimeLimit="1.5" >}}

cols, rows, speed, idleTimeLimit, autoplay, loop, controls, fit and theme are supported. theme="auto" follows the site’s light/dark mode; pass an asciinema palette name to keep a recording on a fixed palette.

Data-driven layouts can use the same player without copying shortcode markup:

{{ partial "asciinema.html" (dict
  "page" . "src" .Params.cast "id" "release-demo"
  "controls" "auto" "fit" "width" "theme" "auto") }}

Autoplay is off by default. The player version is pinned in data/cdn.yaml; see Dependencies for CDN and self-hosting options.

Pricing page

Three clear service tiers with one emphasized recommendation.

Tailwind and design tokens

Use the theme's Tailwind integration and stable projectious.work design tokens.

Content authors normally use Markdown and shortcodes; they do not need Tailwind. Template developers may use Tailwind utilities in site-owned layouts and shortcodes. Hugo’s build statistics tell Tailwind which classes were actually emitted, so [build.buildStats] enable = true is required.

Available Tailwind namespaces#

The theme maps brand tokens in assets/css/theme-layer.css:

<aside class="rounded-lg border border-default bg-surface p-6 text-hi">
  <h2 class="font-display text-accent">Release status</h2>
  <p class="font-sans text-lo">All documentation checks passed.</p>
</aside>

CSS token reference#

Use CSS custom properties when a utility is not appropriate. The complete source of truth is assets/css/brand-tokens.css; it defines the 12-step Midnight, Orange and Slate scales, semantic success/warning/danger/info colours, typography, spacing, radii, shadows, motion, breakpoints, layout measurements, terminal ANSI slots and light/dark syntax roles. Prefer semantic tokens such as --color-text-primary, --color-surface, --color-border, --space-5, --radius-lg and --type-body-size over raw palette steps.

The implementation follows the projectious.work brand design system. Set params.build.tailwind = false only when site templates contain no Tailwind utilities; the theme’s component CSS and tokens still render.

Data-driven components

Compose badges, card collections and data tables from Hugo data.

The theme exposes stable partials for layouts and matching content shortcodes for Markdown authors. Both accept structured data without copying internal markup. Sources can be:

• inline CSV, JSON, TOML, YAML or XML inside a paired shortcode;
• a file in assets/ or beside index.md in a page bundle; or
• an HTTP(S) URL fetched and cached by Hugo during the build.

Remote data is a build dependency, not a browser request. Pin a durable URL and keep a local fallback when reproducibility matters.

Badge#

badge.html accepts label, optional variant = "accent", and optional href. A badge communicates compact metadata such as lifecycle, availability or compatibility. It should not replace a button or carry a long sentence.

{{ partial "badge.html" (dict "label" "Ready" "variant" "accent") }}

For a list controlled by data, put this in assets/data/component-badges.yaml:

- label: Stable
  variant: accent
- label: Accessible
- label: Build-time data
  href: /docs/features/data-driven-components/

Then render the file from Markdown:

{{< data-badges src="data/component-badges.yaml" >}}{{< /data-badges >}}

For remote YAML, replace src with url and state the format because remote servers do not always send a useful content type:

{{< data-badges url="https://example.org/statuses.yaml" format="yaml" >}}{{< /data-badges >}}

Card list#

card-list.html accepts items. Each item may contain eyebrow, title, description, status = { label, variant }, and href. For example, assets/data/roadmap.json contains a top-level phases array:

{
  "phases": [
    {
      "eyebrow": "Now",
      "title": "Graphics foundations",
      "description": "Accessible SVG, bitmap figures and CSV charts.",
      "status": { "label": "Ready", "variant": "accent" },
      "href": "/docs/features/diagrams/"
    }
  ]
}

{{< card-list src="data/roadmap.json" key="phases" >}}{{< /card-list >}}

In a layout template, load the same global resource explicitly:

{{ $roadmap := resources.Get "data/roadmap.json" | transform.Unmarshal }}
{{ partial "card-list.html" (dict "items" $roadmap.phases) }}

site.Data.roadmap.phases is also valid when the source is JSON, YAML, TOML or XML at data/roadmap.*; CSV belongs in assets/ and is unmarshaled as shown above. A remote array uses the same shortcode with url, format and optional key arguments.

Data table#

data-table.html accepts row objects, column definitions and an accessible label. The shortcode’s compact columns="key:Label,…" syntax maps source fields to headers. It remains the simplest choice for a static table:

version,date,status,downloads,size_mb,featured,notes
v0.3.6,2026-08-16,Stable,18420,2.46,true,/changelog/release-v0-3-6/
v0.3.5,2026-08-03,Supported,12705,2.31,false,/changelog/release-v0-3-5/
v0.3.4,2026-07-14,Archived,9341,2.18,false,/changelog/release-v0-3-4/

For typed formatting and interaction, define the columns separately in assets/data/release-columns.yaml. This example demonstrates every supported type:

- key: version
  label: Version
  type: string
  sortable: true
  filter: text
- key: date
  label: Released
  type: date
  format: 02 Jan 2006
  sortable: true
  filter: date-range
- key: status
  label: Status
  type: status
  sortable: true
  filter: select
  variants:
    stable: accent
- key: downloads
  label: Downloads
  type: int
  format: "%d"
  align: right
  sortable: true
  filter: range
- key: size_mb
  label: Size
  type: float
  format: "%.1f MB"
  align: right
  sortable: true
- key: featured
  label: Featured
  type: bool
  trueLabel: Yes
  falseLabel: No
  align: center
  sortable: true
  filter: boolean
- key: notes
  label: Notes
  type: url
  linkLabel: Read notes
  align: right
  searchable: false

{{< data-table src="data/releases.csv"
    columns-src="data/release-columns.yaml"
    search=true sort=true filter=true
    label="Theme releases" >}}{{< /data-table >}}

search, sort and filter are independent and optional. Hugo always emits the complete accessible table. When an option is enabled, the page loads a small progressive-enhancement script that adds controls, typed sorting and a live result count. With JavaScript unavailable, readers still receive every row and formatted value.

Column type controls both rendering and comparisons:

align accepts left, center or right. searchable: false excludes a column from global search. Filters may be text, select, range, date-range or boolean; select choices are derived from the rendered rows. Sorting uses raw typed values rather than their formatted labels.

The original compact form continues to work:

{{< data-table src="data/releases.csv"
    columns="version:Version,date:Released,status:Status"
    label="Theme releases" >}}{{< /data-table >}}

Inline data uses the paired body and an explicit format:

{{< data-table format="csv"
    columns="version:Version,date:Released" label="Theme releases" >}}
version,date
v0.3.6,2026-08-16
v0.3.5,2026-08-03
{{< /data-table >}}

The complete template equivalent is:

{{ $source := resources.Get "data/releases.csv" }}
{{ $rows := transform.Unmarshal
    (dict "format" "csv" "targetType" "map") $source.Content }}
{{ partial "data-table.html" (dict
  "page" .
  "label" "Releases"
  "rows" $rows
  "search" true
  "sort" true
  "filter" true
  "columns" (slice
    (dict "key" "version" "label" "Version" "sortable" true)
    (dict "key" "date" "label" "Released" "type" "date"
      "format" "02 Jan 2006" "filter" "date-range")
    (dict "key" "downloads" "label" "Downloads" "type" "int"
      "align" "right" "filter" "range"))) }}

Use url="https://example.org/releases.json" format="json" to fetch a remote table at build time. The rendered table is identical; only the source changes.

Changelog badges#

Changelog badges let readers scan release maturity or category before reading the notes. Put the array in the front matter of the changelog content file—for example content/en/changelog/release-v1-4-0.md. Hugo makes it available as .Params.badges; the theme’s changelog list and single layouts pass each entry to badge.html automatically.

stable security

+++
title = "v1.4.0"
date = 2026-08-25

[[badges]]
label = "stable"
variant = "accent"

[[badges]]
label = "security"
+++

No shortcode is needed on the changelog page. For other content types, use the single badge or data-backed data-badges shortcodes shown above.

Run state page

Observability states for empty, loading, successful and failed runs.

Tags

Use Hugo taxonomies for related-content and release-note metadata.

Tags are ordinary Hugo taxonomy terms. Add them to front matter:

tags = ["release", "accessibility"]

The theme renders tags in page metadata and generates Hugo’s term and taxonomy pages. Tags are also included in the search index. The example site deliberately does not place a Tags link in the primary header; link to a curated term from your content when it helps readers, or add /tags/ to your own menu.

Configure a different taxonomy through Hugo’s [taxonomies] table and provide the corresponding templates if its presentation differs from tags.

Article page

A focused long-form article with metadata and a reading rail.

Developer guide

Adapt the theme, swap bundled assets, run tests and contribute changes safely.

Theme consumers should override files through Hugo Modules or their project layout instead of editing a cached module. Contributors to this repository work below src/; release and deployment scripts intentionally remain outside that tree.

Repository structure#

src/assets/       CSS, JavaScript and inline SVG icons
src/layouts/      Hugo templates, partials, render hooks and shortcodes
src/i18n/         interface translations
src/data/         glossary and pinned runtime metadata
src/static/       fonts, logos and licences
src/content/      executable multilingual example site
scripts/          local build, verification, release and deployment commands
tests/browser/    Playwright behavior and visual baselines

Override or adapt a template#

Hugo’s lookup order gives the consuming site’s layouts/ precedence over module templates. Copy only the partial or template you need to change and preserve its public parameters. This limits the merge work required during upgrades.

CSS variables in brand-tokens.css are the stable styling surface. Put site-level overrides in a later stylesheet rather than changing component selectors whenever possible.

Append site-owned CSS and JavaScript#

Do not override the theme’s complete styles.html or scripts.html pipelines. Create layouts/partials/hooks/styles-end.html or layouts/partials/hooks/scripts-end.html in your site instead. The theme calls these public, empty-by-default hooks after its own assets in both Tailwind and Hugo-only builds.

For example, compile assets/scss/site.scss, then fingerprint it and emit SRI:

{{ with resources.Get "scss/site.scss" }}
  {{ $built := . | css.Sass (dict "targetPath" "css/site.css") | minify | fingerprint "sha384" }}
  <link rel="stylesheet" href="{{ $built.RelPermalink }}"
    integrity="{{ $built.Data.Integrity }}" crossorigin="anonymous">
{{ end }}

Build and protect assets/js/site.js the same way:

{{ with resources.Get "js/site.js" }}
  {{ $built := . | js.Build (dict "minify" hugo.IsProduction "target" "es2018") | fingerprint "sha384" }}
  <script src="{{ $built.RelPermalink }}" integrity="{{ $built.Data.Integrity }}"
    crossorigin="anonymous" defer></script>
{{ end }}

The complete public contract is in the root API.md.

Icons and Tabler#

The theme currently bundles this small offline fallback set:

accessible, alert-circle, alert-triangle, arrow-left, arrow-right, book, brand-github, check, chevron-down, chevron-left, chevron-right, chevron-up, circle-check, clock, copy, device-desktop, external-link, file, file-code, folder, info-circle, language, list, menu-2, moon, pencil, player-play, printer, search, star, sun, tag, thumb-down, thumb-up, versions and x.

The fallback source files are in src/assets/icons/fallback/. Use a name with {{< icon "search" >}} or front-matter icon = "search". The resolver checks a site override, the mounted Tabler outline library and then the bundled fallback. Install the pinned library and mount it in hugo.toml:

npm install --save-exact @tabler/icons@3.31.0

[[module.mounts]]
  source = "node_modules/@tabler/icons/icons/outline"
  target = "assets/tabler-icons/outline"

Every Tabler outline icon is then available by its filename without .svg. A site can still override or add a glyph at assets/icons/<name>.svg. See the root ICONS.md for resolution order, naming and MIT attribution.

This icon is resolved from the mounted full library rather than the fallback set:

{{< icon name="rocket" class="ico--lg" label="Rocket from Tabler Icons" >}}

Tailwind in site templates#

Content Markdown should not contain presentation classes. Site-owned layouts and shortcodes may use the theme’s Tailwind namespaces and CSS tokens. See Tailwind and design tokens for the complete mapped utility surface, token categories and a working component example.

Swap fonts or runtime assets#

Font faces live in src/static/fonts/; declarations live in fonts.css. Replace both files and licence documents together, then test layout at 200% text size.

KaTeX, Mermaid and asciinema pins live in src/data/cdn.yaml. For offline hosting, mirror the exact file structure below static/vendor/ and enable params.selfHostAssets. See Dependencies and SBOM.

Build and test#

npm install
./scripts/build.sh
./scripts/verify.sh
./scripts/serve-watch.sh start

build.sh performs two Hugo passes because Tailwind consumes Hugo’s generated class inventory. verify.sh compares two output trees, validates base-path links and runs Playwright at desktop and mobile sizes.

When an intentional visual change fails a snapshot, inspect the actual and diff images first. Only then run npx playwright test --update-snapshots and review the new files.

Contribute#

Create a short-lived branch from main, use Conventional Commits, add tests for behavior changes, run verification locally and open a pull request referencing its work item. Do not add GitHub Actions: this repository’s release policy is explicitly local-only. See the root CONTRIBUTING.md for the complete workflow.

Search

How the generated search index, header search and command palette work.

Search is local and requires no hosted service. Hugo writes /index.json; the browser loads the bundled FlexSearch runtime only on pages where search is enabled. Each page contributes its title, description, breadcrumb, tags, content and H2/H3 headings, so a heading result links directly to its anchor.

Reader experience#

• Type in the header field or press / to focus it.
• Press Ctrl/Cmd+K for the command palette.
• Filter the dedicated search page by top-level section.
• Use arrow keys and Enter to select a result.

Configuration#

Copy the SearchIndex output format and add it to outputs.home, as shown in Configuration. Create content/search.md with layout = "search". Set params.search = false to remove the header field, index and search page integration.

Set private = true on a page to omit it from search and the sitemap. This is publication control, not access control: do not put secrets in a static site.

Changelog page

A chronological product history with compact semantic change labels.

Maintenance and upgrades

Keep the theme, runtime pins, content and published documentation current.

Treat theme upgrades as reviewed application changes. They can affect templates, generated URLs, accessibility, search records and screenshots even when content is unchanged.

Upgrade a consuming site#

1. Read the release notes and compare configuration examples.

2. Update the pinned Hugo Module version:

   sh Copy

   hugo mod get github.com/projectious-work/brand-theme-hugo-vanilla@vX.Y.Z
   hugo mod tidy

3. Update locked Node dependencies with npm install when the release changes package.json.

4. Compare local template overrides with their new upstream versions.

5. Build with the production baseURL, run link and browser checks, and review visual changes in every supported language.

6. Commit go.mod, go.sum, package lockfiles and required configuration changes together.

Check for a new release#

Copy scripts/check-theme-update.sh from the theme release into the consuming site’s scripts/ directory and make it executable. It reads the installed version from Hugo’s module graph and compares it with upstream SemVer tags:

chmod +x scripts/check-theme-update.sh
./scripts/check-theme-update.sh

It is check-only by default and exits with status 10 when an update is available, which makes it suitable for a scheduled local task. After reading the release notes and committing or stashing site changes, apply the update explicitly:

./scripts/check-theme-update.sh --update

The update mode runs hugo mod get and hugo mod tidy; it deliberately does not rewrite configuration, overwrite local templates or publish. Review the resulting go.mod/go.sum, compare configuration examples, then run the consuming site’s build, link, accessibility and visual tests.

Routine checks#

• Run npm audit and review direct dependency updates.
• Test the minimum and current supported Hugo versions.
• Check external links and the Edit-this-page prefix.
• Verify search, version and language menus after adding or moving pages.
• Review translated pages whenever English structure changes.
• Confirm CDN pins still exist and self-hosted mirrors match them.
• Re-run accessibility checks after CSS, navigation or component changes.

Maintain versioned documentation#

Publish a version URL before adding it to params.versions. Keep canonical current documentation at the stable root. When removing an old version, remove its selector entry and configure redirects where links may remain in the wild.

Repository release chain#

This repository uses local scripts rather than GitHub workflows. From a clean, synchronized main after review:

./scripts/release.sh vX.Y.Z

The script verifies deterministic output and browser baselines, packages the theme, creates the annotated tag and GitHub release, then deploys that tagged commit to GitHub Pages. Never deploy an unreviewed working tree.

Recovery and support#

Published tags and GitHub release archives are immutable recovery points. Report security issues through SECURITY.md; use GitHub issues for reproducible defects and discussions for usage questions when enabled.

Mathematics

Render inline and display mathematics with KaTeX.

KaTeX renders LaTeX notation. Set math = true in the page front matter first. Inline mathematics such as \( t_{build} < 1s \) stays in a sentence; display mathematics gets its own block:

+++
math = true
+++

Inline: \\( t_{build} < 1s \\)

$$
T_{publish} = T_{build} + T_{verify} + T_{deploy}
$$

For generated expressions that are awkward to place directly in Markdown, the paired shortcode is equivalent:

{{< math display="block" >}}
T_{publish} = T_{build} + T_{verify} + T_{deploy}
{{< /math >}}

See Page configuration for the front-matter contract and Dependencies for the runtime pin.

Dependencies and SBOM

Understand build tools, browser runtimes, bundled assets, versions and licences.

The theme has no server runtime. Hugo produces static files. Dependencies fall into build-time tools, browser-loaded libraries and bundled assets.

Direct dependency inventory#

D2, Graphviz and Typst are optional build tools. The graphics pre-renderer calls only a backend used by uncached content, so a consuming project installs the subset it needs. Their versions should be pinned in that project’s build image; they are not mandatory theme dependencies.

See Installation for the required core toolchain, optional renderer commands and offline/self-hosted setup.

Exact browser-runtime URLs are maintained in src/data/cdn.yaml; exact npm transitives and integrity values are in package-lock.json; Python conversion pins are in scripts/requirements.txt.

Bundled fonts and icons#

Plus Jakarta Sans, Source Sans 3 and IBM Plex Mono are bundled as WOFF2 under the SIL Open Font License 1.1. IBM Plex Mono includes normal and italic cuts at 400, 500, 600 and 700 so syntax roles use real faces rather than browser-synthesized weight or oblique. Licence texts ship under src/static/fonts/licenses/. The theme’s fallback SVG set follows Tabler geometry. The exact Tabler dependency is mounted from node_modules during the example build; consuming sites may use the same mount or rely on the fallback set. See Icons and Tabler. FlexSearch’s licence ships under src/static/licenses/flexsearch/.

SBOM scope and maintenance#

This page is the human-readable software bill of materials for v0.3.x. Before each release, maintainers must compare it with package-lock.json, requirements.txt, data/cdn.yaml, bundled asset directories and Hugo/Go declarations. Generated CycloneDX or SPDX output may supplement this page, but must not replace checked-in licence files or the exact lockfiles.

Run npm audit --json for the Node graph. CDN and bundled assets require separate release-note and advisory review because npm audit cannot see them.

Jupyter notebooks

Convert and publish reproducible notebook output.

Jupyter notebooks combine prose, executable code, and output in .ipynb JSON files. The theme converts them before Hugo builds, so the published page contains ordinary Markdown and images rather than executable code.

pages = 98
languages = ["English", "Deutsch", "Français"]
pages_per_language = pages / len(languages)
pages_per_language

32.67

{{< notebook "theme-demo" >}}

Create an isolated conversion environment and convert every notebook:

python3 -m venv .venv
. .venv/bin/activate
pip install -r scripts/requirements.txt
./scripts/notebooks.sh

The pinned nbconvert environment makes conversion reproducible and keeps the tools outside the system Python installation. Embed the converted result with {{< notebook "theme-demo" >}}. The shortcode accepts a converted file; it cannot execute or contain an inline notebook. See Notebook conversion for lookup paths.

Internationalization

Configure translated content, language navigation, metadata and RTL layout.

Use Hugo’s multilingual configuration and place translated content below language directories. The example site contains complete English, German and French trees.

defaultContentLanguage = "en"

[languages.en]
  label = "English"
  weight = 1
[languages.de]
  label = "Deutsch"
  weight = 2
[languages.fr]
  label = "Français"
  weight = 3

The language menu links to the current page’s translation when available and falls back to that language’s home page. Search indexes, edit links, RSS, canonical URLs, sitemaps, hreflang and llms.txt remain language-aware.

Translate interface strings in i18n/<lang>.toml. For right-to-left languages set languagedirection = "rtl"; structural rails, chevrons and menus mirror.

Keep filenames and translation keys stable across languages. Hugo then associates translations without custom template logic.

Header and navigation

Configure primary links, repository actions, search and header controls.

The header contains the brand link, primary menu, search, version and language menus, accessibility and colour controls, and an optional repository link. On wide screens it aligns with the documentation shell; on narrow screens documentation navigation moves into a drawer.

Primary links#

Use Hugo menus in hugo.toml:

[[menus.main]]
  name = "Documentation"
  pageRef = "/docs"
  weight = 10

[[menus.main]]
  name = "Change log"
  pageRef = "/changelog"
  weight = 20

Prefer pageRef for site pages and url for external destinations. Ordering is by weight.

Set params.activeSection on a menu entry when it owns an entire section. This prevents a direct shortcut and its parent section from both appearing active:

[[menus.main]]
  name = "Documentation"
  pageRef = "/docs"
  [menus.main.params]
    activeSection = "docs"

Below 30rem the wordmark collapses automatically while the linked brand mark and accessible name remain available.

Sidebar groups#

Documentation section groups are collapsed on a reader’s first visit. Configure the number of initially open levels below [params]:

[params]
  sidebarOpenDepth = 0 # 0 closes all; 1 opens top-level groups.

The small Expand all or Collapse all button beside the sidebar title changes every group at once. Opening or closing an individual group stores the complete tree state in browser-local storage, scoped to the site and language. That reader state takes precedence over sidebarOpenDepth on later page loads, so following links does not reset the tree. Filtering opens matching groups only temporarily and restores the stored state when the query is cleared.

Header icons and links#

params.github adds the bundled GitHub icon with an accessible label. For another service, add an icon SVG below assets/icons/ and extend partials/header.html with an .iconbtn link using partials/icon.html. Keep the link at least 44 by 44 CSS pixels and provide an aria-label.

See Bundled icons for the complete icon list.

Editing and feedback

Connect pages to their source files and optionally collect useful reader votes.

Edit this page#

params.editURL is the repository URL prefix containing the site’s Markdown files. For a page at content/docs/install.md, this configuration creates a link to https://github.com/org/repo/edit/main/content/docs/install.md:

[params]
  editURL = "https://github.com/org/repo/edit/main/content/"

Use a language map when each language has its own content root:

[params.editURL]
  default = "https://github.com/org/repo/edit/main/content/en/"
  de = "https://github.com/org/repo/edit/main/content/de/"
  fr = "https://github.com/org/repo/edit/main/content/fr/"

The control is omitted when editURL is unset or the page has no source file.

Page feedback#

The Yes/No control works locally by remembering one vote per page in browser storage. Set params.feedback = false to hide it. To collect votes centrally, set params.feedbackEndpoint to an HTTPS endpoint. The browser sends:

{"path":"/docs/install/","value":"up","title":"Install","lang":"en"}

The browser avoids repeated submissions from the same browser—at most one network request per page per hour and ten per tab session. This is only interface behavior: a caller can bypass JavaScript and send arbitrary requests. The receiving service must therefore reject unexpected origins and paths, validate the JSON fields, limit request rates by an appropriate server-side identity, cap body size and avoid logging sensitive headers. CONTRACT-feedback.md contains the endpoint contract and a reference Worker implementation.

Diagrams and Charts

Create responsive diagrams, data-driven charts and generated vector figures.

The theme accepts diagram source and chart data directly in Markdown, from a project file, or from an explicitly supplied build-time URL. Each source is passed to a domain-specific renderer and becomes inline SVG or semantic HTML. That common contract keeps text selectable and lets the page provide responsive, accessible and printable presentation without reducing every domain to one generic drawing language.

Choose an authoring path#

Mermaid in Markdown#

A mermaid fence is the fastest route from an idea to a semantic diagram. The theme loads its pinned runtime only when a page uses Mermaid and redraws the diagram after a colour-mode change.

flowchart LR
  M[Markdown] --> H[Hugo]
  H --> S[Search index]
  H --> P[HTML and print]

```mermaid
flowchart LR
  M[Markdown] --> H[Hugo]
  H --> P[HTML and print]
```

The paired shortcode {{< mermaid >}}…{{< /mermaid >}} is equivalent. It can also load a page/global asset or fetch a source during the Hugo build. For example, this rendering comes from assets/graphics/request-flow.mmd:

flowchart LR
  B[Browser] --> E[Edge]
  E --> H[Hugo site]
  H --> C[(Content)]

{{< mermaid src="graphics/request-flow.mmd" >}}{{< /mermaid >}}

A build-time URL uses the same rendering path:

{{< mermaid url="https://example.org/diagrams/request-flow.mmd" >}}{{< /mermaid >}}

Hugo fetches the URL while building; the browser receives the Mermaid source inside the page and does not contact that URL. Prefer a versioned, project-controlled URL. Versions and delivery options are documented under Dependencies, while Mermaid syntax belongs in the Mermaid documentation.

Charts from CSV#

The chart shortcode turns a two-column CSV resource into inline, accessible SVG during the Hugo build. It adds no browser JavaScript and automatically uses the theme’s surfaces, borders, typography and colour-mode tokens.

Place shared data under assets/, or put it beside index.md in a page bundle. The first row is a header; the first column contains labels and the second contains positive numeric values.

Quarter,Projects
Q1,18
Q2,31
Q3,46
Q4,67

{{< chart src="data/graphics-adoption.csv" type="bar"
    title="Projects using generated graphics"
    x-label="Quarter" y-label="Projects"
    caption="A bar chart generated from CSV." >}}

The explicit title becomes the SVG’s accessible name, while the caption supplies visible context. Tooltips expose the exact label and value for every mark.

Line charts#

Use a line when ordered values form a meaningful progression.

{{< chart src="data/graphics-adoption.csv" type="line"
    title="Growth in projects using generated graphics"
    x-label="Quarter" y-label="Projects" >}}

Dot charts#

Use dots when the individual measurements matter more than continuity.

{{< chart src="data/graphics-adoption.csv" type="dot"
    title="Projects using generated graphics by quarter"
    x-label="Quarter" y-label="Projects" >}}

Rich charts with Plot#

The static chart shortcode is ideal for a small, printable series. For broader coverage, plot uses Observable Plot. It adds tooltips, scales, grouping and richer marks while retaining responsive SVG output and the theme’s colour tokens.

Every Plot example accepts the same three build-time data paths:

• inline CSV, JSON, TOML, YAML or XML in the paired shortcode body;
• src pointing to assets/ or a page-bundle resource; or
• url fetched and cached by Hugo, with an explicit format.

Bar and grouped bar#

The bar, line and area examples share assets/data/plot-series.csv:

quarter,projects,target
Q1,18,20
Q2,31,30
Q3,46,44
Q4,67,60

{{< plot src="data/plot-series.csv" type="bar"
    x="quarter" y="projects" title="Projects by quarter" >}}{{< /plot >}}

Add color="team" when the data contains a grouping column. Plot creates the categorical scale and legend.

Line and area#

{{< plot src="data/plot-series.csv" type="line"
    x="quarter" y="projects" title="Project adoption" >}}{{< /plot >}}
{{< plot src="data/plot-series.csv" type="area"
    x="quarter" y="projects" title="Project adoption" >}}{{< /plot >}}

Scatter plots#

The scatter, histogram and box-plot examples share assets/data/plot-measurements.csv:

team,latency,throughput
Core,82,510
Core,91,470
Core,76,540
Edge,48,610
Edge,55,590
Edge,43,650
Data,118,390
Data,105,420
Data,127,360

{{< plot src="data/plot-measurements.csv" type="scatter"
    x="latency" y="throughput" color="team"
    title="Throughput versus latency" >}}{{< /plot >}}

Histograms and distributions#

{{< plot src="data/plot-measurements.csv" type="histogram"
    x="latency" title="Latency distribution" >}}{{< /plot >}}

Box plots summarize distributions by group:

{{< plot src="data/plot-measurements.csv" type="box"
    x="team" y="latency" title="Latency range by team" >}}{{< /plot >}}

Heat maps#

The heat map uses assets/data/plot-heatmap.csv:

day,hour,value
Mon,09:00,18
Mon,13:00,32
Mon,17:00,24
Tue,09:00,25
Tue,13:00,41
Tue,17:00,35
Wed,09:00,22
Wed,13:00,37
Wed,17:00,29

{{< plot src="data/plot-heatmap.csv" type="heatmap"
    x="hour" y="day" color="value" title="Requests by time slot" >}}{{< /plot >}}

Inline and remote data#

Inline data is useful for a small chart that belongs to one paragraph:

{{< plot format="csv" type="bar" x="quarter" y="projects"
    title="Inline project counts" >}}
quarter,projects
Q1,18
Q2,31
Q3,46
{{< /plot >}}

For a build-time URL, Hugo downloads and caches the source before it writes the page; visitors do not make the data request:

{{< plot url="https://example.org/metrics.json" format="json"
    type="line" x="date" y="value" title="Daily metric" >}}{{< /plot >}}

CSV and JSON are the most portable choices. YAML, TOML and XML also work.

More Plot charts and configuration#

The theme shortcode currently exposes bar, line, area, scatter, histogram, box and heat-map charts. Plot itself uses composable marks rather than a fixed list of chart types. Its capabilities overview and gallery demonstrate additional possibilities such as stacked and diverging bars, rules, text, links, arrows, vectors, density and contour plots, hexagonal bins, raster plots, maps, trees, clusters and small multiples.

Plot can layer multiple marks and configure axes, grids, legends, colour and opacity scales, projections and facets. It can also derive values with bin, group, stack, normalize, window and map transforms. Consult the upstream marks, scales, transforms, and facets references for the complete option set. The theme keeps its shortcode deliberately smaller so every exposed option has consistent responsive, accessible and colour-mode behavior.

Build-integrated diagram fences#

D2 and Graphviz/DOT are source languages rather than formats understood by Hugo itself. The project build command therefore runs the graphics renderer immediately before Hugo. It discovers fences and referenced source files, hashes their content, invokes only the required external renderer, caches the resulting SVG under _generated/graphics/, and then lets Hugo include that SVG as an ordinary responsive figure.

Authors only write a fence or use diagram with a file or URL; they do not run a separate conversion command or maintain a matching SVG by hand. A cached result also lets builds proceed without the renderer until its source changes. CI should nevertheless pin and install every renderer used by the site so a clean build can reproduce all outputs.

D2 architecture diagrams#

D2 is strongest for architecture, infrastructure, service maps and data flows. It supplies automatic layout, containers, connections, labels and multiple layout engines without manual coordinates.

```d2 {alt="Request processing architecture" caption="Service flow"}
direction: right
client -> edge: HTTPS
edge -> api: authenticated request
api -> db: query
```

Network topology#

This deliberately compact campus example borrows the useful visual grammar of larger operational diagrams: traffic flows top-down, boundaries group the edge, campus zones and branch, device shapes distinguish network equipment from hosts, and labels carry example addresses, VLANs, protocols and link capacity. Redundant paths remain explicit without reproducing every access device. The rendering is loaded from assets/graphics/network-topology.d2 and compiled as part of the Hugo build.

{{< diagram renderer="d2" src="graphics/network-topology.d2"
    alt="Internet, campus network zones and a VPN-connected branch"
    caption="A grouped top-down network topology." >}}

direction: down

classes: {
  zone: {
    style: {
      fill: "#f7f9fc"
      stroke: "#7890aa"
      stroke-dash: 4
    }
  }
  network-device: {
    shape: hexagon
    style: {
      fill: "#e7f2ff"
      stroke: "#2f6f9f"
    }
  }
  endpoint: {
    shape: rectangle
    style: {
      fill: "#ffffff"
      stroke: "#567089"
    }
  }
}

internet: Internet {
  shape: cloud
  style.fill: "#dceeff"
}

edge: Internet edge {
  class: zone
  isp: ISP router\n203.0.113.1 {
    class: network-device
  }
  firewall: Perimeter firewall\nWAN 203.0.113.2\nLAN 10.20.0.1 {
    shape: hexagon
    style.fill: "#ffe7dc"
    style.stroke: "#b34f2a"
  }
  isp -> firewall: 1 Gbit/s fibre
}

campus: Main campus · 10.20.0.0/16 {
  class: zone
  core: Core network {
    class: zone
    primary: Core switch A\n10.20.0.2 {
      class: network-device
    }
    standby: Core switch B\n10.20.0.3 {
      class: network-device
    }
    primary <-> standby: redundant 10 Gbit/s trunk
  }
  dmz: DMZ · 10.20.20.0/27 {
    class: zone
    web: Web server\n10.20.20.8 {
      class: endpoint
    }
    mail: Mail server\n10.20.20.9 {
      class: endpoint
    }
  }
  users: User VLANs {
    class: zone
    engineering: Engineering\nVLAN 20 · 10.20.20.0/24 {
      class: network-device
    }
    business: Business\nVLAN 30 · 10.20.30.0/24 {
      class: network-device
    }
    eng-pc: Workstation ENG-01\n10.20.20.41 · DHCP {
      class: endpoint
    }
    bus-pc: Workstation BUS-01\n10.20.30.41 · DHCP {
      class: endpoint
    }
    engineering -> eng-pc: access port
    business -> bus-pc: access port
  }
}

branch: Branch office · 10.40.0.0/16 {
  class: zone
  router: Branch router\n10.40.0.1 {
    class: network-device
  }
  switch: Access switch\n10.40.10.2 {
    class: network-device
  }
  client: Branch workstation\n10.40.10.51 · DHCP {
    class: endpoint
  }
  router -> switch: 1 Gbit/s trunk
  switch -> client: VLAN 10
}

internet -> edge.isp: public uplink
edge.firewall -> campus.core.primary: inside · 10.20.0.0/16
edge.firewall -> campus.core.standby
campus.core.primary -> campus.dmz.web: HTTPS · TCP 443
campus.core.standby -> campus.dmz.mail: SMTP · TCP 25
campus.core.primary -> campus.users.engineering: 802.1Q trunk
campus.core.standby -> campus.users.business: 802.1Q trunk
campus.core.primary -> branch.router: site-to-site VPN\n10.255.0.0/30

Nested provider-style infrastructure#

D2 containers naturally express account, region, VPC, availability-zone and subnet boundaries. Icons from the D2 icon library make services recognizable while the grouping remains ordinary D2. The example deliberately mixes icons with plain labeled resources: an icon supports meaning but does not replace it.

{{< diagram renderer="d2" src="graphics/aws-nested-infrastructure.d2"
    alt="Nested AWS production infrastructure"
    caption="Provider-style infrastructure grouping." >}}

direction: right

internet: Internet {
  shape: cloud
}

aws: AWS account {
  icon: https://icons.d2lang.com/aws%2F_Group%20Icons%2FAWS-Cloud-alt_light-bg.svg
  style: {
    stroke: "#d86613"
    font-color: "#8a3b00"
    fill: white
  }

  region: eu-central-1 {
    vpc: Production VPC 10.1.0.0/16 {
      icon: https://icons.d2lang.com/aws%2F_Group%20Icons%2FVirtual-private-cloud-VPC_light-bg.svg
      style: {
        stroke: green
        font-color: green
        fill: white
      }

      az-a: Availability Zone A {
        style: {
          stroke: blue
          font-color: blue
          stroke-dash: 3
          fill: white
        }

        public: Public subnet {
          lb: Application Load Balancer
        }

        private: Private subnet {
          lambda: Lambda API {
            icon: https://icons.d2lang.com/aws/Compute/AWS-Lambda.svg
          }
        }

        data: Database subnet {
          db: Amazon RDS PostgreSQL {
            icon: https://icons.d2lang.com/aws%2FDatabase%2FAmazon-RDS_light-bg.svg
          }
        }
      }
    }
  }
}

internet -> aws.region.vpc.az-a.public.lb: HTTPS
aws.region.vpc.az-a.public.lb -> aws.region.vpc.az-a.private.lambda
aws.region.vpc.az-a.private.lambda -> aws.region.vpc.az-a.data.db

Remote icon URLs are fetched by D2 while rendering. For deterministic offline builds, download the chosen SVG icons into the project, reference their local paths, and commit them with the diagram source. D2 also supports imports and variables, so teams can keep provider styles and reusable infrastructure groups in a small local D2 library rather than copying them into every figure.

Graphviz graphs#

Graphviz is the dependable choice for dependency graphs, trees, finite-state relationships and machine-generated networks. Its DOT language describes nodes and edges; the selected layout engine computes their geometry.

```dot {alt="Release workflow" caption="Release states"}
digraph release {
  rankdir=LR;
  draft -> review;
  review -> published [label="approve"];
}
```

For a source file instead of a fence, put .d2, .dot or .typ in assets/ or a page bundle and use the same renderer:

{{< diagram renderer="d2" src="diagrams/system.d2"
    alt="Request processing architecture" caption="Service flow" >}}

url="https://example.org/system.d2" is also accepted by the shortcode. The pre-renderer fetches it during the build and Hugo fetches the same URL through its resource cache. Prefer a versioned, project-controlled URL; a remote source is deliberately an explicit build dependency and cannot work offline until its SVG is cached.

For precision drawings, mathematical figures and the wider Typst package ecosystem, continue with Typst graphics and CeTZ.

Interactive mathematics with JSXGraph#

JSXGraph renders manipulable geometry, functions, curves, vector fields and other mathematical constructions. The theme accepts a declarative JSON model: named elements can reference elements created earlier, and their attributes are passed to JSXGraph.

{
  "boundingBox": [-1.5, 5, 6, -1.5],
  "axis": true,
  "elements": [
    {"id": "a", "type": "point", "parents": [0, 0], "attributes": {"name": "A", "size": 5, "fillColor": "#ffffff", "strokeColor": "#174a72", "strokeWidth": 3}},
    {"id": "b", "type": "point", "parents": [4, 0], "attributes": {"name": "B", "size": 5, "fillColor": "#ffffff", "strokeColor": "#174a72", "strokeWidth": 3}},
    {"id": "c", "type": "point", "parents": [1.4, 3], "attributes": {"name": "C", "size": 5, "fillColor": "#ffffff", "strokeColor": "#174a72", "strokeWidth": 3}},
    {"type": "polygon", "parents": ["a", "b", "c"], "attributes": {"fillColor": "#70a9d1", "fillOpacity": 0.22, "borders": {"strokeColor": "#174a72", "strokeWidth": 3}}},
    {"type": "circumcircle", "parents": ["a", "b", "c"], "attributes": {"strokeColor": "#d0522a", "strokeWidth": 4, "fillOpacity": 0}}
  ]
}

{{< jsxgraph src="graphics/math-construction.json"
    title="Interactive circumcircle construction"
    caption="Drag the triangle vertices." >}}{{< /jsxgraph >}}

The same JSON can be placed directly inside the paired shortcode or loaded with url. Consult the JSXGraph API for element types, parents and attributes; the theme does not duplicate that reference.

Digital timing with WaveDrom#

WaveDrom turns WaveJSON into SVG timing diagrams for clocks, signals, buses and register fields.

{ signal: [
  { name: "clk",  wave: "p......." },
  { name: "req",  wave: "01....0." },
  { name: "data", wave: "x.345.x.", data: "header payload crc" },
  { name: "ack",  wave: "0...1.0." }
]}

{{< wavedrom src="graphics/clock-bus.json5"
    title="Clock and request bus timing" >}}{{< /wavedrom >}}

Inline WaveJSON and build-time url input use the same shortcode.

Chemical structures from SMILES#

SMILES Drawer converts a compact SMILES description into inline SVG. The textual SMILES value remains in the document as an assistive fallback.

CC(=O)OC1=CC=CC=C1C(=O)O

{{< smiles value="CC(=O)OC1=CC=CC=C1C(=O)O"
    title="Aspirin structure" >}}

Use src for a checked-in .smi file or url for an explicitly approved build-time source.

Algorithms and pseudocode#

pseudocode.js typesets a LaTeX-like algorithm notation into semantic HTML and delegates formulae to KaTeX. The result remains selectable and responds to the page typography.

\begin{algorithm}
\caption{Binary search}
\begin{algorithmic}
\PROCEDURE{Search}{$A, x$}
  \STATE $low \gets 1$
  \STATE $high \gets \mathrm{length}(A)$
  \WHILE{$low \leq high$}
    \STATE $mid \gets \lfloor(low + high) / 2\rfloor$
    \IF{$A[mid] = x$}
      \RETURN $mid$
    \ELSIF{$A[mid] < x$}
      \STATE $low \gets mid + 1$
    \ELSE
      \STATE $high \gets mid - 1$
    \ENDIF
  \ENDWHILE
  \RETURN not found
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}

\begin{algorithm}
\caption{Binary search}
\begin{algorithmic}
\PROCEDURE{Search}{$A, x$}
  \STATE $low \gets 1$
  \STATE $high \gets \mathrm{length}(A)$
  \WHILE{$low \leq high$}
    \STATE $mid \gets \lfloor(low + high) / 2\rfloor$
    \IF{$A[mid] = x$}
      \RETURN $mid$
    \ELSIF{$A[mid] < x$}
      \STATE $low \gets mid + 1$
    \ELSE
      \STATE $high \gets mid - 1$
    \ENDIF
  \ENDWHILE
  \RETURN not found
\ENDPROCEDURE
\end{algorithmic}
\end{algorithm}