Building and Viewing the Documentation

The documentation is built with Hugo using the Hextra theme.

Prerequisites

• Hugo Extended (version 0.124 or later)

On macOS:

brew install hugo

On Windows (via winget):

winget install Hugo.Hugo

On Linux, follow the official installation guide.

Building and Viewing

cd docs

# Install dependencies
hugo mod tidy

# Start the development server
hugo server --disableFastRender -p 1313

The documentation will be available at http://localhost:1313.

Hugo watches for file changes and automatically re-renders the site. Simply refresh your browser to see updates.

Build production version

To build the production version, run the following:

hugo --gc --minify --baseURL

Editing Hugo Configuration

The file docs/hugo.yaml controls the site’s theme, navigation menu, and display options.

Theme Module

Hugo loads the Hextra theme as a module dependency:

module:
  imports:
    - path: github.com/imfing/hextra

Do not remove this block; it is required for the theme to load.

Markup Settings

Under markup: you can configure Markdown rendering:

• goldmark.renderer.unsafe: true — allows raw HTML in markdown content (e.g., custom <div> elements). Set to false to strip unsafe tags.
• highlight.noClasses: false — enables Hextra’s syntax highlighting styles. Change to true to output plain <pre><code> without class attributes.

Navigation Menu

The menu.main: section defines the top navigation bar. Each entry has:

To add a new menu item:

menu:
  main:
    - name: New Section
      pageRef: /new_section
      weight: 7

Ensure the corresponding page file exists under docs/content/new_section/.

Display Parameters

Under params: you can control visual aspects:

• navbar.displayTitle — show the site title in the navbar
• navbar.displayLogo — show the logo in the navbar
• footer.displayCopyright — show a copyright notice in the footer
• footer.displayPoweredBy — show “Powered by Hugo & Hextra” in the footer

All params support true or false toggles. Refer to the Hextra documentation for the full list of available options.

CI/CD: GitHub Pages Deployment

The file .github/workflows/docs.yaml automates building and deploying the documentation to GitHub Pages. It runs on every push to the main branch.

How It Works

The workflow has two jobs:

1. build — checks out the repo, installs Go and Hugo (v0.156.0), runs hugo --gc --minify --baseURL in the docs/ directory, and uploads the docs/public/ output as an artifact.
2. deploy — takes the uploaded artifact and deploys it to GitHub Pages.

Concurrency Policy

The workflow uses concurrency.group: "pages" to prevent overlapping deployments. In-progress builds are allowed to complete rather than being cancelled, ensuring production pages are never partially deployed.

Manual Trigger

To trigger a manual deploy, go to Actions > Deploy documentation to Github Pages on the repository’s GitHub page and click Run workflow.