Customization

• 1: Configuration
• 2: Brand and appearance
• 3: Home and landing pages
• 4: Navigation and menus
• 5: Layouts and page types
• 6: Search
• 7: Command palette
• 8: Keyboard navigation
• 9: Languages
• 10: Versions
• 11: Taxonomies
• 12: Repository links and page info
• 13: Print
• 14: AI-agent support

1 - Configuration

This is the single home of site parameters. Every key the theme reads has a row in one of the tables below, giving its type, default and a one-line description, and linking to the guide that covers it. The guides give pasteable snippets and never repeat the definitions. Page-level parameters (front matter) are in Page parameters.

The tables are grouped by function, one ## each, and the anchors are referenceable — for example /docs/customize/config/#sidebar. An empty default column means the theme has no default: leave the key out and the feature is off.

The layers of hugo.yml

An OINK site’s configuration has four kinds of key, and which layer you change depends on what you are changing:

A minimal working configuration needs only the first two layers:

title: Product Docs
baseURL: https://docs.example.com/
defaultContentLanguage: en
enableGitInfo: true

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

params:
  offline_search: true
  github_repo: https://github.com/example/product-docs

Configuration principles

• The theme’s defaults are conservative; write only the keys you change. Interactive features (local search, image zoom, comments, feedback, the light/dark menu) are off by default, because the theme does not make policy for a site. Trimming a “complete configuration” leaves behind keys you never needed more readily than adding them as you go.

• There is no theme master switch. There is no oink.enabled, no params.oink.* namespace, and no option that swaps between a “Docsy shell” and an “OINK shell”. A switch you cannot find on this page does not exist.

• An invalid value warns and falls back to the documented default. params.ui.typography: solarized reports invalid params.ui.typography "solarized" (allowed: technical | system) -- using "technical" and the site still builds; footer_style: thin, page_width: huge and section_index: grid behave the same way. One typo therefore degrades one setting instead of serving HTTP 500 on every URL under hugo server. It cannot ship silently either: every publishing gate builds with --panicOnWarning, which turns the warning back into a hard failure.

• One warning keeps the value instead of dropping it. A theme_color the theme reads as below AA body text (4.5:1) against its own canvas still ships — a custom canvas or a brand mandate is the author’s call — but says so, and prints the ignoreLogs id that silences it. Treat it as advice, not a rejection: the fix is either a darker color or one line of configuration, and the publishing gate stops the build until you choose. Only an unparseable hex is dropped outright, and that one falls back to the default palette like every other invalid value.

• The theme itself never stops the build. Its templates contain no errorf at all: every invalid value takes the warn-and-fall-back path above. A feature needing an external endpoint — PlantUML, Draw.io, Algolia — warns and stays off when the endpoint is missing, because the theme never connects to a public service on your behalf. An incomplete upstream attribution warns and omits the whole notice, because a partial one reads exactly like a complete one. What does stop a build comes from Hugo rather than the theme: a content reference that resolves to nothing, and a Hugo older than module.hugoVersion.min.

Page-level override precedence

Hugo’s .Param lookup lets most parameters be overridden per page, highest precedence first:

1. The page’s own front matter;
2. cascade in an ancestor section’s _index.md (nearer wins);
3. Site params.

Drop the ui. prefix when writing it in front matter. The site’s params.ui.scroll_spy is simply scroll_spy on a page. A ui: block in front matter is read by nobody and reported by nobody, so a setting that seems to have no effect is worth checking against Page parameters first.

---
title: Wide reference
page_width: wide
navbar_enabled: false
footer_style: slim
scroll_spy: true
---

A cascade sets a whole subtree at once:

---
title: Docs
cascade:
  type: docs
  footer_style: slim
  feedback: true
---

Overrides are for real differences in content. Rebuilding a visual system page by page tends to fall out of step at the next theme upgrade.

The three Goldmark prerequisites

Hugo does not merge a theme module’s markup configuration into the site, so these three must be in the site’s own hugo.yml, or attribute lines, component HTML and mathematics all stop working:

markup:
  goldmark:
    parser:
      # block images may carry an attribute line ({caption=…}, numbered figures)
      wrapStandAloneImageWithinParagraph: false
      attribute:
        block: true
    renderer:
      # HTML emitted by `{{% … %}}` shortcodes has to survive
      unsafe: true
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
  highlight:
    # class-based highlighting, so light and dark can each have a palette
    noClasses: false
  tableOfContents:
    endLevel: 4

Without attribute.block, {.fields}, {.steps} and {caption=…} render as literal text; without passthrough, \(x\) never becomes a formula; without unsafe, the structure of steps and cards is escaped away.

renderer.unsafe: true also lets raw HTML in Markdown through. It is meant for trusted authors, not as a submission filter. Where content comes from untrusted sources, the review belongs in the contribution process.

Site identity and brand

Hugo’s own top-level keys:

Theme parameters:

There is no favicon parameter: the theme scans static/ for conventional names (favicon.ico, favicon.svg, favicon-NxN.png, apple-touch-icon.png, apple-touch-icon-NxN.png) — see Brand and appearance.

Shell types and section roots

The shell follows the page type, not the path. Documentation can live in any directory, with a cascade giving it type: docs.

Blog

Seven keys shape a blog section. They apply to the section named by params.ui.blog_section, and each can be overridden per section through front matter or a cascade on the blog root.

Article authorship and series are taxonomies rather than parameters — see Taxonomies and Writing a blog.

Navbar and footer

The fat footer’s column data comes from data/footer/<language>.yaml rather than from a parameter — see Navigation and menus.

Sidebar

How to use the sidebar is in Layouts and page types; the tree itself comes from the shape of content/ — see Organizing content.

Table of contents

The outline’s levels come from Hugo’s own configuration; the theme controls only the tracking behaviour:

Hide the outline on one page with the front matter notoc: true — see Page parameters.

Pager and page end

The page-end components are in a fixed order — share → feedback → page information → pager → comments — and each has its own switch; backlinks sit in the right rail beside the table of contents.

Search and command palette

Local search is off by default, and the command palette appears only once it is on (the navbar magnifier, Cmd/Ctrl+ with K, /, \).

A custom command record accepts seven keys only — id, title, description, icon, keywords, url, action — and id must match ^[a-z][a-z0-9_-]*$ and must not collide with a built-in action ID. Per-language titles go under languages.<lang>.params.ui.command_palette.commands.

Keyboard

Image zoom

Which images become zoom candidates is in Images.

Typography

Use params.ui.fonts when the faces already exist on the reader’s system or the site has declared them with @font-face. Bundling font files and changing lower-level typography still use the SCSS/CSS entry points — see Brand and appearance.

Comments and feedback

Missing any one of the four required giscus values leaves the comment section unrendered: no error, and nothing appears.

Repository links and page information

Content runtimes

