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.