Features

A tour of what hugodoks renders for every docs site, and the switches that control it.

Sidebar navigation#

Pages under params.docs.navRoot (default /docs) become the left sidebar:

• Leaf pages and sections sort by weight; a page’s icon shows next to its title. Pages without one get a fallback marker — params.docs.navDefaultIcon (default dot; set "" for an empty slot).
• Directories with _index.md render as collapsible <details> groups that auto-open on the active page. The section title links to its _index page; the caret toggles the group. Sibling groups stay open independently, like a file browser, and each group’s open state persists in localStorage across page loads.
• The current page is highlighted and marked aria-current="page".
• Below 768px the sidebar becomes an off-canvas drawer opened by the header’s hamburger button.

Table of contents#

With toc: true in front matter, a sticky “On this page” aside is built from the page’s h2–h3 headings (configure the range with markup.tableOfContents.startLevel/endLevel). The toggle button collapses it and remembers the choice across pages via localStorage.

Search#

Ctrl K (or the header button) opens a FlexSearch modal over /index.json, which the theme generates at build time with each page’s title, section, URL and plain text. Everything runs client-side; no service to operate.

Dark and light themes#

The header toggle flips Pico’s data-theme attribute; the choice persists in localStorage under hugodoks-theme. A tiny inline script in <head> applies the stored (or OS-preferred) theme before first paint, so there’s no flash of the wrong theme. Code blocks follow along: the theme ships Chroma stylesheets scoped to html[data-theme].

Code blocks#

Every code block gets a Copy button in its top-right corner (visible on hover or keyboard focus, always on touch screens). It copies the block’s plain text — line numbers excluded — through the Clipboard API, with a fallback for non-secure contexts, and announces the result to screen readers. Without JavaScript, code blocks are plain blocks. The labels come from the copyCode, copiedCode and copyFailed i18n keys.

Diagrams#

Fenced code blocks tagged mermaid render as Mermaid diagrams. The library is vendored and only loads on pages that contain a diagram, and diagrams re-render when the light/dark theme flips. The Copy button still copies the diagram source.

graph LR
  A[Markdown] --> B[Hugo]
  B --> C[hugodoks]
  C --> D{Docs site}

Page chrome#

• Prev/next pager — links to the previous and next pages within the same section, ordered by weight.
• Edit this page — with docs.editPage and a docs.repoURL, every docs page links to its source file (GitHub, GitLab and Bitbucket URL layouts are detected); docs.lastMod adds a “Last updated” line.
• Section cards — _index.md pages render their children as icon cards using each child’s icon and description.
• Ask AI dropdown — with docs.aiAssist, docs article headers get an “Ask AI” dropdown with prefilled ChatGPT/Claude links to the page; docs.aiAssistIcon/aiAssistLabel customize it.
• Icons — the Phosphor font (regular weight) is vendored; any icon name works in front matter, params, shortcodes and {{ partial "hd-icon.html" "name" }}. Browse them all on the icons gallery.
• Heading anchors — every rendered heading gets a hover anchor link for deep-linking.

i18n and RSS#

UI strings are translated through Hugo’s i18n (i18n/en.toml ships English; your site’s own i18n/ files can override any key). outputs.home includes rss, so the home page also publishes a feed.

Performance and offline builds#

Pico CSS, Chroma themes and all JavaScript are vendored in assets/ and bundled with Hugo Pipes — concatenated, minified and fingerprinted. Nothing is fetched from a CDN at runtime, and the site builds with no network access once the theme itself is fetched.