Mermaid, KaTeX, ECharts, Infographic, Asciinema, Swagger UI and Redoc are detected from the content and load only where a page uses them, and only in that page’s HTML output; they have no site switch. Only these need a switch or an external endpoint:

Mathematics needs no parameter, only the passthrough prerequisite.

Output formats

The theme declares its custom output formats but does not enable them for a site: request what you want under outputs. Expensive aggregate and machine-readable outputs remain explicit opt-ins.

outputs:
  home: [HTML, markdown, LLMS, NAVJSON]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

LLMSFULL and BookManifest are enabled in the relevant top-level section’s front matter rather than globally. NAVJSON belongs on outputs.home. The complete examples and constraints are in AI-agent support and Books.

Two parameters for print output:

Languages and versions

Languages are defined with Hugo’s own languages block, and the theme only reads the translation relationships it establishes:

Paired files, anchor alignment and fallback for untranslated pages are in Languages.

Version parameters:

Miscellaneous

Editor completion via generated schemas

The theme ships two generated JSON Schemas under its schema/ directory: site-params.schema.json for a site’s hugo.yaml and front-matter.schema.json for page front matter. They are projections of the theme’s own hugo.yaml defaults (with the comment documentation as hover text) and its parameter-scan registry; the theme’s CI regenerates them and fails on drift, so they can never disagree with the theme you have pinned.

With the VS Code YAML extension, map the site schema in your settings:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/pgsty/oink/main/schema/site-params.schema.json": "hugo.yaml"
  }
}

Pin the URL to your release tag instead of main to match your go.mod pin. Front matter completion depends on your Markdown tooling; point it at front-matter.schema.json the same way. The front-matter schema deliberately omits type constraints, because keys like share and theme_color accept a bare-boolean opt-out beside their ordinary type.

Verifying a configuration change

Run a strict build after changing configuration:

hugo --printPathWarnings --panicOnWarning

It passes only when the output reads Total in … with no ERROR and no WARN. Common errors and what they mean:

A configuration change also needs at least three checks: one page in each language, a page with no translation to see the fallback, and the links under the production baseURL (easy to miss on a subpath deployment).

The theme’s declared Hugo floor is 0.160.1. OINK’s continuous test toolchain is pinned to Hugo Extended 0.165.0; configuration changes are tested once with that pinned version instead of against a version matrix:

# require v0.165.0+extended in this output
hugo version
hugo --printPathWarnings --panicOnWarning

The floor is declared in the theme’s hugo.yaml and theme.toml, and a site’s own module.hugoVersion.min should agree with it. It remains a consumer compatibility declaration, not a second routine CI test leg.

Related

• Brand and appearance — site name, logo, colours, fonts
• Navigation and menus — navbar menu, page actions, footer
• Layouts and page types — shell, sidebar, table of contents
• Page parameters — the full front matter table
• Troubleshooting — locating a build failure

2 - Brand and appearance

This page covers a site’s appearance: the name and logo live in hugo.yml, colours and fonts go through SCSS entry points, and page width and footer shape are parameters. It assumes the site already builds (Quick start).

There are four things to change: hugo.yml, the icons under static/, assets/scss/_variables_project.scss, and assets/scss/_styles_project.scss. Do not edit files inside the theme directory: the theme is a Hugo Module, and an upgrade replaces the whole directory.

Site name

The site name appears in the navbar, the browser title and the footer. A multilingual site writes one per language:

title: Product Docs

languages:
  en:
    title: Product Docs
    label: English
    locale: en-US
    weight: 1
  zh:
    title: 产品文档
    label: 简体中文
    locale: zh-CN
    weight: 2

The top-level title is the fallback, and languages.<lang>.title wins.

Logo and wordmark

The theme ships assets/icons/logo.svg and uses it by default. To replace it, put the icon file in the site’s assets/ or static/ and point the configuration at it.

params:
  logo: images/product-mark.svg
  wordmark: logo.svg

• params.logo is the square mark, shared by the navbar, the sidebar and the footer. Under assets/ it goes through Hugo’s resource pipeline (and can be fingerprinted); under static/ it is published as is. Either way the path is relative to the assets/ or static/ root.
• params.wordmark is the horizontal wordmark. Once set, the navbar uses it instead of “icon + site name”, falling back to params.logo when the screen is too narrow. Left unset, “icon + site name” stays.

Crop the source SVG tight to the artwork, or the sizes will not line up. An SVG needs a viewBox, and its colours should inherit currentColor or hold enough contrast in both light and dark.

This site leaves both unset: the navbar pairs the theme’s own assets/icons/logo.svg with the site title, drawn in the display font.

favicon

The favicon has no parameter. The theme scans the site’s static/ directory for conventional filenames and emits the matching <link> on every page for whichever it finds:

A sufficient minimum is favicon.ico plus favicon.svg plus apple-touch-icon.png. A file with a size suffix has to be square (NxN) or it is not recognized.

Generate these with any graphics tool. The theme needs no Node.js, and Hugo simply publishes what is already in static/.

Extra head metadata such as a Web App Manifest is outside the scan; emit it yourself through the layouts/_partials/hooks/head-end.html hook. To change the discovery rules themselves (a different directory, more filenames), override layouts/_partials/favicons.html in the site’s layouts/.

Accent colour and palette

Colour comes in two layers: Bootstrap’s semantic colours (Sass variables, at compile time) and OINK’s brand layer (CSS custom properties, at run time).

Change the semantic colours first; they decide the tone of buttons, links and callouts:

$primary: #315f8f;
$secondary: #b4762e;
$success: #2c7a4b;
$warning: #9a6700;
$danger: #b42318;

This file is loaded before Bootstrap and the OINK defaults, which is where Sass variables are overridden. To reference a variable or map Bootstrap has already defined, use _variables_project_after_bs.scss instead.

The brand layer is a set of CSS custom properties, and light and dark must be overridden in pairs or one mode leaks the original colour:

:root {
  --td-brand-copper: #a66722;
  --td-brand-mark-from: #1d588c;
  --td-brand-mark-to: #a66722;
}

[data-bs-theme='dark'] {
  --td-brand-copper: #e0a35c;
  --td-brand-mark-from: #7fb8e8;
  --td-brand-mark-to: #e0a35c;
}

The brand properties available are --td-brand-elev (overlay ground), --td-brand-silk (secondary text), --td-brand-copper and --td-brand-copper-dim (the accent and its muted form), --td-brand-line-strong (rules), --td-brand-header-bg (navbar background), --td-brand-shadow-sm / --td-brand-shadow-md (shadows), and --td-brand-mark-from / --td-brand-mark-to / --td-brand-mark-gradient (the brand gradient).

Section theme colour

The brand palette above sets the colour of the whole site. theme_color is the smaller instrument beside it: one hex that tints the accent grounds of the shell, so a reader can tell which part of the site they are standing in without being told.

