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#

text

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.

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

toml

[[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.