params:
  ui:
    theme_color: '#6d28d9'
    theme_color_dark: '#a78bfa' # optional

It is more useful per section than site-wide. Written into a section root’s cascade, it gives that whole section an identity — a navy Docs beside a violet Blog and an orange Book — while the site default stays the brand colour:

cascade:
  theme_color: '#6d28d9'
  theme_color_dark: '#a78bfa'

Hugo resolves these cascade values on the section page as well as its descendants, so the pair is declared once. The same resolved pair drives the page’s accent and that section’s mark in the root switcher.

What it touches: the selected sidebar row and the greyed ground its neighbours take under the pointer, hover washes, the outline pill and its travelling rail and dot, a Book chapter’s headings under the pointer, tag and chip hovers, a content card’s hovered edge, a share button’s hover fill, text selection, focus rings, and each root’s mark in the sidebar switcher.

What it deliberately does not touch: prose links, external URLs, and inline code. Those are reading conventions, not brand surfaces — a page dense in identifiers should read as code and prose in every section, and a link should look like a link wherever it is. This is why the accent is its own custom property rather than a repaint of Bootstrap’s link colour.

The dark half is optional. Left out, it is derived by lightening the light colour toward white until it clears AA body text on the dark canvas, so a single-colour author cannot produce an unreadable dark palette. Name it yourself when the derived value no longer matches the brand hue you want. The light colour is the key: theme_color_dark on its own, or beside an invalid theme_color, colours nothing in either mode — the theme warns and keeps the default palette rather than tint dark mode alone.

A page inside a coloured section can decline the colour with the theme’s bare-boolean idiom: theme_color: false in front matter opts that page out — inherited dark half included — and reverts to the default palette without a warning. Any other non-hex value (a number, true, a named colour) warns.

Hugo merges params by key, so a page overriding theme_color inside a section whose cascade also sets theme_color_dark inherits that dark value. Override both, or neither.

Light and dark mode

The theme does not show a light/dark control by default. To enable it:

params:
  ui:
    dark_mode: true

A theme control then appears in the navbar: clicking it toggles light and dark, and hovering or focusing it expands “follow system / light / dark”. The reader’s choice is stored locally in the browser, and with no choice it follows prefers-color-scheme. The switching script sets data-bs-theme before the first paint, so there is no theme flash.

For the dark palette without the control, write dark_mode: { show_menu: false, enable: true }; dark_mode: false (the default) enables neither.

Custom components need readable hover, focus, disabled and selected states in both modes, with at least 4.5:1 contrast for body text and 3:1 for large text.

Fonts

There are two font presets, decided at build time with no JavaScript involved:

params:
  ui:
    typography: technical # technical | system

• technical (the default): interface and body text use the bundled Inter (variable weight, with Latin / Cyrillic / Greek / Vietnamese subsets, while Chinese and emoji fall through to platform fonts), display headings use Chakra Petch, and code uses IBM Plex Mono. All font files are local, and Google Fonts is never requested.
• system: the interface, display, metadata, print and monospace roles all fall back to the platform stack, and the browser requests no brand font. The font files still ship with the theme; they are simply not referenced.

An invalid value warns and falls back to technical, so an ordinary hugo server stays usable; publishing gates run --panicOnWarning, which is where that warning becomes a hard failure. The chosen value is written to <html data-td-typography="…"> and can be confirmed in the browser.

Custom fonts

The font roles are seven CSS custom properties. Override them rather than hunting for component selectors:

ui is the main face: body resolves through it and heading through body, so a single line moves the interface, the prose and the headings together.

From configuration

To swap font families and nothing else, skip SCSS and write params.ui.fonts:

params:
  ui:
    fonts:
      # The main face: interface, body and headings follow it
      ui: "'Source Han Sans SC', 'PingFang SC', sans-serif"
      # Monospace needs a CJK fallback, or mixed code blocks stop aligning
      code: "'Sarasa Mono SC', 'Noto Sans Mono CJK SC', monospace"

These are family names, not font files. The theme never downloads or loads a font because of this key: a family here must be one the reader already has, or one the site declared in an @font-face of its own. End every list with a generic family (sans-serif, monospace, serif) — that is where a reader without your face lands.

Values are gated to plain font family syntax: quoted names, bare identifiers, a leading hyphen (-apple-system), and names spelled in any script (苹方 is a family name). Semicolons, braces, parentheses, url() and angle brackets do not pass. An unknown role or an unsafe value warns and is dropped on its own; the rest of the map still ships. A site that sets nothing gets no style element in <head> at all.

The block renders after the stylesheet, which is what lets an authored face outrank the typography preset at equal specificity.

From a stylesheet

To ship a font file of your own, or to change the face for one kind of content only, use a stylesheet. Put the .woff2 in the site’s static/webfonts/, declare the face in the project stylesheet, then rewrite the roles:

@font-face {
  font-family: 'My Sans';
  font-display: swap;
  font-style: normal;
  font-weight: 400 800;
  src: url('../webfonts/my-sans-variable.woff2') format('woff2');
}

:root {
  --td-ui-font-family: 'My Sans', 'Noto Sans SC', sans-serif;
  --td-body-font-family: var(--td-ui-font-family);
  --td-heading-font-family: var(--td-ui-font-family);
  --td-display-font-family: var(--td-heading-font-family);
}

Roles inherit by ordinary CSS rules, so changing the font for one kind of content needs no component selectors either:

body.td-blog {
  --td-body-font-family: 'My Serif', 'Noto Serif SC', serif;
  --td-heading-font-family: var(--td-body-font-family);
}

A monospace stack needs a CJK fallback, or mixed code blocks fail to align:

:root {
  --td-code-font-family: 'My Mono', 'Sarasa Mono SC', 'Noto Sans Mono CJK SC', monospace;
}

A site migrating from Docsy need not change how it writes this. The old Sass variables still feed the corresponding roles, still work from _variables_project.scss, and take precedence over the preset defaults:

Docsy’s three Google Fonts variables — $td-enable-google-fonts, $td-google-font-name and $td-web-font-path — are no longer read by the theme. Leaving them in _variables_project.scss breaks nothing and does nothing: what ships with the theme is Inter, Chakra Petch and IBM Plex Mono, and neither preset requests anything from Google Fonts. The print role --td-print-font-family follows the body role, and the theme ships no separate font for paper.

YAML accepts font family names only — neither a remote font URL nor arbitrary CSS. Font files and styles must both be auditable local inputs, and an ordinary build makes no network request for a font.

Page width

params:
  page_width: normal # normal | wide | full

page_width controls the overall shell width and can be overridden per page or per section by cascade. Book pages additionally have reading_width (slim / normal / wide), which changes the reading measure of the body rather than the shell. An invalid value in either key warns and falls back during ordinary preview; the warning fails a publishing build with --panicOnWarning.

Footer

params:
  ui:
    footer_style: fat # fat | slim | none
  copyright:
    authors: '[The product team](https://example.com/)'
    from_year: 2026
    to_year: present
  footer_center_info: 'Powered by [Oink](https://oink.pgsty.com)'

• fat (the default): a multi-column link grid plus the copyright line;
• slim: the copyright line only;
• none: no footer at all.

Page front matter (including a section cascade) can override it; this site’s documentation section uses footer_style: slim. An unrecognized value warns and falls back to fat in ordinary preview; strict publishing rejects the warning.

The grid’s data lives in data/footer/<language>.yaml — see Navigation and menus. With fat configured but no data, it degrades to slim automatically, so it can be enabled before the content exists.

params.copyright accepts a Markdown string, or a map of authors / from_year / to_year (present means this year). footer_center_info is inline Markdown in the centre of the footer, and setting it explicitly to an empty string hides that region.

SCSS entry points, and what not to do

A site’s SCSS overrides join the theme’s single style bundle, and a production build still emits one fingerprinted stylesheet with an integrity attribute. Three entry files go under the site’s assets/scss/:

The compilation order is: Bootstrap functions → project variables → OINK defaults and Bootstrap → post-Bootstrap project variables → OINK components and the brand layer → project styles.

The CSS interface has a defined boundary. The seven font roles in Fonts and the --td-brand-* properties are public, and the theme keeps their names and meanings across minor versions. Component aliases such as --td-asciinema-font-family promise only to work within that component, and undocumented variables such as the --td-shell-* family are implementation detail that may be renamed or removed at any time.

What not to do:

• Do not edit any file inside the theme directory (hugo mod overwrites it);
• Do not @import the theme’s internal partials individually — they are not a public Sass interface and their import order may change;
• Do not override baseof.html to change one colour. Use a design variable where one exists, and otherwise write the narrowest selector that works;
• Do not reference a remote stylesheet or a font CDN.

For additional third-party CSS, publish a local resource through the layouts/_partials/hooks/head-end.html hook rather than writing a <link> in Markdown.

Verify

hugo --printPathWarnings --panicOnWarning

• The build prints Total in … with no ERROR and no WARN;
• The page source has data-td-typography="technical" (or your chosen preset) on <html>;
• In the browser the navbar shows your logo and site name, and the tab shows your favicon;
• Switch to dark mode and look again at body text, tables, callouts, code blocks and focus rings. A colour change is easy to verify in only one mode;
• Switch language and confirm the site name changes with it.

To check whether the font really was replaced, inspect any paragraph’s font-family in the browser’s developer tools: it should be the face you declared rather than Inter.

Related

• Configuration — types and defaults of the brand parameters
• Navigation and menus — navbar menu, page actions and footer data
• Layouts and page types — shell, sidebar and table of contents
• Images — images in the body, light/dark pairs and captions
• Home and landing pages — hero, sections and landing data

3 - Home and landing pages

The home page is not a template but a data file: the sections list in data/home/<language>.yaml decides which sections the page has from top to bottom, and each section’s content is looked up by name in the same file. An ordinary page with layout: landing uses the same sections.

Every section is rendered on the server. Prices, star counts, screenshots, avatars and download states all have to exist in the repository before Hugo starts; no section fetches data in the browser.

A site migrating from Docsy’s blocks/* home page has to rewrite it: the theme has no blocks/cover, blocks/section or blocks/feature shortcodes, and keeping them fails the build with template for shortcode "blocks/cover" not found. The two ways forward are the data/home/<language>.yaml described here, or layout: landing on an ordinary page.

Where the home page’s data lives

The home page’s content file keeps only a title and a description:

---
title: OINK
description: A local-first, Hugo-only theme for technical documentation
---

Section data is a file per language:

The lookup order is data/home/<current language>.yaml → data/home/en.yaml → data/home.yaml for a single-language site.

The file has only two levels: a sections list, and the same-named keys that list references.

sections:
  - hero          # uses the hero: key
  - capabilities
  - type: cards   # uses the cards section, reading the release: key
    key: release
  - cta

hero: { … }
capabilities: { … }
release: { … }
cta: { … }

That is how this site’s home page is written; the complete file is data/home/en.yaml in the repository.

A minimal working home page

Paste the following, replace the text and links, and it publishes. Write internal links as site paths without a leading slash, and the theme adds the current language prefix (docs/start/ → /docs/start/).

sections:
  - hero
  - cards
  - cta

hero:
  eyebrow: Local-first · Hugo only
  title_lines:
    - words:
        - { text: PGSTY OINK }
  lead: Components are written in Markdown, assets ship with the theme, and one source produces four outputs.
  image:
    light: images/hero-light.webp
    dark: images/hero-dark.webp
    alt: OINK engineering documentation illustration
  actions:
    - { label: Quick start, url: docs/start/, icon: fa-solid fa-rocket, style: primary }
    - { label: See the components, url: docs/components/, style: ghost }

cards:
  eyebrow: What it does
  title: Everything engineering documentation needs
  columns: 3
  items:
    - title: Markdown-native components
      desc: Callouts, tabs, field lists and file trees are all part of Markdown syntax.
      icon: fa-solid fa-cubes
      url: docs/components/
    - title: Four outputs
      desc: HTML, print, Markdown and RSS from one source, losing nothing.
      icon: fa-solid fa-file-export
      url: docs/customize/agents/
    - title: Local-first
      desc: Fonts, icons, search and diagram runtimes all ship with the theme; no CDN.
      icon: fa-solid fa-plug-circle-xmark
      url: docs/about/features/

cta:
  title: Start from a bilingual site that already works.
  text: Start from OINK Starter, replace the project identity and content, then publish.
  label: Get started
  url: docs/start/
  style: primary

Hero

The hero is the first screen, and the only section with a large title and an illustration.

hero:
  eyebrow: PROJECT 1.0 · Local-first       # small text above the title, with a status dot
  title_lines:                             # the large title, controlled line by line
    - words:
        - { text: PGSTY OINK }
  lead: One sentence saying what this is.  # inline Markdown and <br> allowed
  note: No Node.js required                # a supplementary line with an icon
  note_icon: fa-solid fa-circle-check
  title_size: 4.25rem                      # rem / em / px only
  image:
    light: images/hero-light.webp
    dark: images/hero-dark.webp            # with only one, both modes share it
    alt: First-screen illustration
  media:
    ratio: '1fr 240px'                     # column widths for text and image
    max_width: 240px
    hide_below: md                         # hide the image below sm | md | lg | xl
  actions:
    - { label: Get started, url: docs/start/, icon: fa-solid fa-rocket, style: primary }
    - { label: GitHub, url: 'https://github.com/pgsty/oink', external: true, style: ghost }
  detail: { label: See what it looks like, url: docs/about/showcase/ }

Without title_lines it uses title, and without either the site title. The image is a CSS background: with an alt the container carries role="img", and without one it is hidden from assistive technology.

align: center gives a text-only centred first screen: the text block widens and centres, the title balances its line breaks, and note moves below the buttons. When an image is present too, ordinary preview warns and falls back to start so the image is preserved; a strict publishing build rejects the warning.

The section registry

There are 22 section types, named with hyphens (underscores in older data are normalized). Apart from the hero, each shares the three heading fields eyebrow / title / desc (or text) plus a class.

A misspelled type does not silently disappear: the build emits an unknown section type warning and skips the section. Adding --panicOnWarning in CI turns that into a build failure.

The commonest sections, minimally

Cards and capability panels are the two used most. cards controls its column count with columns:

cards:
  title: Use cases
  columns: 4
  link_label: Learn more
  items:
    - title: Book publishing
      meta: Long form
      icon: fa-solid fa-book-open
      desc: Numbered figures and examples, cross-references, indexes and whole-book print.
      url: docs/write/book/

capabilities is one capability per screen with a structured visual panel on the right, and visual.type must be one of shell, components, code, image or card:

capabilities:
  eyebrow: Value
  title: What engineering documentation needs, out of the box
  items:
    - ref: 01 / Engineering docs
      title: Built for engineers and their documentation sites
      url: docs/start/
      motto: No extra friction from the first build to long-term maintenance
      bullets:
        - 'A [deployment](docs/admin/deploy/) experience that works out of the box'
        - 'Built-in [search](docs/customize/search/) and [languages](docs/customize/i18n/)'
      value: Content teams spend their time on documentation rather than rebuilding a site.
      visual:
        type: code
        title: build.sh
        lines:
          - { class: c, prefix: '# ', text: One command, one deterministic output }
          - { class: p, prefix: '$ ', text: hugo --gc --minify }
          - { class: ok, prefix: '✓ ', text: public/ is ready to deploy }

metrics:
  title: Facts
  animate: true
  items:
    - { value: 2189, compact: true, label: Stars, source: { label: Local CI data, url: 'https://example.org/' } }
    - { value: 32, suffix: '+', label: Languages }

command-box:
  title: Install
  code: hugo mod get github.com/pgsty/oink
  lang: bash
  note: The copy button comes from the on-demand landing runtime.

steps:
  title: Three steps to publish
  items:
    - { title: Clone, desc: Copy the documentation site repository. }
    - { title: Configure, desc: Change three settings., cmd: { code: hugo server } }
    - { title: Publish, desc: Push to GitHub Pages. }

timeline:
  title: Project history
  items:
    - { date: '2024', title: Prototype, desc: The first data-driven sections. }
    - { date: '2026', title: Scenario components, desc: Landing becomes a reusable shell. }

code-plate:
  title: Page configuration
  aria_label: Example configuration
  lang: yaml
  code: |
    layout: landing
    landing: pricing

preview:
  title: What you write is what you get
  file: guide.md            # the filename in the source panel header, default page.md
  source: |                 # the right side renders this Markdown with the site's own hooks
    > [!TIP] Markdown only
    > Callouts, steps and tabs are all ordinary syntax.

    1. Write Markdown
    2. Run `hugo`
    {.steps}

case-study:
  title: Migration outcome
  stats:
    - { value: 12, label: Reusable sections }
    - { value: 0, label: Remote requests }
  quote: "One YAML file replaced a bespoke page template."
  source: A site maintainer

pricing:
  title: Pricing
  tiers:
    - name: Community
      price: Free
      period: forever
      desc: The full open-source capability.
      features: [Every component, Community support]
      cta: { label: Download, url: docs/start/ }
    - name: Professional
      featured: true
      price: $3.4K
      period: /year
      features: [Priority response, Release packages]
      cta: { label: Contact us, url: 'mailto:example@example.org' }

pricing-compare:
  title: Tier comparison
  tiers: [Community, Professional]
  groups:
    - name: Support
      rows:
        - { name: Priority response, cells: [N, Y] }
        - { name: Annual fee, price_row: true, cells: [Free, $3.4K] }

download:
  title: Download
  keys: [prd5]

bar-chart:
  title: Build time
  unit: seconds
  items:
    - { label: Cold build, value: 12.3, group: cold }
    - { label: Warm cache, value: 1.6, group: warm, note: A repeat build on the same machine. }

The download section consumes exactly the data/download/<key>.yaml from Releases and downloads, introducing no second version model.

Turning any page into a landing page

Two lines of front matter make an ordinary content page a landing page: a full-width canvas that keeps the navbar, the command palette and the footer, and drops the sidebar and the outline.

---
title: Pricing
layout: landing
landing: pricing
---

The data lives in a directory parallel to the home page’s, likewise split by language:

A non-home landing page looks for its data in this order. When nothing is found, ordinary preview warns and renders the landing shell with no sections; a strict publishing build rejects the warning:

1. sections in the page’s front matter;
2. data/landing/<key>/<exact language>.yaml;
3. The exact-language entry inside a single data/landing/<key>.yaml;
4. The English or language-less record.

Small amounts of data can go in front matter, but landing: and sections: are mutually exclusive:

---
title: Pricing
layout: landing
sections:
  - type: hero
    data:
      title: Publish a product page with Hugo alone
      actions:
        - { label: Read the docs, url: docs/, style: primary }
  - type: download
    data: { title: Download, keys: [prd5] }
  - cta
---

Writing a section entry

Each item in sections is either a type-name string or a map:

Languages and local facts

Narrative text belongs in per-language files (zh.yaml / en.yaml). A shared record of facts can also fall back field by field: <field>_<exact language> → <field>_<base language> → <field>, with - in a language tag normalized to _. A Chinese site resolves title_zh_cn, then title_zh, then title. camelCase suffixes are not accepted.

Display text inside a section is site data, not the theme’s i18n strings. Only the theme’s own controls — marquee pause, pricing states — use translation keys. Configuring a multilingual site as a whole is in Languages.

A few optional facts on the landing shell are local too, written in hugo.yml and never fetched at runtime:

params:
  offline_search: true
  ui:
    landing_search: true          # boolean; the palette appears only if the site enabled offline_search
    github_stars: 2189            # a committed number, never a GitHub API request
    alt_site: { label: 中文站, url: 'https://example.cn/' }

The footer is not home page data: it reads data/footer/<language>.yaml (or data/footer.yaml on a single-language site), and this site has one per language. A leftover footer key in data/home/<language>.yaml warns and is ignored in ordinary preview; --panicOnWarning rejects it while naming the new location. How to write it is in Navigation and menus.

Output

With JavaScript disabled the server-rendered document is still complete. The marquee’s duplicate track stays out of the accessibility tree, and pausing uses a checkbox that needs no JavaScript; with the reader’s reduced-motion preference on, movement and reveal are switched off.

Verify

1. The build is warning-free: hugo --printPathWarnings --panicOnWarning. A misspelled type, a missing data key, and landing alongside sections all surface here.
2. Open the home page and any landing page, compare each section against the data file, and look at every language.
3. Reload with JavaScript disabled: the content is still there, only without motion.
4. Look at both light and dark, confirming image.light and image.dark are each correct.
5. When deploying to a subpath, confirm internal links and images all carry the prefix.

Related

• Brand and appearance — site name, logo, colours and fonts
• Navigation and menus — navbar, footer and the language menu
• Releases and downloads — the data behind the download section
• Languages — enabling languages and splitting data by language
• Configuration — full definitions of params.ui.landing_search and the rest

4 - Navigation and menus

This page covers the ways a reader moves between pages: the navbar menu, the section switcher, breadcrumbs, page actions, previous / next, and the footer. The sidebar tree and the outline belong to Layouts and page types.

Navigation has no second information architecture: the navbar comes from Hugo’s menus.main, and the sidebar from the shape of content/. The theme reads no parallel navigation tree such as a docs.json or a navigation.yaml.

The navbar menu

Top-level entries go in each language’s menus.main:

languages:
  en:
    menus:
      main:
        - identifier: docs
          name: Docs
          pageRef: /docs
          weight: 20
        - identifier: blog
          name: Blog
          pageRef: /blog
          weight: 50
        - identifier: download
          name: Download
          pageRef: /download
          weight: 60
          params:
            icon: fa-solid fa-download

A lower weight comes first. pageRef points at a site page and url at an external one; an external link automatically gains target="_blank", rel="noopener noreferrer" and an external-link mark. identifier is the stable handle configuration uses to reference the entry (quick_links and sidebar_root_menu match on it), name is translated per language, and the identifier is not.

A menu entry can also hang off a page’s front matter, which suits “this page is itself a top-level entry”:

---
title: Download
menu:
  main:
    weight: 30
---

The GitHub entry at the right of the navbar is not a menu item: it comes from params.github_project_repo (falling back to params.github_repo). A menu entry identified as github is skipped by the menu area and never shows. To change that entry’s target, change the repository parameters — see Repository links and page info.

Dropdowns

Use Hugo’s parent to establish a parent-child relationship. Only one level of children is supported:

menus:
  main:
    - identifier: docs
      name: Docs
      pageRef: /docs
      weight: 20
    - identifier: docs-start
      parent: docs
      name: Get started
      pageRef: /docs/start
      weight: 10
      params:
        icon: fa-solid fa-rocket
        description: Start from OINK Starter, customize in layers, deploy
    - identifier: docs-components
      parent: docs
      name: Components
      pageRef: /docs/components
      weight: 20
      params:
        icon: fa-solid fa-cubes

• Every entry is one icon and one title on its own row, in one moderate-width column. A child’s params.description is configuration data only; the panel never renders it.
• The parent is itself an ordinary link: hovering or focusing it expands the panel, and clicking or pressing Enter goes to the parent page. There is no separate expand arrow, and a touch reader lands on the parent page, whose body lists the same links.
• Keyboard: the down arrow expands and focuses the first item, Esc closes and returns focus to the link, and clicking outside closes it.
• The 0.5 params.columns parameter is retired: setting it emits a build warning and the panel keeps its single column.
• A third level warns at build time and degrades to a static group heading; it does not produce a third-level flyout. Put deeper levels in the sidebar.

Menu icons

Below lg a menu entry is reduced to its icon, so every top-level entry should have one. Icons resolve in this order:

1. icon in the target page’s front matter;
2. The menu entry’s own params.icon;
3. A built-in default matched by identifier or section name (docs, blog, examples, community, about, download, github and others);
4. fa-solid fa-link when none matched.

An icon is one Font Awesome class pair, with the free faces supplied locally by the theme:

menus:
  main:
    - identifier: handbook
      name: Operations handbook
      pageRef: /handbook
      weight: 40
      params:
        icon: fa-solid fa-screwdriver-wrench

Taxonomy menus

A top-level entry pointing at a taxonomy page (/tags/, /categories/) needs no hand-written submenu: the panel renders a grid of “term + count” chips, ordered by descending count.

menus:
  main:
    - identifier: tags
      name: Tags
      pageRef: /tags
      weight: 60

Enabling taxonomies is in Taxonomies.

Navbar controls

The navbar is 50px tall and holds, left to right: the brand (logo or wordmark), the menu area, search, version, language, theme, GitHub. Home and Landing pages keep a final drawer menu button at the right edge. The navbar renders on every layout; documentation, blog and taxonomy pages use the same controls without that Landing drawer.

The navbar has a full desktop tier and a compact icon tier:

The individual controls are switched on elsewhere: the search icon needs params.offline_search (see Search), the version menu needs params.versions (see Versions), the language menu appears automatically with two or more languages configured (see Languages), and the theme control needs params.ui.dark_mode (see Brand and appearance).

Auto-hide

params:
  ui:
    navbar_autohide: true

With it on, the navbar leaves the normal flow and rests above the viewport, sliding out only when the pointer enters the middle 60% of the area above its original position (or keyboard focus arrives), and it overlays the body rather than pushing it down. 64px at each side is outside the wake zone, so it does not cover the collapsed sidebar and outline restore buttons.

It is disabled automatically below 768px, on a coarse pointer, and on a touch-only device, where the navbar stays visible. A top-level navbar_autohide in page front matter or a section cascade overrides it per section.

Turning the navbar off

params:
  ui:
    navbar_enabled: false

It can also be turned off for one page or one section:

---
title: Docs
cascade:
  navbar_enabled: false
---

With it off, the theme restores the interface the navbar carried: mobile subnavigation, a brand and search row at the top of the sidebar, and utility buttons on the outline rail. The switch suits pages that must own the viewport; it is not a general layout preference. This site’s documentation section uses it: documentation pages navigate through the sidebar, and the navbar is one row too many.

The section switcher

The row at the top of the sidebar is the section switcher, deciding which tree is shown. Its entries are built in order and deduplicated: every top-level section → every section anywhere with sidebar_root_for: self → the currently resolved root.

params:
  ui:
    sidebar_root_enabled: true
    sidebar_root_menu: true

To let a large subtree become a root of its own (a versioned API reference, a self-contained handbook), in its _index.md:

---
title: API reference v2
sidebar_root_for: self
sidebar_root_link_self: true
---

self makes the section index and all its descendants use the new tree; children leaves the index in the parent tree and binds only the descendants. To keep a top-level section out of the switcher, set sidebar_root_menu: false in its front matter.

With one entry the switcher degrades to a borderless link; two or more make it a dropdown. The tree below it still has the section index as its first link: the switcher picks a tree, and the root link picks a document.

Breadcrumbs and page actions

An ordinary content page has a breadcrumb row above its title, and that row’s right end carries the page actions. A top-level section omits a single-level breadcrumb that would only repeat the title, and the action buttons stay where they are.

params:
  ui:
    breadcrumb: false

Breadcrumb labels use the localized linkTitle, and the hierarchy matches the sidebar.

The page action menu

Page actions are the split button at the end of the title row: the left half copies this page’s Markdown in one click (turning into a green tick on success), and the arrow on the right expands the full menu. The menu has two groups — taking the content away, and changing or producing it:

params:
  ui:
    page_context_menu:
      enable: true
      assistant_links: false
      links: []

The assistant entries are off by default: on a click the full current URL (query and fragment included) goes to a third party with a localized prompt, while the body is not uploaded. Before enabling it, confirm no sensitive information appears in URLs, and disclose the boundary in the privacy statement. A page can narrow the site policy with a boolean assistant_links in front matter, but cannot enable it on the site’s behalf.

Custom external actions come last in the menu, and url supports three URL-encoded placeholders:

params:
  ui:
    page_context_menu:
      links:
        - name: Ask the internal assistant
          icon: fa-solid fa-wand-magic-sparkles
          url: https://assistant.example.com/new?source={markdown_url}&title={title}

The placeholders are {url} (the page’s full address), {title} (the page title) and {markdown_url} (the Markdown version’s address).

On the blog root section and its first-level subsections, the left half becomes the RSS subscription link while “copy as Markdown” stays in the menu. A page with no Markdown output loses the left half, and the arrow becomes an “Actions” button with a label.

These actions are also entries in the command palette.

The pager

Previous / next at the end of the body are two text links, ordered by the sidebar’s visible tree: root page → first page → through to the last. The root has no previous, and the last page has no next. Where a site provides data/docs_nav.json, that explicit tree decides the paging order too — and the section index on a docs or book section the file declares, so the sidebar, the pager and the index can no longer show the same children in three different orders. A section the file does not declare, and a site without the file, keep walking the content tree. See Layouts and page types.

params:
  ui:
    pager_types: [docs, book, blog]

pager_types accepts only docs, book and blog; any other value warns and is dropped. A page opts out through front matter:

---
title: Appendix
pager: false
---

The same order is written into <head>: with a previous or next page, it emits <link rel="prev"> and <link rel="next"> so browsers and crawlers can see the reading sequence.

<link rel="prev" href="/docs/customize/home/">
<link rel="next" href="/docs/customize/layout/">

Paging applies to HTML output only. Print, Markdown and RSS have neither the links nor the two rel relationships.

The pager is the third of the four page-end components (feedback → annotation → pager → comments), in a fixed order with four independent switches.

Backlinks

The pages that link to a page can be listed in the right rail, as a “Linked from” group with a link icon below the table of contents and above the taxonomy clouds, expanded by default; below the xl breakpoint it moves into the sidebar drawer with the table of contents. A reader who arrived from search sees which pages consider this one worth pointing at, and where it sits in the rest of the site. It is off until a site asks for it:

params:
  ui:
    backlinks: true

A page overrides it in front matter, and a section cascades it to everything below:

---
title: Docs
cascade:
  backlinks: true
---

The index is derived at build time from what authors already write: an ordinary Markdown link, or a ref / relref shortcode, in the page source. There is no new syntax to learn, nothing to migrate, and no JavaScript — the list is in the HTML. Fenced and inline code are stripped before scanning, several links to one target merge into a single entry, and self links, external links, mailto: and same-page anchors never count. A fragment is dropped when identifying the target page, and each language has its own graph, so a Chinese page never appears under an English one. Entries are sorted by stable page path, so the same content builds the same order every time, and the block is absent entirely — no heading, no empty container — when nothing links in.

The first eight entries are visible and the rest fold behind a native “Show N more” disclosure, so a heavily referenced page cannot swallow the rail; no JavaScript is involved. Each entry carries its source page’s description, shown on hover.

Reading the source has a known limit: a URL inside a custom shortcode’s parameters, or a raw <a href>, does not become an edge, and a destination that cannot be resolved is dropped without a warning. This is a navigation enhancement, not a link checker; keep using a link checker for broken links.

A non-boolean value warns, falls back to off and fails a build run with --panicOnWarning, while hugo server keeps working.

The page’s Markdown output carries the same list, introduced by “Backlinks:”. RSS omits it, and the print output format omits it with the rest of the rail.

This site enables it site-wide: look at this page’s right rail for the real thing, and the most-referenced page — Configuration — lists more than forty inbound links, most of them folded behind the disclosure.

The footer

The footer’s shape comes from params.ui.footer_style (fat / slim / none — see Brand and appearance). The fat link grid reads data/footer/<language>.yaml. It is not a menu, and the theme has no menus.footer:

brand:
  name: Product Docs
  tagline: A short description that **supports Markdown**.
  slogan: Close to the product, with clear answers.
columns:
  - title: Docs
    links:
      - { label: Get started, url: /docs/start/ }
      - { label: Components, url: /docs/components/ }
  - title: Project
    links:
      - { label: GitHub, url: https://github.com/pgsty/oink, external: true }
      - { label: Releases, url: /blog/release/ }

• Without brand.name and brand.logo it falls back to the site’s own brand name, logo and wordmark; tagline and slogan render Markdown.
• An internal url resolves against the current language root; external: true opens in a new tab with rel="noopener noreferrer".
• The grid has as many columns as the data does.
• A single-language site can use data/footer.yaml.
• With fat configured but no data, it degrades to slim automatically, so it can be enabled before the content exists.

The fat footer’s copyright row has a collapse arrow at its right end, hiding or restoring the link grid above it. It starts expanded, and the reader’s choice is kept in localStorage under td-footer-collapsed across pages. slim and none have no such button, and it is unrelated to focused reading mode.

Every rendered bottom bar ends with the same icon dock: version, language, theme, then keyboard help. Each configured menu opens upward; the version trigger stays icon-only while its choices keep their full labels. The fat footer’s collapse arrow follows those four controls. The sidebar has no second copy of the dock, and footer_style: none removes the bar with the footer.

The copyright row and the centre note are parameters — see Configuration.

Verify

hugo --printPathWarnings --panicOnWarning

After changing navigation, check each of these:

• The build has no Navbar menu … supports one interactive child level warning; one means the menu is three levels deep;
• On the desktop: clicking a parent goes to the parent page, hovering expands the panel, and Esc closes it;
• Narrow the window below lg: every top-level entry still has an icon, and one without an icon is blank at this width;
• Below md: Home and Landing navbars keep search and the drawer button on the right; version, language, theme and keyboard help stay in the persistent footer bottom bar;
• The switcher at the top of the sidebar lists every top-level section, with the current one marked;
• On any documentation page, E / Q page in sidebar order, and the page source has matching rel="prev" / rel="next";
• With backlinks on, grep td-backlinks public/<a page that is linked to>/index.html finds the block, and a page nothing links to has no such markup at all;
• Open the page action menu and confirm what should be there is, and what should not is not (for example “open a project issue” with no github_project_repo configured).

Related

• Layouts and page types — sidebar tree, outline and shell types
• Configuration — defaults of the navigation parameters
• Command palette — page actions and custom commands
• Repository links and page info — the edit, history and issue links
• Organizing content — how the directory structure decides the sidebar

5 - Layouts and page types

This page covers a page’s skeleton: whether it has a sidebar, how wide that is, how deep the outline goes, and whether a section index is a list or cards. Where content goes is in Organizing content; this page is only about the shell.

The rule is that the shell follows type, not the path. Documentation can live anywhere under content/ as long as it has type: docs.

Shell types

params.ui.shell_types lists the types that use the reading shell with a sidebar:

params:
  ui:
    shell_types: [docs, book, blog, swagger]

Taxonomy and term pages are not in this table but use the same shell.

Assigning a type to a subtree uses a cascade, which is how documentation ends up at an arbitrary path:

---
title: Operations handbook
type: docs
cascade:
  type: docs
---

Section roots are only navigation starting points

params:
  ui:
    docs_section: docs
    blog_section: blog

These two keys do not decide the shell. They tell the theme where the documentation and blog trees are rooted, for resolving the sidebar root, quick links and default icons. The content/handbook/ example above still has the documentation shell, and leaving docs_section at docs does not affect it.

To make a docs page’s sidebar root the site home rather than the documentation section:

params:
  ui:
    docs_sidebar_root: home # home | section

Those are the only two values. Anything else warns and uses section in ordinary preview; --panicOnWarning rejects the warning during publishing.

Documentation at the site root

A documentation-first site can publish the docs section at the URL root while the source stays in content/docs/. Three pieces of configuration are needed together.

The first uses Hugo’s own permalinks to drop the docs/ segment from URLs:

permalinks:
  page:
    docs: /:sections[1:]/:slug/
  section:
    docs: /:sections[1:]

The second keeps the physical site root index usable as a link target while no longer competing for the same output path. Every language’s site root index (content/_index.md, content/_index.zh.md) needs it:

---
title: Product Docs
build: { render: link }
---

The third declares the sidebar root to be the site home, so the sidebar and the pager share one tree:

params:
  ui:
    sidebar_root_enabled: true
    docs_sidebar_root: home

With docs_sidebar_root: home, every top-level section of the site home enters that tree. Overview sections that are not part of the reading sequence — blog, community, download — opt out with toc_root: true in their own _index.md, which keeps them out of the tree and out of the paging order:

---
title: Blog
toc_root: true
---

Documentation then shares the URL root with blog, community and the rest. Build with --printPathWarnings and resolve every duplicate target before publishing.

Landing pages

Any page with layout: landing uses the landing layout: navbar + a body assembled from sections + footer, with no sidebar. How to write the data is in Home and landing pages.

params:
  ui:
    landing_search: true

landing_search: false removes the search entry point from the landing shell and affects no other page.

Sidebar

The sidebar tree comes from the shape of content/, ordered by weight and labelled with linkTitle where one exists. What is adjustable is density and size:

params:
  ui:
    sidebar_menu_compact: true
    sidebar_menu_foldable: true
    sidebar_menu_truncate: 2000
    sidebar_width_min: 220
    sidebar_width_max: 480
    sidebar_item_overflow: ellipsis # ellipsis | wrap
    sidebar_expand_levels: 2

• sidebar_menu_compact expands only the current branch and its neighbours; false expands the whole tree.
• sidebar_menu_foldable lets the reader expand and collapse sections manually. Blog sections are expanded by default; to collapse one by default, write sidebar_expanded: false in its _index.md.
• sidebar_expand_levels is how many levels are expanded by default.
• sidebar_menu_truncate is the maximum entries rendered per section, so a thousand-page tree does not inflate the HTML past usability.
• sidebar_width_min / sidebar_width_max bound drag-resizing on the desktop, in pixels. The reader’s adjusted width is kept locally, and double-clicking the divider restores the default.
• sidebar_item_overflow defaults to ellipsis (long titles truncate); a site with many long titles can use wrap.

Fold state, width and scroll position are stored locally per language. Below md the sidebar becomes a drawer with a backdrop.

To drop the sidebar on one page, use front matter:

---
title: Full-screen report
sidebar_enabled: false
---

An explicit navigation tree, data/docs_nav.json

The sidebar tree is derived from content/ by default. A site may also supply an explicit navigation manifest, and the theme renders from it when three conditions hold together:

• The site has a data/docs_nav.json containing a sections key;
• The page’s type is docs or book;
• The resolved sidebar root is not the site home.

The file is a nested node tree. Each node’s page points at a content path, url is its link, and children are its children; active_path_by_url records the ancestor chain for each URL, used for highlighting the current entry:

{
  "sections": [
    {
      "page": "/docs/start",
      "url": "/docs/start/",
      "children": [{ "page": "/docs/start/install", "url": "/docs/start/install/" }]
    }
  ],
  "active_path_by_url": {
    "/docs/start/install/": ["/docs/start/"]
  }
}

URLs have their language prefix stripped before comparison, so one file serves every language.

That tree also decides the paging order, so the sidebar and previous / next never disagree. An empty sections array warns and falls back to the content tree; a page that does not exist warns and skips that entry. Strict publishing rejects either warning. Placeholder nodes with manual_link and sidebar_divider rows stay in the sidebar without becoming paging targets.

It suits a site whose navigation order is generated by an external tool — a manual migrated from a Sphinx toctree that has to freeze its existing chapter order, say. Where order is maintained by weight in content/, the file is not needed.

Sidebar icon density

An icon in a page’s front matter appears in the sidebar. Icons on every leaf page reduce readability, so a density policy controls them:

params:
  ui:
    sidebar_icon_policy: groups # all | groups | none

An invalid value only warns and falls back to all rather than failing the build. This site uses groups.

Expanding headings in the sidebar

Book pages can expand an h2–h4 branch under the current sidebar row, which helps navigation inside a long chapter:

params:
  ui:
    sidebar_headings: 3 # false | true | 2 | 3 | 4

An integer sets the deepest level expanded (2–4), true means 2 (h2 only), and false turns it off. Out of range warns and disables the branch in ordinary preview; strict publishing rejects the warning. It applies to type: book pages only, and expands only under the current sidebar row.

Table of contents

The right-hand outline is generated by Hugo from the Markdown headings, and the levels collected are Hugo’s own configuration:

markup:
  tableOfContents:
    startLevel: 2
    endLevel: 4
    ordered: false

The theme governs only the tracking behaviour:

params:
  ui:
    scroll_spy: false