Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Customization

Configure the site brand, navigation, layout, search, languages, versions, print output, and agent output.

Use this section to configure site parameters in hugo.yml, data files under data/, and style entry points under assets/. To write individual pages and their front matter, see Authoring.

Find it by what you want to change

What you want to change Page
Site name, logo, favicon Brand and appearance
Colors, light and dark mode, fonts Brand and appearance
The navbar menu and its dropdowns Navigation and menus
Sidebar width, icon density, outline depth Layouts and page types
The home page and landing pages Home and landing pages
Full-text search and its index scope Search
What appears in the command palette Command palette
Keyboard shortcuts Keyboard navigation
Adding a language Languages
Multi-version sites and the archive banner Versions
Tags and categories Taxonomies
Edit this page, last modified, contributors Repository links and page info
Print and whole-chapter export Print
llms.txt and the per-page .md output AI-agent support
A parameter’s type and default Configuration

Comments, analytics, and deployment require an external service. See Operations.

1 - Configuration

Find every site parameter that the theme reads, with its type, default, description, and related guide.

This page is the complete reference for site-level parameters in hugo.yml. Every key that the theme reads appears in a table below with its type, default, short description, and a link to its dedicated guide for copy-ready examples. For page-level front matter parameters, see Page parameters.

The tables are grouped by function, with one ## heading per group (so you can link directly to anchors such as /docs/customize/config/#sidebar). An empty default column means the theme has no default—if you omit the key, that feature stays off.

The layers of hugo.yml

An OINK site’s configuration has four kinds of key. Choose the layer that controls the feature you want to change:

Layer Examples Who defines it
Hugo’s own top-level keys baseURL title languages markup outputs taxonomies module Hugo itself. See gohugo.io for behavior
Top-level params logo offline_search github_repo version page_width comments Site-level options the theme reads
params.ui.* navbar_enabled sidebar_width_min typography pager_types The shell, navigation and reading interface
params.<runtime> mermaid plantuml drawio markmap Each content runtime’s own switch and endpoint

A minimal working configuration needs only the first two layers (including the three Goldmark settings that power OINK’s native Markdown components):

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

markup:
  goldmark:
    renderer:
      unsafe: true
    parser:
      attribute:
        block: true
      wrapStandAloneImageWithinParagraph: false
  highlight:
    noClasses: false

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

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. Local search, image zoom, comments, feedback, and the light/dark menu are off by default. The site chooses its policy for these interactive features. Add keys as needed. Reducing a “complete configuration” can leave unnecessary keys.

  • There is no theme master switch. There is no oink.enabled or params.oink.* namespace. No option switches between a “Docsy shell” and an “OINK shell”. A switch that is absent from this page does not exist.

  • An invalid value warns and falls back to the documented default. The setting params.ui.typography: solarized reports invalid params.ui.typography "solarized" (allowed: technical | system) -- using "technical". The site still builds. The settings footer_style: thin, page_width: huge, and section_index: grid behave the same way. One typo therefore changes one setting instead of producing HTTP 500 on every URL under hugo server.

  • One warning keeps the value instead of dropping it. If theme_color is below AA body-text contrast (4.5:1) against the theme canvas, the color still appears in output. The author may choose it for a custom canvas or brand requirement. The warning includes the ignoreLogs id that can silence it. Use a darker color or silence the warning with one configuration line. Only an unparseable hex value is discarded and falls back to the default palette.

  • The theme itself never stops the build. Its templates contain no errorf. Every invalid value uses the warning and fallback behavior above. Draw.io and Algolia warn and stay off when their required service configuration is missing. OINK 1.4.0’s PlantUML renderer needs no endpoint for local mode; an invalid explicit endpoint warns and disables rendering. The theme never chooses a public service for you. Incomplete upstream attribution produces a warning and omits the entire notice. A partial notice could appear complete. Hugo can still stop a build if a content reference resolves to nothing or its version is below module.hugoVersion.min.

Page-level override precedence

Hugo’s .Param lookup lets you override most parameters per page. It applies the following precedence, from highest to lowest:

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

Remove the ui. prefix in front matter. The site key params.ui.reading_time becomes reading_time on a page. The theme ignores a front matter ui: block and does not report it. If a setting has no effect, first check Page parameters.

content/docs/wide-reference.md
---
title: Wide reference
page_width: wide
navbar_enabled: false
footer_style: slim
reading_time: false
---

A cascade sets a whole subtree at once:

content/docs/_index.md
---
title: Docs
cascade:
  type: docs
  footer_style: slim
  feedback: true
---

Use overrides for actual content differences. Separate visual systems on individual pages can become inconsistent after a theme upgrade.

The three Goldmark prerequisites

Hugo does not merge a theme module’s markup configuration into the site. Put these three prerequisites in the site’s own hugo.yml. Without them, attribute lines, component HTML, and mathematics do not work:

hugo.yml
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\) does not become a formula. Without unsafe, Hugo escapes the structure of steps and cards.

The setting renderer.unsafe: true also permits raw HTML in Markdown. It is for trusted authors and is not a submission filter. Review untrusted content in the contribution process.

Site identity and brand

Hugo’s own top-level keys:

title , string
Site name, shown in the navbar, <title> and the footer
baseURL , string
The production domain. Include the path segment for a subpath deployment
copyright , string
Fallback for the copyright line, rendered as HTML when params.copyright is unset
enableGitInfo , boolean , defaultfalse
Required before “last modified” and commit information exist
enableRobotsTXT , boolean , defaultfalse
Generates robots.txt
enableEmoji , boolean , defaultfalse
Allows :smile: shortcodes

Theme parameters:

params.logo , string , defaulticons/logo.svg
Brand mark. May use an assets/ resource or a static/ path. See Brand and appearance
params.wordmark , string
Horizontal wordmark. If set, replaces “icon + site name” in the navbar
params.description , string
Site description, the meta fallback when a page has no description
params.copyright , string or map
A string renders as Markdown. A map accepts authors, from_year, and to_year. The value present means this year
params.footer_center_info , string , defaultPowered by Oink
Inline Markdown in the footer center. An empty string hides it
params.author , string or map
The RSS author. A map accepts name and email
params.ui.theme_color , string
#rgb/#rrggbb hex color for shell accent backgrounds. Does not affect prose links or inline code. See Brand and appearance
params.ui.theme_color_dark , string , defaultderived
The dark accent color. If omitted, the theme derives it from theme_color until it meets AA contrast on the dark canvas

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.

params.ui.shell_types , list , default[docs, book, blog, swagger]
Which types use the reading shell with a sidebar — see Layouts and page types
params.ui.docs_section , string , defaultdocs
The documentation section’s root directory name, used for navigation resolution only
params.ui.blog_section , string , defaultblog
The blog section’s root directory name
params.ui.docs_sidebar_root , enum , defaultsection
With section, a docs sidebar starts at the documentation section. With home, it starts at the site home. An invalid value warns and uses a fallback
params.ui.quick_links , list , default[docs_section, blog_section]
Top-level menu identifiers listed by the command palette on an empty query — see Command palette
params.ui.sidebar_root_enabled , boolean , defaulttrue
Allows a subsection to become its own sidebar tree with sidebar_root_for: self
params.ui.sidebar_root_menu , boolean , defaulttrue
Shows the section switcher above the sidebar. With only one entry, it becomes a plain link
params.ui.section_index , enum , defaultlist
Child list style on a section index: list or cards, overridable per section
params.ui.section_index_columns , integer , default2
Column count when section_index: cards

Expo albums

OINK 1.3.0 adds expo to the default shell_types list and supports these settings:

params.ui.expo.images , string , defaultimages/*
Pattern for image resources in the bundle
params.ui.expo.mode , enum , defaultwall
wall, cards, or seamless
params.ui.expo.size , integer , default240
Target size from 160 to 360 CSS pixels

A page’s expo block replaces the site block. Absent fields use built-in defaults. Stored reader choices override the author defaults for mode and size. See Expo defaults for the complete rules.

Blog

These settings 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.

The layout guide compares rows, cards, tables, and galleries. OINK v1.4.0 supports all four layouts and the blog_gallery settings below.

params.ui.featured_image , enum , defaultnone
Controls the article’s featured image on single pages and section indexes. The mode none renders nothing. The mode banner shows a 16:9 figure above the title. The mode wash shows the image behind the article header at a tenth of its opacity. The mode hero uses a full-bleed shell background and moves the opening down. It uses the same image as the page card and og:image, so they cannot differ. Without an image, every mode renders nothing
params.ui.blog_index , enum , defaultlist
list shows horizontal entries, cards shows regular image cards, table shows compact rows, and gallery shows linked covers. All sort by date, newest first. Only a standalone table with blog_index_toggle: false shows the complete section without pagination
params.ui.blog_index_columns , integer , default3
Column count for blog_index: cards. Regardless of this value, uses two columns between md and xl breakpoints and one below md
params.ui.blog_index_size , integer , default12
Posts per page for list, cards, gallery, and all four views when switching is enabled. A standalone table ignores it
params.ui.blog_index_toggle , boolean , defaultfalse
Publishes all four layouts and lets readers cycle through list → cards → table → gallery, remembering their choice. When false, publishes only the configured layout
params.ui.blog_gallery.mode , enum , defaultwall
Gallery arrangement: wall has 6px gaps, seamless has no gaps, and cards uses masonry with visible captions. This is independent of the outer blog_index layout
params.ui.blog_gallery.size , integer , default240
Target gallery tile size, 160–360 CSS pixels. Does not set the number of posts per page
params.ui.toc_style , enum , defaultfixed
Right-rail presentation. The mode fixed pins a panel to the viewport. The mode flow uses a wider panel in content flow. It starts with the article and pins only on scroll
params.ui.toc_taxonomies , boolean , defaulttrue
Taxonomy term clouds in the right rail. If the rail has neither a table of contents nor clouds, it renders nothing

A page or cascade blog_gallery block replaces the whole site block. Missing fields use wall and 240; invalid values warn and fall back to those defaults. Saved gallery arrangement and size override the author defaults and are independent of Expo preferences. See Gallery.

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

params.ui.navbar_enabled , boolean , defaulttrue
Whether the site navbar renders; overridable with a top-level navbar_enabled on a page — see Navigation and menus
params.ui.navbar_autohide , boolean , defaultfalse
The navbar retracts above the viewport. It returns when the pointer enters the wake zone. Inactive below 768px and on coarse pointers
params.ui.footer_style , enum , defaultfat
fat is a multi-column grid plus the copyright line, slim is the copyright line only, none renders nothing. An invalid value warns and falls back
params.ui.dark_mode , boolean or map , defaultfalse
true enables the dark palette and theme control. For only the control, use dark_mode: { show_menu: true }
params.ui.breadcrumb , boolean , defaulttrue
Breadcrumbs; false turns them off. A top-level section already omits a one-level breadcrumb
params.ui.page_context_menu.enable , boolean , defaulttrue
The page action split button beside the title
params.ui.page_context_menu.assistant_links , boolean , defaultfalse
Shows “Open in ChatGPT / Claude”; clicking sends the full URL off-site
params.ui.page_context_menu.links , list , default[]
Custom external actions; url supports the {url}, {title} and {markdown_url} placeholders
params.ui.github_stars , string or number
Star count on the navbar GitHub mark. Uses a local constant and makes no request
params.ui.alt_site , map
Sibling-site link in a single-language footer. Requires both label and an absolute http(s) url

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

Sidebar

params.ui.sidebar_menu_compact , boolean , defaulttrue
Expands only the current branch and its neighbours
params.ui.sidebar_menu_foldable , boolean , defaulttrue
Lets the reader expand and collapse sections
params.ui.sidebar_menu_truncate , integer , default2000
Maximum rendered entries in one section. Truncates the remaining entries
params.ui.sidebar_cache_limit , integer , default500
At this page count, reuses visible neutral navigation markup for matching language/root/effective settings. The browser adds active state
params.ui.sidebar_width_min , integer , default220
Lower bound in pixels for drag-resizing on the desktop
params.ui.sidebar_width_max , integer , default480
Upper bound in pixels for drag-resizing
params.ui.sidebar_item_overflow , enum , defaultellipsis
ellipsis truncates a long title, wrap wraps it
params.ui.sidebar_icon_policy , enum , defaultall
Icon density: all everywhere, groups only on the root and nodes with children, none nowhere. An invalid value warns and falls back to all
params.ui.sidebar_expand_levels , integer , default2
Tree levels expanded by default
params.ui.sidebar_headings , boolean or integer , defaultfalse
For type: book only. Expands a heading branch below the current sidebar row. Accepts an integer from 2 to 4. The value true means 2
params.ui.sidebar_enabled , boolean , defaulttrue
The left sidebar. The value false disables it, usually per page instead of per site
params.ui.taxonomy_icons , map
Right-column group icons by taxonomy plural, for example tags: fa-solid fa-tags

For sidebar use, see Layouts and page types. The tree uses the structure of content/. See Organizing content.

Table of contents

Hugo’s configuration sets the outline levels. The theme controls only tracking behavior:

markup.tableOfContents.startLevel , integer , default2
Hugo’s own: the highest heading level collected
markup.tableOfContents.endLevel , integer , default3
Hugo’s own: the lowest heading level collected
params.ui.scroll_spy , boolean , defaultfalse
Quiet 1.x compatibility no-op; the normal shell runtime always tracks the active outline heading and this key emits no asset

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

Pager and page end

Page-end components have a fixed order: share → feedback → page information → pager → comments. Each has its own switch. Backlinks appear in the right rail beside the table of contents.

params.ui.share , list , default[]
Page-end share targets, in the order given, from x bluesky mastodon facebook linkedin reddit hackernews telegram whatsapp line pinterest weibo chatgpt claude email copy. An empty list disables the bar. Each target is a plain intent link. There is no SDK, iframe, third-party script, or share count. See Writing a blog. An unknown target warns and is discarded
params.ui.pager_types , list , default[docs, book, blog]
Types that show previous / next links. To disable them on a page, use front matter pager: false. An unknown type warns and is discarded
params.ui.annotation , boolean , defaulttrue
The “last modified” and provenance block at the end of the body; the upstream attribution line is driven by the page’s upstream_link family — see Page parameters
params.ui.backlinks , boolean , defaultfalse
Lists the pages that link to this one as a “Backlinks” group in the right rail beside the table of contents, derived at build time from ordinary links — see Navigation and menus
params.ui.compare , boolean , defaultfalse
Adds a two-pane Duo View to Docs, Book, and blog pages that have a same-origin HTML translation. A language can set it to false to opt out — see Duo view
params.ui.translation_notice , language code or false , defaultfalse
The language code of the authoritative version, so a translated page shows a line pointing back at it; a page opts out with translation_notice: false
params.ui.reading_time , boolean , defaultfalse
Shows a reading time under the page title
params.ui.book_draft_banner , boolean , defaultfalse
Adds a banner at the top of a draft Book page

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

params.offline_search , boolean , defaultfalse
Generates one local index per language and enables the command palette — see Search
params.offline_search_on_serve , boolean , defaulttrue
Also builds the index under hugo server, so preview matches production. For a very large site, set false to reduce local rebuild time
params.offline_search_index , enum , defaultcontent
Index scope, cumulative: title, heading, summary, content. An invalid value warns and uses content
params.offline_search_summary_length , integer , default70
Word cut-off for the summary scope’s excerpt
params.offline_search_max_results , integer , default10
Result cap, bounding both Lunr and the CJK substring fallback
params.ui.landing_search , boolean , defaulttrue
Whether a layout: landing page keeps a search entry point
params.ui.command_palette.commands , list , default[]
Custom commands, each with either url or a built-in action — see Command palette
params.gcs_engine_id , string
A Google Programmable Search engine ID; enabling it brings in an external service
params.search.algolia , map
Algolia DocSearch. You must supply appId, apiKey, and indexName explicitly. Otherwise, the theme warns and DocSearch remains off

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

Keyboard

params.ui.keyboard_nav , boolean , defaulttrue
Single-key navigation for the tree (WASD / arrows), headings (j/k), paging (q/e), palette, and shell switches. With false, the runtime is excluded from the bundle. See Keyboard navigation

Image zoom

params.ui.image_zoom , boolean , defaultfalse
Lets body images open at full size. Override per page with front matter image_zoom. A non-boolean warns and uses a fallback

Which images become zoom candidates is in Images.

Typography

params.ui.preset , enum , defaultpaper
Site-wide visual preset: paper, slate, or the explicit experiments ink, terminal. Available in 1.2.0; choose slate to retain the previous appearance
params.ui.preset_menu , boolean or list , defaultfalse
true offers Paper, Slate and the site default; a list explicitly opts into experiments and must include the site default. Independent of dark_mode
params.ui.typography , enum , defaulttechnical
technical uses the selected preset’s local fonts (Paper: Plex Sans; Slate: Inter); system uses the platform stack only and requests no brand font. An invalid value warns and falls back
params.ui.fonts , map
Font-family names for the ui, body, heading, code, display, meta, brand, and print roles. The theme validates names but never loads font files. End each list with a generic family
params.page_width , enum , defaultnormal
Overall shell width: normal, wide, full; overridable per page
params.reading_width , enum , defaultnormal
Book body reading width: slim, normal, wide. Does not affect the shell

Use params.ui.fonts when the faces already exist on the reader’s system or the site has declared them with @font-face. To bundle font files or change lower-level typography, use the SCSS/CSS entry points. See Brand and appearance.

Comments and feedback

params.comments.enable , boolean , defaultfalse
The site-level comment switch; a page overrides it with the front matter comments — see Comments
params.comments.type , string , defaultgiscus
Only giscus actually renders today
params.comments.giscus.repo , string
The GitHub repository hosting the discussions; required
params.comments.giscus.repoId , string
The repository ID; required
params.comments.giscus.category , string
The discussion category name; required
params.comments.giscus.categoryId , string
The discussion category ID; required
params.comments.giscus.mapping , string , defaultpathname
How pages map to discussions
params.comments.giscus.term , string
The discussion title or number when mapping is specific or number; the attribute is omitted when unset
params.comments.giscus.strict , string , default0
Strict title matching
params.comments.giscus.reactionsEnabled , string , default1
Shows reactions on the main post
params.comments.giscus.emitMetadata , string , default0
Sends discussion metadata to the parent page
params.comments.giscus.inputPosition , string , defaulttop
Whether the input box sits above or below the list
params.comments.giscus.theme , string , defaultauto
The giscus theme; auto follows the site’s light/dark state
params.comments.giscus.lightTheme , string , defaultlight
The giscus theme or custom CSS URL used in light mode
params.comments.giscus.darkTheme , string , defaultdark
The giscus theme or custom CSS URL used in dark mode
params.comments.giscus.loading , string , defaultlazy
The iframe loading strategy
params.comments.giscus.lang , string , defaultderived from the site language
The giscus interface language. If unset, Chinese sites resolve zh-CN / zh-TW / zh-HK. Other languages use the base language code. Unsupported languages fall back to en
params.comments.giscus.ariaLabel , string , defaultComments
The comment container’s aria-label. The default is English. For a multilingual site, write one per language
params.comments.giscus.errorMessage , string , defaultComments could not be loaded.
Text shown after loading fails. The default is English. For a multilingual site, write one per language
params.ui.feedback.enable , boolean , defaultfalse
The two “was this page helpful?” buttons at the page end. There is no backend. Records a structured event if gtag is present
params.ui.feedback.reasons , boolean , defaulttrue
Expands four optional reasons after “no”

If a required giscus value is missing, the theme warns and skips the comment section. See Comments for the required fields.

Repository links and page information

params.github_repo , string
The content repository URL, resolving “edit this page”, “view history”, “create child page” and “open a documentation issue” — see Repository links and page info
params.github_project_repo , string , defaultgithub_repo
The product repository URL, for “open a project issue” and the navbar GitHub entry
params.github_branch , string , defaultmain
The branch edit links point at
params.github_subdir , string
The content site’s subdirectory inside a monorepo
params.path_base_for_github_subdir , string or map
Rewrites normalized / source paths. The map accepts from and to. External mounts require an explicit mapping to a repository-relative result. See repository links.
params.github_url , — , default—
Removed. Use params.github_repo. The old migration registry no longer names the replacement. The theme now ignores an old key
params.ui.lastmod_commit , enum , defaultsubject
What follows “last modified”: subject the commit subject, hash the short hash, none nothing. An invalid value warns and falls back
params.images , string array , default—
Site-level social card. Supplies og:image if a page has no image. Used only for metadata. Never rendered as a list thumbnail
params.upstream_source , string , default—
Default data/upstreams record name for pages that declare upstream_link; page front matter can override it
params.upstream_modified , boolean , defaultfalse
Site default for whether attributed material is adapted. A page can override it. No attribution renders without upstream_link
params.default_featured , — , default—
Removed. Use params.images or a section cascade with images. As above, the theme now ignores an old key

Content runtimes

The theme detects Mermaid, KaTeX, ECharts, Infographic, Asciinema, Swagger UI, and Redoc from content. They load only on pages that use them, and only in HTML output. They have no site switch. Only the features below need a switch or external endpoint:

PlantUML in OINK 1.4.0

Local rendering is used when enabled without an endpoint. An explicit svg_image_url selects server mode. Both modes and their limits are described in PlantUML. Local-development Mermaid and local PlantUML load engines as diagrams approach the viewport. Their shared viewer and source export need no new configuration. Ordinary browser printing retains source for unrendered diagrams.

params.markmap , boolean , defaultfalse
Enables the mind map fence site-wide — see Markmap
params.mermaid , map
Configuration passed to mermaid.initialize(). Keys are lowercase. Dark mode automatically overrides theme
params.plantuml , boolean or map , defaultdisabled
true enables local rendering; false disables all PlantUML rendering
params.plantuml.enable , boolean , defaultfalse
Enables local PlantUML rendering — see PlantUML
params.plantuml.svg_image_url , string
Optional PlantUML service endpoint; absent means local browser rendering
params.plantuml.svg , boolean , defaultfalse
Server mode only: inline SVG instead of an <img>
params.drawio.enable , boolean , defaultfalse
Enables the edit button on .drawio.svg images — see Draw.io
params.drawio.drawio_server , string
Draw.io editor address. Required when enabled. If absent, the theme warns and leaves Diagrams.net off
params.highlight_classes , boolean , defaulttrue
Emits Chroma classes for highlighting; false returns to Hugo’s inline styles
params.ui.code_copy , boolean , defaulttrue
Copy button on code blocks. The value false removes it globally. A fence’s own copy= still takes precedence

Mathematics needs no parameter, only the passthrough prerequisite.

Output formats

The theme declares custom output formats but does not enable them for a site. Request the formats you need under outputs. You must explicitly enable expensive aggregate and machine-readable outputs.

hugo.yml
outputs:
  home: [HTML, markdown, LLMS, NAVJSON]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]
Format Output Description
HTML index.html The interactive form; required
markdown index.md Plain Markdown version of each page. Required for “copy Markdown” and “view source”. See AI-agent support
LLMS llms.txt A plain-text format the theme declares, usually attached to home only
LLMSFULL llms-full.txt A top-level section opt-in: the same per-page Markdown concatenated in sidebar reading order, one bundle per language
NAVJSON navigation.json A home opt-in: the sidebar/pager navigation authority serialized once per language, validated by schema/nav.v1.schema.json
print _print/index.html The whole-section print page the theme declares — see Print
BookManifest book.json Optional Book-root JSON input for EPUB/PDF packaging tools. It is not an ebook
RSS index.xml Hugo’s own format. Attach it to section to give each section a feed

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:

params.print.toc , boolean , defaulttrue
Generates a table of contents at the top of the print page. The value false omits it
params.print.section_break_wordcount , integer , default50
How many words a section needs before it starts a new print page

Languages and versions

Define languages with Hugo’s languages block. The theme reads the translation relationships that Hugo establishes:

defaultContentLanguage , string , defaulten
The primary language, served without a path prefix
languages.<lang>.label , string
The language’s endonym, shown in the language menu
languages.<lang>.locale , string
The full locale, used for <html lang> and SEO
languages.<lang>.weight , integer
Language order, and the cycle order when clicking the language icon
languages.<lang>.title , string
The site name in that language
languages.<lang>.direction , string , defaultltr
Set rtl for a right-to-left language

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

Version parameters:

params.version , string
The identifier of this site variant, which need not be a Git ref — see Versions
params.version_menu , string , defaultVersion
The version menu’s title
params.version_menu_pagelinks , boolean
On switching version, try the same path on the target site first
params.versions , list
Version entries: version, url, kind; name: '---' is a divider
params.archived_version , boolean
Shows the “this is an archived version” banner at the top
params.url_latest_version , string
The link to the current version inside that banner
params.time_format_blog , string , default2006-01-02
Blog date format, overridable per language
params.time_format_default , string , default2006-01-02
All other date formats, overridable per language

Miscellaneous

taxonomies , map
Hugo’s own: enables tag: tags / category: categories — see Taxonomies
params.taxonomy.page_header , list
Shows only listed taxonomies in a post header. If unset, shows all
services.googleAnalytics.id , string
Hugo’s own: the analytics script is injected in production builds only — see Analytics and SEO
module.hugoVersion.min , string , default0.168.0
The theme’s declared Hugo floor. An older version fails the build
module.hugoVersion.extended , boolean , defaulttrue
Hugo Extended is required (SCSS has to be compiled)

Editor completion via generated schemas

The theme ships two generated JSON Schemas under schema/: site-params.schema.json for site hugo.yaml and front-matter.schema.json for page front matter. They derive from the theme’s hugo.yaml defaults and parameter-scan registry. Configuration comments supply hover text. Theme CI regenerates the schemas and fails if they differ. Use the schema from the same release tag as your theme pin.

With the VS Code YAML extension, map the site schema in your settings. This example matches OINK v1.5.1; replace that tag with the one in your go.mod. Both common YAML configuration filenames are covered:

.vscode/settings.json
{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/pgsty/oink/v1.5.1/schema/site-params.schema.json": ["hugo.yml", "hugo.yaml"]
  }
}

To check the association, temporarily give a known boolean, such as params.offline_search, a string value. The editor should report the type mismatch. Then restore the valid value. Front matter completion depends on your Markdown tooling. Associate it with front-matter.schema.json in the same way. The front matter schema deliberately omits type constraints. Keys such as share and theme_color accept a bare-boolean opt-out as well as their normal type.

Verifying a configuration change

Run a production build after changing configuration:

hugo --printPathWarnings

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

Warning fragment Cause
invalid params.ui.typography The presets are technical and system
invalid footer_style … (allowed: fat | slim | none) A bad footer style; the warning names the page
invalid page_width … (allowed: normal | wide | full) A bad page width
invalid params.ui.section_index … (allowed: list | cards) A bad section index style
invalid params.offline_search_index The scopes are title, heading, summary, content
params.drawio.enable requires an explicit params.drawio.drawio_server Draw.io enabled with no server address
params.search.algolia requires explicit appId, apiKey, and indexName All three Algolia values are required
params.ui.image_zoom must be a boolean Written as the string "true"
theme_color … is not a #rgb or #rrggbb hex color The value is not a hex color; the default palette is kept
theme_color … reads at about N:1 against the theme's … canvas Advisory: the color ships, and the message prints the id that silences it
theme_color_dark … has no theme_color to pair with The dark half was set without a valid theme_color; it is ignored and the default palette is kept in both modes
command … must define exactly one of url or action A custom command gave both url and action, or neither
invalid params.ui.sidebar_icon_policy …; using all Only a warning, but the value is misspelled

After a configuration change, perform at least three checks. Open one page in each language. Open a page without a translation to check fallback. Check links under the production baseURL, including any deployment subpath.

The theme requires Hugo Extended 0.168.0 or newer. Validate configuration changes with the pinned baseline:

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

The theme declares the minimum in hugo.yaml and theme.toml. The site’s module.hugoVersion.min should match it.

2 - Brand and appearance

Change the site name, logo, favicon, accent color, light and dark palettes, and fonts. Use configuration and two SCSS entry points.

This page assumes the site already builds (Quick start). Configure the name, logo, page width, and footer in hugo.yml. To select an existing system or site font, use params.ui.fonts. Section accent colors also have configuration keys.

Add icons under static/. Use assets/scss/_variables_project.scss for SCSS variables and assets/scss/_styles_project.scss for custom styles or new @font-face declarations only when needed. Do not edit files inside the theme directory. An upgrade replaces them.

Visual presets

OINK 1.2.0 defaults to Paper: warm paper backgrounds, ink text, blue links, Plex Sans and framed tables. Slate keeps OINK’s existing cool blue-gray identity. Enable reader choice with:

params:
  ui:
    preset: paper
    preset_menu: true
    dark_mode: true

The theme default for preset_menu is false. Choose preset: slate to keep the previous appearance. Preset and mode are saved separately; selecting the site default (identified in its tooltip) restores the site policy. All styles use one stylesheet and local fonts.

Ink and Terminal are available as explicit opt-ins in OINK 1.2.0:

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true

Ink uses black/white surfaces, red markers, square panels and underlined prose links. Terminal uses mono controls/headings, teal links, amber accents and compact desktop navigation; its long-form prose stays sans-serif. Both support light/dark mode and reuse existing fonts. The menu shows four compact style buttons in a two-column grid, each with a colored icon and no experiment badge. preset_menu: true offers Paper, Slate and the site default; it does not opt into every experiment. Set preset: ink or preset: terminal to make an experiment the site default, even without a reader menu. See the experiment record for tested scope and remaining design work.

Custom dark brand rules using only [data-bs-theme='dark'] have lower specificity than Paper’s dark palette. Retain Slate, or scope those rules to [data-td-preset='paper'][data-bs-theme='dark']. Font configuration and section theme_color overrides keep their precedence in every preset. Print remains light on white paper.

Site name

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

hugo.yml
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. The value of languages.<lang>.title takes precedence.

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.

hugo.yml
params:
  logo: images/product-mark.svg
  wordmark: logo.svg
  • params.logo is the square mark used by the navbar, sidebar, and footer. Under assets/, it uses Hugo’s resource pipeline and can be fingerprinted. Under static/, Hugo publishes it unchanged. The path is relative to the assets/ or static/ root.
  • params.wordmark is the horizontal wordmark. If you set it, the navbar replaces “icon + site name” with it. On a narrow screen, the navbar falls back to params.logo. If you do not set it, the navbar retains “icon + site name”.

Crop the source SVG closely around the artwork so that sizes align. The SVG must have a viewBox. Its colors should inherit currentColor or provide sufficient contrast in both light and dark modes.

This site sets neither parameter. The navbar combines the theme’s assets/icons/logo.svg with the site title in the display font.

favicon

The favicon has no parameter. The theme scans the site’s static/ directory for conventional filenames. For each file it finds, it emits the corresponding <link> on every page:

File Link generated
static/favicon.ico rel="icon"
static/favicon.svg rel="icon" type="image/svg+xml"
static/favicon-32x32.png rel="icon" with sizes, emitted in ascending size order
static/apple-touch-icon.png rel="apple-touch-icon"
static/apple-touch-icon-180x180.png rel="apple-touch-icon" with sizes

The minimum sufficient set is favicon.ico, favicon.svg, and apple-touch-icon.png. A file with a size suffix must be square (NxN). Otherwise, the theme does not recognize it.

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

The scan does not cover extra head metadata, such as a Web App Manifest. Emit it through layouts/_partials/hooks/head-end.html. To change discovery rules, such as the directory or accepted filenames, override layouts/_partials/favicons.html in the site’s layouts/.

Accent colour and palette

Color has two layers. Bootstrap’s semantic colors use Sass variables at compile time. OINK’s brand layer uses CSS custom properties at run time.

First change the semantic colors. They determine the colors of buttons, links, and callouts:

assets/scss/_variables_project.scss
$primary: #315f8f;
$secondary: #b4762e;
$success: #2c7a4b;
$warning: #9a6700;
$danger: #b42318;

The theme loads this file before Bootstrap and the OINK defaults. Override Sass variables here. If you need a variable or map already defined by Bootstrap, use _variables_project_after_bs.scss instead.

The brand layer uses CSS custom properties. You must override light and dark in pairs. Otherwise, one mode retains the original color:

assets/scss/_styles_project.scss
: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;
}

Available brand properties include --td-brand-elev for overlay backgrounds and --td-brand-silk for secondary text. The accent and muted accent use --td-brand-copper and --td-brand-copper-dim. Rules use --td-brand-line-strong, and the navbar background uses --td-brand-header-bg. Shadows use --td-brand-shadow-sm / --td-brand-shadow-md. The brand gradient uses --td-brand-mark-from / --td-brand-mark-to / --td-brand-mark-gradient.

Section theme colour

The brand palette above sets the site’s overall color. The theme_color key uses one hex color to tint the shell’s accent backgrounds. This color helps readers identify their current part of the site.

hugo.yml
params:
  ui:
    theme_color: '#6d28d9'
    theme_color_dark: '#a78bfa' # optional

This key is more useful per section than for the entire site. Set it in the section root’s cascade to give the section its own color. For example, Docs can use navy, Blog violet, and Book orange. The site default retains the brand color:

content/blog/_index.md
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, adjacent rows’ gray hover backgrounds, and hover fills. It colors the outline pill and its moving rail and dot, Book chapter headings on hover, and tag and chip hover states. It also colors content card borders and share button fills on hover, text selection, focus rings, and sidebar switcher root marks.

What it deliberately does not touch: prose links, external URLs, and inline code. These use consistent reading conventions across sections. Readers should recognize code, prose, and links even on pages with many identifiers. Therefore, the accent uses its own custom property. It does not change Bootstrap’s link color.

The dark color is optional. If you omit it, the theme lightens the light color toward white until it meets AA body-text contrast on the dark canvas. This prevents an unreadable dark palette when you supply only one color. Set the dark color explicitly if the derived hue does not match your brand. The light color is required. If theme_color_dark is alone or accompanies an invalid theme_color, neither mode changes color. The theme warns and retains the default palette. It does not tint only dark mode.

To remove the section color from one page, set theme_color: false in its front matter. This removes both the light color and inherited dark color. The page uses the default palette without a warning. Any other non-hex value, including a number, true, or a named color, produces a warning.

Contrast is checked, not enforced

The theme checks your color against its own canvases. It warns if contrast is below AA body text (4.5:1). The color still appears in the output. You may choose it for a custom canvas or brand requirement. The warning includes an ignoreLogs id that can silence it. Review the contrast on the actual canvas and adjust the color when needed.

The check compares the color with the page canvas. Some interactive surfaces use it for both text and a translucent background. For example, a linked solid badge uses accent text over a 12% accent background. This combination provides less contrast than the canvas check. If a color barely passes, inspect these surfaces. Use a darker color when necessary.

Hugo merges params by key. If a section cascade sets theme_color_dark, a page that overrides only theme_color still inherits that dark value. Override both values or neither.

Light and dark mode

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

hugo.yml
params:
  ui:
    dark_mode: true

The sun/moon icon shows the current state: sun for light, moon for dark. Click Appearance in the navbar or footer to open the Light / Dark / System radio group. It supports touch and keyboard; on phones it opens a bottom sheet. The preference is saved locally and synchronized across tabs. No saved choice means follow prefers-color-scheme. The inline head script applies the resolved mode before the stylesheet loads.

To enable the dark palette without the control, set dark_mode: { show_menu: false, enable: true }. The default, dark_mode: false, 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

The typography policy is selected at build time; visual preset switching chooses its bundled faces:

hugo.yml
params:
  ui:
    typography: technical # technical | system
  • technical (the default): Paper uses IBM Plex Sans for interface, body and display text; Slate uses Inter for interface/body and Chakra Petch for display. Both use Chakra Petch for the wordmark and IBM Plex Mono for code. Chinese and emoji use platform fallbacks. Plex Sans and Inter include local Latin, Cyrillic, Greek and Vietnamese subsets. No Google Fonts request is made.
  • Experimental fonts: Ink uses Inter for UI, prose and headings; Terminal uses IBM Plex Mono for controls/headings and Plex Sans for prose. Both reuse existing code fonts. Explicit fonts.ui still supplies the main face; use fonts.body for a separate prose face.
  • system: interface, display, metadata, print, and monospace roles use the platform stack. The browser requests no brand font. Font files remain bundled with the theme, but the output does not reference them.

If the value is invalid, the theme warns and falls back to technical. Normal hugo server preview remains usable. The selected value appears in <html data-td-typography="…">. Check it in the browser.

Custom fonts

Eight CSS custom properties define the font roles. Override these properties instead of searching for component selectors:

Property Config key Where it is used
--td-ui-font-family ui Navigation, controls and interface text
--td-body-font-family body Body text and blog posts
--td-heading-font-family heading Headings in the body
--td-code-font-family code Code and terminals
--td-display-font-family display Display headings
--td-meta-font-family meta Technical labels and metadata
--td-brand-font-family brand Wordmark
--td-print-font-family print Print body text

The ui role is the main font. The body role resolves through it, and heading resolves through body. One line can therefore change the interface, prose, and headings together.

From configuration

To change only font families, use params.ui.fonts. You do not need SCSS:

hugo.yml
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 values are family names, not font files. This key never causes the theme to download or load a font. Each family must already exist on the reader’s system or have a site @font-face declaration. End every list with a generic family (sans-serif, monospace, serif). Readers without your font use this fallback.

Values accept only plain font family syntax: quoted names, bare identifiers, a leading hyphen (-apple-system), and names in any script (苹方 is a family name). They reject semicolons, braces, parentheses, url(), and angle brackets. An unknown role or unsafe value produces a warning. The theme drops only that entry and retains the rest of the map. If the site sets no values, the theme adds no style element to <head>.

The block renders after the stylesheet. At equal specificity, an authored font therefore takes precedence over the typography preset.

From a stylesheet

To bundle your own font file or change the font for one content kind, use a stylesheet. Put the .woff2 file in the site’s static/webfonts/. Declare the font in the project stylesheet. Then override the roles:

assets/scss/_styles_project.scss
@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 through normal CSS rules. To change the font for one content kind, you do not need component selectors:

assets/scss/_styles_project.scss
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:

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

A site migrating from Docsy can retain its font configuration. The old Sass variables still supply the corresponding roles from _variables_project.scss. They take precedence over preset defaults:

Legacy Sass variable Font role it feeds Note
$td-fonts-serif --td-ui-font-family / --td-body-font-family Docsy’s interface stack, assigned to $font-family-sans-serif
$font-family-sans-serif --td-ui-font-family / --td-body-font-family If a project supplies its own stack, the technical preset no longer prepends the preset’s bundled sans face
$font-family-base --td-ui-font-family / --td-body-font-family Bootstrap’s body variable, reaching the role through --bs-body-font-family
$headings-font-family --td-heading-font-family Unset, headings inherit the body role
$font-family-code --td-code-font-family Code, terminals and pre / code / kbd
$td-font-family-monospace --bs-font-monospace Assigned to $font-family-monospace
$font-family-monospace --bs-font-monospace Under the system preset, an explicit project value takes precedence over the platform monospace stack

The theme no longer reads Docsy’s three Google Fonts variables: $td-enable-google-fonts, $td-google-font-name, and $td-web-font-path. Leaving them in _variables_project.scss causes no failure and has no effect. The theme bundles IBM Plex Sans, Inter, Chakra Petch, and IBM Plex Mono. No preset requests Google Fonts. The print role --td-print-font-family follows the body role. The theme bundles no separate print font.

YAML accepts only font family names. It accepts neither remote font URLs nor arbitrary CSS. Font files and styles must be auditable local inputs. A normal build makes no network request for a font.

Page width

hugo.yml
params:
  page_width: normal # normal | wide | full

The page_width key controls the overall shell width. Override it per page or per section through a cascade. Book pages also support reading_width (slim / normal / wide), which changes the body’s reading width instead of the shell. If either key has an invalid value, the theme warns and uses a fallback.

hugo.yml
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 the footer style. This site’s documentation section uses footer_style: slim. An unrecognized value warns and falls back to fat.

Store grid data in data/footer/<language>.yaml. See Navigation and menus. If fat is configured but no data exists, the footer automatically falls back to slim. You can therefore enable it before you write the content.

The params.copyright key accepts a Markdown string or a map with authors / from_year / to_year. The value present means this year. The footer_center_info key accepts inline Markdown for the footer’s center. Set it explicitly to an empty string to hide that region.

SCSS entry points, and what not to do

The site’s SCSS overrides join the theme’s single style bundle. A production build still emits one fingerprinted stylesheet with an integrity attribute. Put the three entry files under the site’s assets/scss/:

File When to use it
_variables_project.scss Sass variables set before Bootstrap and the OINK defaults ($primary, the font variables)
_variables_project_after_bs.scss Variables or maps that depend on Bootstrap’s own definitions
_styles_project.scss Selectors and CSS custom properties written after the theme’s component styles

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 eight font roles in Fonts and the --td-brand-* properties are public. The theme preserves their names and meanings across minor versions. Component aliases such as --td-asciinema-font-family work only within their component. Undocumented variables, such as --td-shell-*, are implementation details. They 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 color. If a design variable exists, use it. 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 layouts/_partials/hooks/head-end.html. Do not write a <link> in Markdown.

Verify

hugo --printPathWarnings
  • The build prints Total in … with no ERROR;
  • 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. Check body text, tables, callouts, code blocks, and focus rings again. Verify every color change in both modes;
  • Switch language and confirm the site name changes with it.

To verify the font change, inspect a paragraph’s font-family in the browser’s developer tools. It should include your declared family. Check the rendered font as well to confirm that the local file or system fallback is being used.

3 - Home and landing pages

Build a home page from one local YAML file. Add hero, cards, capability panels, timeline, pricing, case studies, and downloads. Reuse these sections on landing pages.

Configure home page content in a data file. The sections list in data/home/<language>.yaml sets the sections and their order from top to bottom. The theme finds each section’s content by name in the same file. An ordinary page with layout: landing uses the same sections.

Hugo renders every section on the server. Prices, star counts, screenshots, avatars, and download states must exist in the repository before Hugo starts. No section fetches data in the browser.

If you migrate a Docsy blocks/* home page, you must rewrite it. OINK has no blocks/cover, blocks/section, or blocks/feature shortcodes. If you retain them, the build fails with template for shortcode "blocks/cover" not found. Use the data/home/<language>.yaml file described here, or set 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:

content/_index.md
---
title: OINK
description: A local-first, Hugo-only theme for technical documentation
---

Section data is a file per language:

home page data

  • data/
    • home/
      • en.yamlEnglish home page
      • zh.yamlChinese home page

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

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

the skeleton of data/home/en.yaml
sections:
  - hero          # uses the hero: key
  - capabilities
  - type: cards   # uses the cards section, reading the release: key
    key: release
  - cta

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

This site uses that structure for its home page. The complete file is data/home/en.yaml in the repository.

A minimal working home page

Create the data file below. Replace the text and links with your own content. Put the two hero images in static/images/hero-light.webp and static/images/hero-dark.webp. For a text-only opening, omit the entire hero.image block. Write internal links as site paths without a leading slash. The theme adds the current language prefix (docs/start/ → /docs/start/).

data/home/en.yaml
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 share one source; interactive components use static or source fallbacks.
      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. It is the only section with a large title and an illustration.

data/home/en.yaml
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/ }

If title_lines is absent, the hero uses title. If both are absent, it uses the site title. The image is a CSS background. If alt is present, its container has role="img". Otherwise, the image is hidden from assistive technology.

The setting align: center creates a text-only centered first screen. It widens and centers the text block, balances title line breaks, and moves note below the buttons. If an image is also present, the theme warns and falls back to start so the image is preserved.

The section registry

There are 22 section types. Their names use hyphens. The theme normalizes underscores in older data. Except for the hero, each type has three heading fields, eyebrow / title / desc (or text), and a class.

Type What it holds
hero The first screen: large title, buttons, a theme-following image
metrics Numeric facts, with optional count animation and source links
capabilities Alternating left-right capability descriptions with a dedicated visual panel
principles Numbered product principles
cards A general card set: features, scenarios, entry points
logo-wall Tools and partners, as a grid or a pure-CSS marquee
gallery A wall of screenshots
testimonials Quotations with attribution
contributors People, roles, avatars and links
faq Questions and answers, collapsible or flat
markdown Free Markdown content
cta The closing call to action
pricing Pricing tier cards
pricing-compare A tier-by-feature comparison matrix
command-box One copyable command
steps An ordered procedure, optionally with commands
timeline Dated milestones
code-plate Code inside a presentation panel
preview Markdown source beside its rendered result
case-study A case: metrics plus a quotation plus a source
download One or more data/download/ records
bar-chart Numeric comparison without chart JavaScript

If a type is misspelled, the build emits an unknown section type warning and skips the section.

The commonest sections, minimally

Cards and capability panels are the most common sections. The cards section sets its column count with columns:

data/home/en.yaml
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/

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

data/home/en.yaml
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 }
Minimal YAML for the other ten scenario sections

These fragments come from the theme repository’s executable regression fixture tests/site/data/landing/demo/en.yaml. You can copy the field names.

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:[email protected]' }

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 uses the same data/download/<key>.yaml record described in Releases and downloads. It introduces no second version model.

Turning any page into a landing page

Two front matter lines convert an ordinary content page to a landing page. This full-width canvas retains the navbar, command palette, and footer. It removes the sidebar and outline.

content/pricing.md
---
title: Pricing
layout: landing
landing: pricing
---

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

landing page data

  • data/
    • landing/
      • pricing/
        • en.yaml
        • zh.yaml

A non-home landing page searches for data in this order. If it finds no data, the theme warns and renders the landing shell without sections:

  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.

You can put small amounts of data in front matter. However, landing: and sections: are mutually exclusive:

content/pricing.md
---
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: cta
    data:
      title: Ready to start?
      label: Read the docs
      url: docs/
---

Writing a section entry

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

Key What it does
type The section type. If omitted, uses key as the type
key The key that supplies data. Defaults to the name in type. Use it to distinguish two instances of one section
data Inline data. No top-level key lookup is needed
id The section’s anchor ID, generated from key / type by default
enabled: false Disables the section while keeping its data
partial Uses the site’s own partial. This is a local template convention, not portable landing data

Languages and local facts

Put descriptive text in per-language files (zh.yaml / en.yaml). A shared fact record can also use per-field fallback: <field>_<exact language> → <field>_<base language> → <field>. The theme normalizes - in a language tag to _. A Chinese site resolves title_zh_cn, then title_zh, then title. The theme does not accept camelCase suffixes.

Section display text belongs to site data. It does not use the theme’s i18n strings. Only theme controls, such as marquee pause and pricing states, use translation keys. To configure the whole multilingual site, see Languages.

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

hugo.yml
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 uses separate data in data/footer/<language>.yaml, or data/footer.yaml for a single-language site. This site has one file per language. If data/home/<language>.yaml still contains a footer key, the theme warns, ignores it, and points to the new location. See Navigation and menus for authoring instructions.

Output

Output What appears
HTML The full static section content, plus landing.js loaded on demand for reveal, counting, copying and theme image switching
Print Retains content. Converts dynamic surfaces, such as the marquee, to a static grid. Removes controls
Markdown Titles, prose, lists, tables and code, with no component classes
RSS Landing sections are not emitted

If JavaScript is disabled or landing.js is unavailable, all server-rendered sections remain visible. Metrics include their configured number formatting, prefix, and suffix. Count animations finish on the same display text. The marquee’s duplicate track stays outside the accessibility tree. Its pause checkbox works without JavaScript. If the reader enables reduced motion, movement and reveal are disabled.

Verify

  1. Run hugo --printPathWarnings. This detects misspelled types, missing data keys, and simultaneous landing and sections.
  2. Open the home page and any landing page. Compare sections with their data files. Check every language.
  3. Reload with JavaScript disabled. Confirm that content remains visible without motion.
  4. Check light and dark modes. Confirm that image.light and image.dark show the correct images.
  5. For a subpath deployment, confirm that all internal links and images include the prefix.

4 - Navigation and menus

Configure the navbar menu, dropdowns, section switcher, breadcrumbs, page actions, pager, and footer links.

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.

The navbar comes from Hugo’s menus.main. Docs and Book navigation defaults to the content/ tree; sites importing an existing reading order may use data/docs_nav.json. The sidebar, pager and section index share the selected order.

The navbar menu

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

hugo.yml
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

Lower weight values appear first. Use pageRef for site pages and url for external pages. External links automatically receive target="_blank", rel="noopener noreferrer", and an external-link mark. The identifier is a stable configuration reference. The keys quick_links and sidebar_root_menu match it. Translate name per language. Do not translate the identifier.

You can also define a menu entry in page front matter. Use this when “this page is itself a top-level entry”:

content/download/_index.md
---
title: Download
menu:
  main:
    weight: 30
---

The navbar’s right-hand GitHub entry is not a menu item. It uses params.github_project_repo, with a fallback to params.github_repo. The menu area skips entries identified as github. To change the GitHub 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:

hugo.yml
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. Hover or focus it to expand the panel. Click it or press Enter to open the parent page. There is no separate expansion arrow. On touch screens, readers open the parent page, whose body lists the same links.
  • Keyboard: the down arrow expands the panel and focuses its first item. Esc closes it and returns focus to the link. Clicking outside also 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 produces a build warning and becomes a static group heading. It does not create 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:

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

Taxonomy menus

A top-level taxonomy entry (/tags/, /categories/) needs no manually written submenu. The panel shows a grid of “term + count” chips, sorted by descending count.

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

Enabling taxonomies is in Taxonomies.

Navbar controls

The navbar is 50px tall. It contains the brand logo or wordmark, a centered menu, and utility controls at the end. When enabled, it appears across layouts. On narrow screens, Home and Landing use a site-menu drawer. Shell pages with a sidebar use the sidebar’s drawer instead.

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

Viewport State
lg and above Brand, centered menu text, and search, version, language, theme, and GitHub controls. No drawer button
md to below lg Centered menu icons and utility controls at the end. No drawer button
Below md Centered menu icons remain. Search and the appropriate drawer button remain at the end. Version, language, theme, and keyboard help remain in the footer’s bottom bar

Enable individual controls through their settings. The search icon requires params.offline_search; see Search. The version menu requires params.versions; see Versions. With two or more configured languages, the language menu appears automatically; see Languages. The theme control requires params.ui.dark_mode; see Brand and appearance.

Auto-hide

hugo.yml
params:
  ui:
    navbar_autohide: true

With auto-hide enabled, the hidden navbar retains its 50px band. Move the pointer into the upper 60% of that band, or focus the navbar with the keyboard. The navbar fades in at the same position. The layout does not move, and the hidden navbar does not cover content. The wake zone excludes 64px on each side. Collapsed sidebar and outline restore controls therefore remain usable.

It is disabled automatically below 768px, on a coarse pointer, and on a touch-only device, where the navbar stays visible. Home ignores the site-wide setting unless its own front matter enables it. Hero pages retain their overlay navbar, which scrolls with the hero. A top-level navbar_autohide in page front matter or a section cascade overrides the site setting.

Turning the navbar off

hugo.yml
params:
  ui:
    navbar_enabled: false

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

content/docs/_index.md
---
title: Docs
cascade:
  navbar_enabled: false
---

If the navbar is off, the theme restores mobile subnavigation, a brand and search row at the sidebar top, and utility buttons on the outline rail. Use this switch for pages that need the whole viewport. It is not a general layout preference. This site’s documentation section keeps the navbar enabled and disables its auto-hide behavior with navbar_autohide: false, so section navigation stays visible.

The section switcher

The section switcher is the sidebar’s top row. It selects the displayed tree. The theme builds and deduplicates entries in this order: eligible top-level sections → eligible sections with sidebar_root_for: self → the current resolved root. Candidates must have a permalink. They cannot be divider groups.

hugo.yml
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:

content/docs/api-v2/_index.md
---
title: API reference v2
sidebar_root_for: self
sidebar_root_link_self: true
---

The value self makes the section index and all descendants use the new tree. The value children keeps the index in the parent tree. Only descendants use the new tree. To exclude a top-level section or a nested self-root from the global choices, set sidebar_root_menu: false in its front matter. The current resolved root is still appended if absent. Inside that section, it remains a location marker. The 1.1 implementation excludes both nested self-roots and top-level sections. The 1.0 implementation could still include a nested self-root despite false. A root with build.render: never, or a divider root, never becomes a switcher link.

With no entries, the switcher renders nothing. One entry becomes a borderless link. Two or more entries create a dropdown. The tree below still lists the section index first. The switcher selects a tree. The root link selects a document.

Breadcrumbs and page actions

An ordinary content page has breadcrumbs above its title and page actions at the row’s right end. A top-level section omits single-level breadcrumbs that only repeat its title. Action buttons retain their positions.

hugo.yml
params:
  ui:
    breadcrumb: false

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

The page action menu

The split button at the title row’s end contains page actions. Click its left half to copy the page’s Markdown. A successful copy shows a green check mark. Click the right arrow to expand the full menu. The menu groups actions for exporting content and for changing or producing content:

Action When it appears
Copy as Markdown The site enabled the markdown output format
Open in ChatGPT page_context_menu.assistant_links: true
Open in Claude The same
View Markdown source The markdown output format
View history params.github_repo can resolve the source path
Edit this page params.github_repo
Create child page params.github_repo
Open a documentation issue params.github_repo
Open a project issue params.github_project_repo
Print the whole section The section enabled the print output format
hugo.yml
params:
  ui:
    page_context_menu:
      enable: true
      assistant_links: false
      links: []

Assistant entries are off by default. When clicked, they send the full current URL, including its query and fragment, to a third party with a localized prompt. They do not upload the body. Before enabling them, confirm that URLs contain no sensitive information. Document this boundary in the privacy statement. Page front matter can restrict the site policy. It cannot enable assistant links that the site has not enabled:

Page front matter
page_context_menu:
  assistant_links: false

Confirm that ChatGPT and Claude are absent from both the title menu and the command palette on that page. See AI-agent support for the handoff behavior.

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

hugo.yml
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 and its first-level subsections, the left half becomes an RSS subscription link. “copy as Markdown” remains in the menu. Without Markdown output, a page has no left half. The arrow becomes a labeled “Actions” button.

These actions are also entries in the command palette.

The pager

Previous / next are two text links at the body end. They follow the visible sidebar tree: root page → first page → through to the last. The root has no previous link. The last page has no next link. If the site provides data/docs_nav.json, that tree also orders the pager and declared docs or book section indexes. The sidebar, pager, and index therefore show children in the same order. Undeclared sections and sites without the file use the content tree. See Layouts and page types.

hugo.yml
params:
  ui:
    pager_types: [docs, book, blog]

The pager_types list accepts only docs, book, and blog. Any other value warns and is discarded. To disable paging on a page, use front matter:

content/docs/appendix.md
---
title: Appendix
pager: false
---

The page’s <head> uses the same order. When previous or next pages exist, it emits <link rel="prev"> and <link rel="next">. Browsers and crawlers can then identify the reading sequence.

page source
<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 these four page-end components: feedback → annotation → pager → comments. Their order is fixed. Each has an independent switch. An optional Share bar appears before these components.

The right rail can list pages that link to the current page. Its “Linked from” group has a link icon and appears below the table of contents, above taxonomy clouds. It starts expanded. Below xl, it moves into the sidebar drawer with the table of contents. Readers arriving from search can identify related pages and the current page’s place in the site. Backlinks remain off until the site enables them:

hugo.yml
params:
  ui:
    backlinks: true

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

content/docs/_index.md
---
title: Docs
cascade:
  backlinks: true
---

Hugo derives the index at build time from ordinary Markdown links and ref / relref shortcodes in page source. No new syntax, migration, or JavaScript is required. The list is in HTML. Before scanning, the theme removes fenced and inline code. Multiple links to one target become one entry. It ignores self links, external links, mailto:, and same-page anchors.

The theme removes fragments when identifying target pages. Each language has its own graph. A Chinese page never appears below an English page. Entries sort by stable page path, so identical content always produces identical order. If no pages link in, the entire block is absent, including its heading and container.

The first eight entries are visible. Remaining entries use a native “Show N more” disclosure. This limits right-rail space for heavily referenced pages. No JavaScript is required. Each entry shows its source page’s description on hover.

Source scanning has a known limit. URLs in custom shortcode parameters and raw <a href> elements do not become edges. Unresolved destinations are discarded without a warning. Backlinks enhance navigation. They do not check links. Continue using a link checker to find broken links.

A non-boolean value warns and falls back to off.

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 backlinks site-wide. See this page’s right rail for an example. The most-referenced page, Configuration, lists more than forty inbound links. Most use the disclosure.

The params.ui.footer_style setting selects fat / slim / none. See Brand and appearance. The fat link grid reads data/footer/<language>.yaml. It is not a menu. The theme has no menus.footer:

data/footer/en.yaml
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/ }
  • If brand.name and brand.logo are absent, the footer uses the site’s brand name, logo, and wordmark. The fields tagline and slogan render Markdown.
  • An internal url resolves against the current language root. The setting external: true opens 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.
  • If fat is configured without data, the footer automatically falls back to slim. You can enable it before content exists.

The fat footer’s copyright row has a collapse arrow at its right end. It hides or restores the link grid above. The grid starts expanded. localStorage stores the reader’s choice under td-footer-collapsed across pages. The styles slim and none have no collapse button. This state is independent of focused reading mode.

Every rendered bottom bar ends with an icon dock in this order: version, language, theme, then keyboard help. Configured menus open upward. The version trigger shows only an icon. Its choices retain full labels. The fat footer’s collapse arrow follows the four controls. The sidebar has no duplicate dock. The setting footer_style: none removes both the footer and bar.

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

Verify

hugo --printPathWarnings

After changing navigation, check each of these:

  • Confirm that the build has no Navbar menu … supports one interactive child level warning. This warning indicates a three-level menu;
  • On desktop, click a parent to open its page. Hover to expand the panel. Press Esc to close it;
  • Narrow the window below lg. Confirm that each top-level entry has an icon. An entry without an icon is blank at this width;
  • Below md, confirm that Home and Landing navbars retain search and the drawer button on the right. Version, language, theme, and keyboard help must remain in the footer bottom bar;
  • The switcher at the top of the sidebar lists every top-level section, with the current one marked;
  • On a documentation page, use E / Q to check sidebar paging order. Confirm matching rel="prev" / rel="next" in page source;
  • With backlinks enabled, confirm that grep td-backlinks public/<a page that is linked to>/index.html finds the block. A page with no inbound links must have no backlink markup;
  • Open the page action menu. Confirm that expected actions appear and unavailable actions are absent. For example, “open a project issue” should be absent without github_project_repo.

5 - Layouts and page types

Select the page shell with type. Set sidebar width and icons, outline depth, section index style, and page width.

This page describes the page shell. Configure sidebar visibility and width, outline depth, and list or card styles for section indexes. For content locations, see Organizing content.

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:

hugo.yml
params:
  ui:
    shell_types: [docs, book, blog, swagger]
type Shell
docs The documentation shell: left sidebar (section switcher + tree) + body + right-hand outline
book The documentation shell, plus numbered targets, the reading_width measure and the draft banner
blog The documentation shell, with the sidebar expanded by default and RSS as the left half of the title row
swagger The documentation shell, with Swagger UI or Redoc rendering the body. See API reference pages
Any other type An ordinary page: navbar + single-column body + footer, with no sidebar

OINK 1.3.0 adds expo: a shared sidebar and an image album, with full page width and no right-hand outline. Its default shell_types list includes expo. If you set the explicit list above, add expo to it. See Expo albums.

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

Use a cascade to assign a type to a subtree. This lets you put documentation at any content path:

content/handbook/_index.md
---
title: Operations handbook
type: docs
cascade:
  type: docs
---

Section roots are only navigation starting points

hugo.yml
params:
  ui:
    docs_section: docs
    blog_section: blog

These two keys do not select the shell. They identify the documentation and blog tree roots. The theme uses them to resolve sidebar roots, quick links, and default icons. The content/handbook/ example still uses the documentation shell. Keeping docs_section set to docs does not affect it.

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

hugo.yml
params:
  ui:
    docs_sidebar_root: home # home | section

Only these two values are valid. Any other value warns and uses section.

Documentation at the site root

A documentation-first site can publish the docs section at the URL root. Its source can remain in content/docs/. Apply all three configuration changes below together.

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

hugo.yml
permalinks:
  page:
    docs: /:sections[1:]/:slug/
  section:
    docs: /:sections[1:]

The second keeps the physical site root index usable as a link target. It prevents that index from competing for the same output path. Apply it to each language’s site root index (content/_index.md, content/_index.zh.md):

content/_index.md
---
title: Product Docs
build: { render: link }
---

The third sets the sidebar root to the site home. The sidebar and pager then share one tree:

hugo.yml
params:
  ui:
    sidebar_root_enabled: true
    docs_sidebar_root: home

With docs_sidebar_root: home, the tree includes every top-level section of the site home. Exclude overview sections outside the reading sequence, such as blog, community, and download. Set toc_root: true in each section’s _index.md to exclude it from both the tree and paging order:

content/blog/_index.md
---
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

A page with layout: landing uses a navbar, a body assembled from sections, and a footer. It has no sidebar. To write the data, see Home and landing pages.

hugo.yml
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 uses the structure of content/. It sorts by weight and uses linkTitle labels when present. You can adjust its density and size:

hugo.yml
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 adjacent branches. The value false expands the complete tree.
  • sidebar_menu_foldable lets readers expand and collapse sections manually. Blog sections start expanded. To start one collapsed, set sidebar_expanded: false in its _index.md.
  • sidebar_expand_levels is how many levels are expanded by default.
  • sidebar_menu_truncate limits rendered entries per section. This keeps the HTML usable for a thousand-page tree.
  • sidebar_width_min / sidebar_width_max set desktop drag-resizing limits in pixels. The browser stores the adjusted width locally. Double-click the divider to restore the default.
  • sidebar_item_overflow defaults to ellipsis, which truncates long titles. For many long titles, use wrap.

At sidebar_cache_limit, pages with the same effective settings may share a neutral rendered tree. It remains visible and navigable without JavaScript. The shell runtime only adds the current path and opens its ancestors. Page or cascade overrides select the matching cached variant. A Book page with sidebar_headings enabled keeps its page-specific tree instead.

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:

content/docs/fullscreen-report.md
---
title: Full-screen report
sidebar_enabled: false
---

An explicit navigation tree, data/docs_nav.json

By default, the theme derives the sidebar tree from content/. A site may instead supply an explicit navigation manifest. The theme uses it only when all three conditions hold:

  • 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 contains a nested node tree. Each node’s page identifies a content path, and children defines its navigation children. The theme resolves links and the active branch from page identity and this tree. url and the active_path_by_url ancestor map are optional legacy hints:

data/docs_nav.json
{
  "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/"]
  }
}

Write these paths without a language prefix or the deployment subpath from baseURL. Since OINK 1.1, both prefixes are stripped before comparison, so the same /docs/start/ key works at /zh/docs/start/ and /handbook/zh/docs/start/. Rendered links retain the real language and deployment prefixes.

The manifest can group root-level manuals without moving their source files under content/docs/. Nodes apply to a sidebar root if they are that root, content descendants, or Docs/Book pages resolving to the same root. For example, with docs_section: docs and docs_sidebar_root: section, root-level pages whose type is docs can use this tree:

data/docs_nav.json
{
  "sections": [
    { "page": "/intro" },
    { "page": "/config", "children": [{ "page": "/api" }] }
  ]
}

Here content/config.md and content/api.md remain sibling files, while API appears under Config in navigation. Selecting API expands Config without URL hints. A custom page URL changes its link, not its sidebar ownership. A separate Book root or nested sidebar_root_for root selects its own branch; a root absent from the manifest uses its content tree.

This tree also sets paging order and navigation JSON. The sidebar and previous / next links therefore agree. An empty sections array warns and falls back to the content tree. A nonexistent page warns and skips that entry. Placeholder nodes with manual_link and sidebar_divider rows stay in the sidebar without becoming paging targets. In 1.1, a divider section retains its children in this explicit tree too; use the same group-only front matter as for the content-derived tree.

Use an explicit tree when an external tool generates navigation order. For example, a manual migrated from a Sphinx toctree may need to preserve chapter order. If weight in content/ maintains the order, you do not need this file.

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:

hugo.yml
params:
  ui:
    sidebar_icon_policy: groups # all | groups | none
Value Effect
all Every entry with an icon shows it (the compatibility default when unset)
groups Only the root and nodes with children show icons
none No entry icons in the sidebar

An invalid value warns and falls back to all. It does not fail the build. This site uses groups.

Expanding headings in the sidebar

Book pages keep headings out of the left page tree by default. To add an h2–h4 branch under the current sidebar row, opt in explicitly:

hugo.yml
params:
  ui:
    sidebar_headings: 3 # false | true | 2 | 3 | 4

An integer sets the deepest expanded level (2–4). The value true means 2, or h2 only. The value false disables the branch. An out-of-range value warns and disables it. This feature applies only to type: book pages. It expands only below the current sidebar row. Page front matter or a section cascade can set the same key; sidebar_headings: false turns off an inherited opt-in. The right outline remains available.

Table of contents

Hugo generates the right-hand outline from Markdown headings. Configure the collected levels in Hugo’s own settings:

hugo.yml
markup:
  tableOfContents:
    startLevel: 2
    endLevel: 4
    ordered: false

The normal shell runtime always tracks the active heading. It draws a continuous rail, highlights the current section, and marks the position. No separate switch is required. Readers can collapse the right column. The browser stores that state locally. Below xl, the right column hides, and its content moves to the sidebar drawer.

Since OINK 1.2.0, heading tracking decodes valid URL fragments. A malformed percent sequence falls back to the literal heading ID, including when following a link to a heading near the page end.

The old params.ui.scroll_spy site key and scroll_spy page key remain accepted as quiet compatibility no-ops throughout 1.x. Either boolean value produces the same outline and loads no extra runtime. The theme will remove these keys only in a future breaking release.

To hide the outline on one page, use the front matter notoc: true.

The outline includes only headings in Hugo’s table of contents. Headings from Markdown-form shortcodes ({{%/* … */%}}) appear there. Headings from ordinary shortcodes ({{</* … */>}}) usually do not. Write structural headings in Markdown.

Section index style

A section with an _index.md lists its child pages automatically, in one of two styles:

hugo.yml
params:
  ui:
    section_index: cards # list | cards
    section_index_columns: 2
  • list (the default): one title plus description paragraph per child page;
  • cards: a grid of cards reading each child’s title (or linkTitle), description and icon.

You can override this setting per section. An invalid value warns and uses a fallback:

content/docs/components/_index.md
---
title: Components
section_index: cards
section_index_columns: 3
---

Related page switches control child listings. The setting no_list: true lists no children. The setting simple_list: true emits a bulleted list without descriptions. A child with hide_summary: true excludes itself from the list. Do not write a child list by hand. It can become inconsistent with the sidebar.

Page width

hugo.yml
params:
  page_width: normal # normal | wide | full

The value normal uses the usual reading width. The value wide widens the content column. The value full fills the viewport. Override the setting per page or per section. Wide tables, large images, and API reference pages often use wide:

content/docs/api/reference.md
---
title: API reference
page_width: wide
---

Book pages also support reading_width (slim / normal / wide). This changes body reading width without changing the shell. An invalid value in either key warns and uses a fallback.

Navbar and footer switches

Configure the navbar and footer per page at the top level of front matter. Do not put these keys under ui. To configure a section, set them once in a cascade:

content/docs/_index.md
---
title: Docs
cascade:
  navbar_enabled: false
  footer_style: slim
---

The behaviour is in Navigation and menus and Brand and appearance, and the key definitions in Page parameters.

Verify

hugo --printPathWarnings
  • The build prints Total in … with no ERROR;
  • Confirm that a new type: docs page has a left sidebar. If it does not, check its cascade and shell_types;
  • Drag the sidebar divider and reload. Confirm that the width persists. Double-click to restore the default;
  • Below md the sidebar becomes a closable drawer, and below xl the outline moves into the drawer;
  • A section index has as many cards as the sidebar has child pages;
  • Confirm that a page with page_width: wide is wider than adjacent pages;
  • With documentation at the site root, hugo --printPathWarnings reports no duplicate output paths.

6 - Search

Enable local search. Control index size and result ranking, and configure useful CJK query matches.

OINK uses local search. Hugo generates one JSON index per language at build time. The reader’s browser downloads the index and runs the search locally. Search requires no crawler, account, CDN, or external search service. It is off by default. Enable it with one configuration line.

Search opens through the command palette. See Command palette for opening methods and its other contents.

Turning on local search

hugo.yml
params:
  offline_search: true

This key controls the page’s index reference, Lunr runtime, and search dialog. All three conditions must hold:

  • params.offline_search is true;
  • The page is the home page, or uses a shell layout (docs / book / blog / swagger — see Layouts and page types), or is a landing page with params.ui.landing_search on;
  • The current output is not print.

If any condition fails, the build includes no dialog, index reference, or Lunr runtime on that page. The resources are not hidden. They are not generated.

By default, hugo server also generates the index, so preview matches production. On a very large site, rebuilding the complete index can noticeably slow each preview change. To disable preview index generation, use:

hugo.yml
params:
  offline_search: true
  # skip index building during preview; only needed on very large sites
  offline_search_on_serve: false

Controlling index size

The offline_search_index key sets how much page content the index contains. It determines whether readers can find body text and the download size for their first search.

hugo.yml
params:
  offline_search: true
  offline_search_index: summary
  offline_search_summary_length: 70
  offline_search_max_results: 10
Value What is indexed When to use it
title Title, tags, categories, search_keywords A very large site where titles alone locate a page
heading The above plus every heading in the page When headings are specific enough
summary The above plus description and summary Sites with thousands of pages. This site uses it
content The above plus the full plain text The default, suitable up to a few hundred pages

Any other value warns with invalid params.offline_search_index and uses content.

The offline_search_summary_length key limits result excerpts (default 70). The offline_search_max_results key limits result count (default 10). The full definitions are in Configuration.

One index per language, budgeted at 2 MiB raw and 512 KiB gzipped.

The browser downloads the complete index before the first search. If it exceeds this budget, reduce offline_search_index from content to summary.

Adjusting ranking

A page influences its own ranking from front matter:

content/docs/reference/pgsql.md
---
title: PostgreSQL parameters
search_keywords: [postgres, postgresql, pg, database parameters, GUC]
search_boost: 1.5
---

The search_keywords key adds matching terms as a string or array. It is more useful than the boost setting. Readers searching pg or GUC can find a page titled only “PostgreSQL parameters”. Keywords have less ranking weight than the title and more than the body.

The search_boost key is a positive multiplier applied to the text match score. Its default is 1.0. A value of 1.5 does not guarantee first place. In OINK 1.4.0, it raises rank within the same term-coverage and phrase tier. Zero, negative numbers, and non-numbers warn and use 1.0.

Set a section-wide default once with a cascade:

content/docs/_index.md
---
title: Docs
cascade:
  search_boost: 1.25
---

A page’s own value overrides its inherited value. Pages under this site’s docs/ use search_keywords for Chinese phrasing, English terms, and configuration key names.

Keeping a page out of the index

content/internal/draft-plan.md
---
title: Internal plan
search_exclude: true
---

Use only search_exclude. The theme ignores the removed exclude_search and excludeSearch keys, so they do not exclude a page. The migration checker reports them. The index also excludes pages with empty bodies.

The index is a static JSON file anyone can download; it is not access control.

Do not put content that should stay private on the site, and do not use search_exclude to protect it.

Chinese, mixed queries, and identifiers

OINK 1.4.0 local search

The behavior below is included in the current release.

Search splits whitespace and Latin/CJK boundaries: PostgreSQL 备份 and PostgreSQL备份 both search for postgresql and 备份. A contiguous CJK run remains a literal substring, without a dictionary: 主从复制 does not imply 复制主从. Use spaces to separate concepts, for example 连接池 超时. search_keywords remains useful for synonyms and abbreviations.

The search preserves underscores, hyphens, dots, paths, and command options. Try shared_buffers, pg_basebackup, --baseURL, or /pg/data. These are literal identifiers, not query operators or spelling corrections. English words retain Lunr stemming. If no exact/stemmed English term exists, spelling fallback allows one edit for words of 5–7 characters and two for longer words. Shorter words and identifiers use literal substring matching. Case and Unicode width are normalized; at most 24 distinct terms participate in a query.

Terms may match different indexed fields. A title containing PostgreSQL and a description containing 备份 can satisfy both. Ranking follows these rules:

  1. If any page covers every term, show only those pages. Otherwise, show partial matches, labeled with matched/total terms, in descending coverage order.
  2. Within equal coverage, a contiguous complete phrase ranks first.
  3. Apply search_boost to field scores within those tiers. Each term uses its strongest field: title, keywords, tags/categories, headings, description, then body. A term repeated in that field ranks the page above one that mentions it once in the same field, but never above a page with a stronger field. Remaining ties use title and URL for stable ordering.

Literal substrings also match while typing. A boost cannot promote a partial match over a complete one. Results stay grouped in the navbar’s content-root order; ranking applies within those groups after the global result limit. Keyword-only matches show the description or excerpt, never the synonym list.

Each page occupies one result row, even when several sections match. The row shows the best matching section title and nearby text, and opens its actual rendered heading ID. Explicit IDs, duplicate auto-generated headings, Chinese headings, and deployment subpaths are preserved. A metadata-only hit opens the page when no section matches. heading and summary scopes can target heading matches; body-only queries require content. No index setting silently grows to full text. Matched snippets use up to 160 characters around the hit; the configured summary length still controls fallback excerpts.

The palette’s Search in control shows two adjacent choices: all sections and the current top-level section (such as Docs, Blog, or Book). It defaults to all sections on each page load and retains the choice while reopening that page’s palette. Home has no current section. Commands and page actions stay available; command mode hides the scope control. Use Tab to reach the selected scope and the arrow keys to switch. Press Tab again to return to the query; Shift+Tab from the query returns to the selected scope.

During input-method composition, result updates and Enter activation pause. They resume after committed text. Empty, loading, unavailable, result-count, and partial-match states remain readable and are announced to screen readers.

Optional: hosted search

The theme also provides two hosted search integrations. Both are off by default. Enable only one at a time. If more than one is configured, the build warns You have more than one site-search option configured.

If you enable hosted search, you accept its crawling behavior, availability, and privacy boundary. Document these in the site’s privacy statement.

Algolia DocSearch

hugo.yml
params:
  search:
    algolia:
      appId: YOUR_APP_ID
      apiKey: YOUR_SEARCH_ONLY_KEY
      indexName: YOUR_INDEX

You must supply all three values explicitly. A missing value warns and disables Algolia. OINK never falls back to another project’s public index. The theme bundles DocSearch JS and CSS locally. They do not load from a CDN. However, every query sends a request to Algolia. The integration requires real credentials and an index, so this page renders no demonstration.

Google Programmable Search

hugo.yml
params:
  gcs_engine_id: YOUR_ENGINE_ID

A landing page for the results is needed too:

content/search.md
---
title: Search results
layout: search
---

The search box submits queries to <baseURL>/search/?q=…. Google’s script renders results on that page, which requires access to cse.google.com. This integration uses an external service. This page renders no demonstration.

Verify

  1. Build, and confirm one index per language was generated:

    hugo --printPathWarnings
    ls public/offline-search-index.*

    A development build uses offline-search-index.zh.json. A production build fingerprints the filename, such as offline-search-index.zh.7ab….json. Confirm one file per language. If a file is missing, that language’s pages never reached an index.

  2. Inspect the index first when diagnosing “Chinese finds nothing”:

    python3 -c "import glob,json; f=sorted(glob.glob('public/offline-search-index.zh*.json'))[0]; \
      d=json.load(open(f)); print(f, len(d)); print(d[0])"

    The entry count should be close to the number of Chinese pages, and the keywords and boost fields should show what the front matter set.

  3. Open the site and press /. Search an English word, then a Chinese word. Confirm that results group by content root. Each group uses the first breadcrumb segment as its name.

  4. For a subpath deployment, such as https://example.com/docs/, open the browser’s network panel. Confirm that the index request includes the subpath. An index request to the domain root can return 404 while the page works. This is the most common cause of “search returns nothing”.

  • Command palette — search’s entry point, and the commands and page actions beside it
  • Keyboard navigation — the four single keys that open search and commands
  • Languages — per-language indexes and untranslated fallback
  • Configuration — full definitions of the offline_search* keys
  • Page parameters — search_keywords / search_boost / search_exclude

7 - Command palette

Use one dialog for page search, page actions, and site commands. Open the palette, use its groups, and add custom commands.

The command palette provides one modal dialog for page search and site actions. Use it to copy page Markdown, switch language or version, and open site links. The theme assembles it with local search. If params.offline_search is off, the page has no palette, index, or Lunr runtime. See Search.

Opening the palette

How to open it What opens
Click the search box in the navbar or sidebar Full search mode
⌘ / Ctrl + K Full search mode. Press again to close
/ Full search mode
The backslash key Command-only mode (equivalent to a prefilled >)
f / c The same two, provided by keyboard navigation
Typing a query beginning with > in the box Command-only mode

/, backslash, f, and c are bare single keys. They do not open the palette during typing. This applies to focus in an input, textarea, select, or contenteditable, and to input-method composition. The keys type ordinary characters instead. The modified ⌘/Ctrl + K can open the palette from a text box. It also remains inactive during input-method composition. Another open native dialog or visible ARIA dialog blocks every opening shortcut, including fixed-position dialogs. Hidden ARIA dialogs do not block them.

Inside the palette, use ↑ ↓ to select an item. Press Enter to run it. Press Esc to close the palette and return focus to the opening control.

What the palette holds

With nothing typed, the palette lists four groups in a fixed order:

Group Contents Decided by
Quick links A few entry points chosen from the navbar’s top-level menu params.ui.quick_links
Page actions Copy Markdown, view Markdown source, edit this page, view history, create a child page, open an issue, print the section, open the duo view (compare_translations) Repository configuration, whether this page has a Markdown output, and for the duo view params.ui.compare plus a same-origin translation
Preferences Switch version → switch language → switch theme Whether the site configures versions, languages and the light/dark menu
Commands Open the GitHub repository, then the site’s own commands params.github_project_repo (falling back to github_repo) and ui.command_palette.commands

The three preferences follow the navbar order: version, language, theme. Selecting a preference such as “switch language” does not navigate immediately. The palette expands its options in place. Select an option in a second action.

When you type text, page results appear first, grouped by content root. Each group uses the first breadcrumb segment as its name. Groups follow the navbar’s top-level menu order. Commands and actions appear together in the final group.

A query starting with > lists commands and actions only and searches no pages. Use it when you are unsure which menu holds a feature.

If the theme can explain why an item is unavailable, the item remains listed. Without repository configuration, “edit this page” remains with an “unavailable” note.

OINK 1.4.0 adds two adjacent Search in options for all sections or the current top-level section. It filters page results before the result limit, while commands and page actions remain available. The choice persists only while this page stays loaded. Matching sections appear beside page titles and open real heading anchors; multiple hits on one page share one row. Partial matches show their term coverage. See query semantics. Tab focuses the selected scope; arrow keys switch it. The control disappears in command and preference-choice modes.

Select quick links from Hugo’s main menu by identifier. You do not need to define them again:

hugo.yml
params:
  ui:
    quick_links: [docs, blog]

Values use the identifier of entries in menus.main. If unset, the list defaults to the documentation and blog sections (params.ui.docs_section and blog_section). To configure the menu, see Navigation and menus.

Custom commands

A site’s own commands go under params.ui.command_palette.commands, after the built-in ones, in the order written:

hugo.yml
params:
  ui:
    command_palette:
      commands:
        - id: theme_issues
          title: OINK issues
          description: Report or browse theme and documentation issues
          url: https://github.com/pgsty/oink/issues
          icon: fa-brands fa-github
          keywords: [bug, support, roadmap]

This site uses the command above. Commands have seven fields. An unsupported key or invalid record warns and discards that command:

  • id is required. It must start with a lowercase letter and contain only lowercase letters, digits, underscores, and hyphens. It must not duplicate a built-in action ID.
  • title supplies the displayed title. The description supplies the smaller line below it. The icon is one Font Awesome class pair.
  • keywords is an array of possible reader search terms. It participates in matching but is not displayed.
  • url and action are mutually exclusive and one is required. The url accepts a full http/https address, site path, or in-page anchor beginning with #. An address with a host opens in a new tab. The action references a built-in action ID.
Do not alias a built-in action with action:

Built-in actions are already in the palette, and wrapping one makes the same feature appear twice under two names.

For a multilingual site, put commands under languages.<lang>.params.ui.command_palette.commands. This lets you localize titles and keywords. The default language’s list sets the order. An entry with the same id in another language overrides only fields. A new id is appended. Command order therefore remains the same across languages.

Configuration can supply only a link or built-in action reference. It cannot inject a JavaScript callback. The palette reads a plain data manifest.

Page actions

The palette’s “page actions” and the documentation title’s split button share one implementation. They use the same action descriptors, URL generation, and executor. The button’s left half copies the page’s Markdown. Its right arrow expands all actions.

To hide the button beside the title, set page_context_menu: false. The corresponding actions stay in the palette:

hugo.yml
params:
  ui:
    page_context_menu: false

To hide the button on just one page, use page_context_menu: false in that page’s front matter instead.

The assistant_links setting is off by default. Clicking an assistant link sends the current page’s full URL, including query string and anchor, to a third party. It never uploads the body. Enable links site-wide through params.ui.page_context_menu.assistant_links. A page can only restrict that policy with this front matter:

Page front matter
page_context_menu:
  assistant_links: false

Check the title menu and palette. Neither should offer assistant links on that page. See AI-agent support for handoff behavior.

links adds external actions that appear only in the menu beside the title, not in the palette:

hugo.yml
params:
  ui:
    page_context_menu:
      links:
        - name: Ask in Discussions
          url: https://github.com/pgsty/oink/discussions/new?title={title}
          icon: fa-solid fa-comments

The three placeholders {url}, {title} and {markdown_url} are replaced with the current page’s values.

Whether “edit this page”, “view history” and “open an issue” are available depends on repository configuration. See Repository links and page info. “Copy Markdown” and “view Markdown source” require the page’s markdown output. See AI-agent support.

The dialog uses two independent data sources:

  • Page results come from the local search index. If the index was not generated or fails to download, the palette still opens and runs commands. The page section reads “the page index is unavailable; actions still work”.
  • Commands and actions come from a JSON manifest embedded in the page and need no network.

The theme does not assemble the palette for print output. If offline_search is off, there is also no palette. The keys f and c then do nothing and do not affect normal typing.

Query-aware site actions

The runtime hook for trusted site JavaScript is available since OINK 1.1. Feature-detect it: v1.0.0 and pages without local search do not provide it. Load the integration after the theme scripts, for example through layouts/_partials/hooks/body-end.html. This example assumes the site implements openSiteAssistant and owns its provider settings:

if (window.OinkCommandPalette?.registerSearchTail) {
  const unregister = window.OinkCommandPalette.registerSearchTail({
    id: 'ask-site',
    rows(context) {
      return [{ id: 'ask', title: 'Ask the site', description: context.query }];
    },
    activate(row, context) {
      context.handoff();
      return openSiteAssistant(context.query, {
        locale: context.locale,
        signal: context.signal,
      });
    },
  });
  // Call unregister() when removing this integration.
}

Rows follow native results and actions, including empty/error searches. They are absent in empty, command, choice, and loading states. Keep rows() pure and synchronous. All strings render as text. Activation receives the query that created the row, not newer input. Before opening another coordinated surface, use handoff(). The site then owns its focus and failure UI. For non-UI actions, return the operation without calling handoff.

The Shell contract defines fields, cancellation, validation, and lifecycle. YAML cannot contain callbacks. OINK adds no remote service or telemetry by default.

Verify

Run from your site’s root after a production build. In the commands below, replace public/docs/getting-started/index.html with an actual generated documentation page in your site (including a language prefix if needed).

  1. After a build, confirm the command manifest reached the page:

    hugo --printPathWarnings
    PAGE=public/docs/getting-started/index.html
    test -f "$PAGE" && grep -o 'td-action-manifest' "$PAGE"

    This confirms that HTML contains the action data. The remaining steps check the palette interface with local search enabled.

  2. Open the site. Press ⌘/Ctrl + K without typing. Confirm this order: quick links, page actions, preferences, commands.

  3. Type >. Confirm that only commands and actions remain. A new command should appear after “open the GitHub repository”.

  4. Repeat step 3 in another language. Confirm that command titles change and order remains the same.

  5. Open print preview (⌘/Ctrl + P). Confirm that it contains no palette.

8 - Keyboard navigation

Use single-key shortcuts and understand when typing disables them. Disable shortcuts for the site or individual pages.

OINK’s interactive pages have single-key shortcuts. WASD moves through the sidebar tree. J K move between headings. Q E open previous and next pages. Other shortcuts switch the theme, language, and command palette. Shortcuts are on by default. Typing disables every binding. You can disable shortcuts per site or per page.

Keyboard navigation keeps no separate state. Expansion and collapse use the sidebar’s arrow buttons. Section jumps use the right-hand outline. Language and theme switching use command palette actions. Keyboard and mouse navigation therefore use the same order.

Sidebar

Key Behaviour
W S ↑ ↓ Move focus to the previous / next visible entry
A D ← → Collapse / expand a group. On a leaf, A opens the parent and D does nothing
Enter Space G Activate the focused entry: open a page link or toggle a group button
Esc Leave the tree. Return focus to the body

You can use the four letter keys before entering the tree. With focus in the body, S starts from the current page’s sidebar entry. It moves down one entry and takes focus. The focused row is darker than the “current page” row. Readers can distinguish the two states.

If the sidebar is in a narrow-screen drawer or collapsed on desktop, the first key press opens it. If a page has no sidebar tree, these keys do nothing.

Arrow keys control the tree only after focus enters the sidebar. In the body, they retain native browser scrolling. For a right-to-left language, ← → swap with the reading direction. A D always mean “collapse / expand”.

Since OINK 1.1, groups without their own pages use disclosure buttons for keyboard navigation. From a child, A first returns to the group. Press it again to collapse the group. D opens a collapsed group. If the group is open, it moves to the first visible child. Page navigation with Q / E skips group buttons.

Reading

Key Behaviour
J K Jump to the next / previous section along the page outline
N Home page only: jump to the next top-level section (a mnemonic alias for J there)
Q E Previous / next page
H Focused reading: hide / restore the navigation shell
B Open or close the duo view when the site enables params.ui.compare and the page has a translation

J K use the same target sequence as the right-hand outline. They reach the same location as an outline click. Each jump uses a 100 ms ease, regardless of distance. You can press again before the animation finishes. If you have scrolled into a section, K first returns to its start. A second press opens the previous section. Without headings, the keys perform a short scroll.

Q E follow the sidebar tree’s visible order. They do not sort by date. Section indexes are tree entries. At a blog section boundary, the sequence is “last post of the previous section → next section’s index → first post of the next section”. Collapsed branches are excluded. Paging and focus use the same order. Without a sidebar tree, paging uses the page-end pager. Without that pager, it uses rel=prev/next in <head>.

On the home page, H hides only the navbar and footer. On a documentation page, it also hides the left and right columns and floating buttons. The tab session stores this state and restores it before the first frame. Paging with Q E preserves it without flicker. While the shell is hidden, WASD cannot focus the invisible sidebar.

Appearance, language and routing

Key Behaviour
L Y Cycle the language (the two keys are equivalent)
T Toggle light and dark
R Cycle among same-origin top-level navbar entries

These three shortcuts work on every interactive page, including pages outside the documentation shell. L does nothing on a single-language site. T does nothing if the light/dark menu is off. R does nothing if there is only one top-level entry. R cycles only same-origin top-level menu items. It excludes external links and navbar utility controls.

Key Behaviour
F or / Open the command palette in full search mode
C or the backslash key Open the command palette in command-only mode
⌘ with K or Ctrl with K Open the palette; press again to close

/ and backslash belong to search. They work when keyboard navigation is off. Keyboard navigation adds F C as aliases for the same palette. Backslash is difficult to use on some non-US layouts. You can also type a > prefix in the palette to select command-only mode. See Command palette for its contents.

Expo image viewer

The Expo viewer has its own shortcuts. Page-level single-key navigation pauses while an image is open. It resumes when the viewer closes.

Key Viewer action
W / A / S / D Move the enlarged image up / left / down / right
Q or H, E or L Previous image, next image
J or −, K or + Zoom out, zoom in
R or 0 Reset size and position
F Expand to fit the whole image in the viewing area
Escape Close the viewer

These actions apply inside the viewer. keyboard_nav: false disables page shortcuts; it does not disable the viewer controls. Expo is available in OINK 1.3.0.

Keys deliberately left free

? is reserved and unbound. The cheatsheet uses the question mark button in the footer’s bottom bar. It opens on hover, keyboard focus, or touch. It lists only keys available on the current page. A single-language site therefore has no language row.

G G, Shift with G and the digits are likewise reserved, as possible future jump sequences.

When shortcuts stand down

Each binding is a bare single key. The following conditions disable all bindings to prevent conflicts with typing or overlays:

  • Focus is in an input, textarea, select or contenteditable region;
  • An input method is composing (a hard requirement on a Chinese site);
  • A modifier is held. ⌘ with C still copies, and Shift with ↓ remains a browser action;
  • The command palette, another open native dialog, or a visible ARIA dialog owns the keyboard. This includes fixed-position ARIA dialogs; hidden ARIA dialogs do not block shortcuts.

The comment section uses an iframe. Its key events do not propagate to the page. No additional isolation is needed.

Focus order and accessibility

Since OINK 1.1, hidden sidebar and drawer content is removed from keyboard focus. Clicking the article, a table viewport or a code block no longer produces a large outline after a later keypress. Keyboard focus remains visible: the skip link highlights the article title, and scrollable tables and code keep their own focus indication and keyboard scrolling.

  • Skip link: the first Tab on a page reveals “skip to main content”. It skips the navbar and sidebar in one action.
  • Real focus: tree navigation moves actual DOM focus instead of a virtual cursor. A screen reader announces the link name and “current page” marker. Enter retains the link’s native behavior. The Tab order remains unchanged.
  • High contrast: under forced-colors, the focused row’s background is removed. A system highlight outline replaces it.
  • Reduced motion: with prefers-reduced-motion enabled, section jumps and paging scroll position instantly without an ease.
  • The key caps in the cheatsheet share their styling with the Kbd component used in the body.

Turning it off

Site-wide:

hugo.yml
params:
  ui:
    keyboard_nav: false

For one page (interaction-heavy demonstration pages often need this), or for a whole section by cascade:

content/docs/playground.md
---
title: Interactive playground
keyboard_nav: false
---

The key accepts only a boolean. Passing "false" or any other non-boolean value warns (params.ui.keyboard_nav must be a boolean) and uses the site default. See the complete definition in Configuration.

If you disable keyboard navigation, its runtime is excluded from the JavaScript bundle. /, backslash, and ⌘ with K belong to search and still work. The footer’s collapsible link-grid arrows are unaffected.

Verify

Run from your site’s root after a production build. In the commands below, replace public/docs/getting-started/index.html with an actual generated documentation page in your site (including a language prefix if needed).

  1. After a build, confirm the cheatsheet button is in the page:

    hugo --printPathWarnings
    PAGE=public/docs/getting-started/index.html
    test -f "$PAGE" && grep -c 'td-shell-keyboard__trigger' "$PAGE"

    With keyboard navigation off and local search not enabled, the button is not generated at all.

  2. Open a documentation page. Leave focus in the body and press S repeatedly. Confirm that the sidebar moves down from the current page’s entry. The body should not move.

  3. Press E several times. Confirm that paging follows the sidebar from top to bottom. Collapse a group and page again. Confirm that paging skips collapsed pages.

  4. Click in the search box and press J. The page should not scroll. The character should appear normally. Repeat with a Chinese input method.

  5. Enable “reduce motion” in the system and press J. Confirm instant positioning without animation.

  6. For the 1.1 focus fixes, follow the skip link and check the title’s focus indication. Collapse the sidebar and use Tab: its hidden links should be skipped, while the restore control remains reachable.

  • Command palette — the dialog F C open
  • Search — where the palette’s page results come from
  • Layouts and page types — which pages have a sidebar and outline, and so which keys apply
  • Kbd — writing key caps in your own documentation
  • Configuration — the full definition of ui.keyboard_nav

9 - Languages

Add a language and keep translations beside their originals. Configure menus and interface strings per language. Use matching heading anchors across languages.

OINK uses Hugo’s multilingual model without adding directory conventions. Configure a languages block. Put each translation beside its original in the same directory, with a language suffix in its filename. This page explains how to convert a single-language site to a bilingual site. It also covers two common problems: resource ownership and heading anchors.

Enabling a second language

hugo.yml
defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: OINK
    params:
      description: A Hugo theme for engineering docs
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: OINK
    params:
      description: 为工程而设计的 Hugo 文档主题
      time_format_default: 2006年1月2日
      time_format_blog: 2006年1月2日

This site uses the configuration above. The four fields have these functions:

  • label is the name shown in the language picker, written in that language’s own script: 简体中文, not Chinese.
  • locale is the standard language tag. It supplies <html lang>, hreflang alternate links, and Open Graph metadata.
  • weight decides both language order and the picker’s cycle order, lowest first.
  • params contains per-language overrides. If a key is absent here, it inherits the global value with the same name. Date formats usually need per-language values.

The default language has no path prefix, such as English at /docs/…. Each other language has a prefix, such as Chinese at /zh/docs/…. To also prefix the default language, add defaultContentLanguageInSubdir: true. This changes every site URL. For a live site, configure redirects at the same time.

File naming and resources

Put each translation beside its original, with a language suffix. Hugo uses the shared base filename to identify them as language versions of one page:

  • content/docs/
    • install.mdEnglish
    • install.zh.mdChinese
    • _index.md
    • _index.zh.md

Page bundles work the same way: index.md and index.zh.md in one directory.

In a page bundle, every language shares resources without a language suffix. A resource with a language suffix belongs only to that language.

  • content/docs/install/
    • index.mdEnglish page
    • index.zh.mdChinese page
    • topology.webpavailable to both languages
    • screenshot.zh.webpavailable to the Chinese page only

When you reference a suffixed resource in the body, write its name without the suffix: ![Screenshot](screenshot.webp). Hugo resolves it for the current language.

If a bundle contains only index.zh.md, with no English counterpart, its unsuffixed resources do not belong to the Chinese page. They belong to the default language, which has no page in that bundle. Each resource therefore needs the .zh. suffix. This site’s Chinese page bundles under docs/ use that structure.

What needs translating:

  • Translate: title, description, summaries, menu labels, tag names, image alt text, callout bodies, and reader-facing shortcode parameters.
  • Keep identical: dates, weight, aliases, and any metadata affecting routing. A mismatch makes the sidebar order differ between languages.
  • Do not translate: commands, configuration keys, filenames, URLs, version numbers, product names, shortcode names.

Per-language configuration

Three things live outside content/ and need one copy per language.

Menus are written under their own language:

hugo.yml
languages:
  zh:
    menus:
      main:
        - identifier: docs
          name: 文档
          pageRef: /docs
          weight: 20

The identifier must match across languages. Command palette quick links and search result grouping both use it. For complete menu configuration, see Navigation and menus.

Home page data uses the language files data/home/en.yaml and data/home/zh.yaml. If the current language has no file, it falls back to en.yaml. A single-language site needs only data/home.yaml. See Home and landing pages.

Interface strings: the theme ships 32 complete interface catalogs. These use the 31 locale filenames supported by Docsy, plus generic zh. Every catalog contains all 235 OINK messages in its native language. No catalog depends on generated English fallback blocks. zh and zh-cn use Simplified Chinese, while zh-tw uses Traditional Chinese. The exact locale and placeholder contract is recorded in Architecture. To change a string, create a file of the same name under the site’s own i18n/ and write only the keys you override:

i18n/en.yaml
ui_search: Search the docs

The current Hugo baseline accepts locale: zh alongside regional Chinese catalogs. The concrete locale: zh-CN shown above also works; no older-Hugo locale workaround is required.

Untranslated fallback and the language picker

The language picker icon is a link. Click it to select the next language by weight. After the last language, it returns to the first. Hover or focus it to expand a menu of all languages. On a touch screen, a tap switches language directly without expanding the menu. A bilingual site switches between its two languages with one click.

The menu always lists every configured language, whether or not the current page is translated:

  • If the target language has a translation, open that page;
  • If the target language has no translation, open its home page.

The home page fallback avoids a 404. However, readers may not notice that they moved to the home page. A bilingual site should enforce “every page has a counterpart” as a constraint. Do not depend on the fallback.

This fallback belongs to the language picker. Since OINK 1.2.0, this fallback is separate from SEO: the hreflang links list only the current page and actual translations. Each blog pagination page has its own canonical URL, and later pages omit language alternates. See canonical URLs and language alternates.

A missing translation is never filled in with the original

If no Chinese page exists, the Chinese site has no version of that page. Its sidebar, search index, and paging order omit the page.

Search indexes also apply per language. A search from a Chinese page matches only Chinese content. Queries support separated CJK terms, mixed languages and technical identifiers. See Search.

Heading anchors must align

Hugo derives IDs from heading text. A Chinese heading therefore produces a Chinese ID. The links /docs/install/#prerequisites and /zh/docs/install/#前置条件 point to corresponding sections with different anchors. Cross-language deep links, contents links, and in-page jumps then break.

Set the original heading’s ID explicitly on the translated heading:

install.zh.md
## 前置条件 {#prerequisites}

Follow these two rules:

  1. Read the ID from the HTML the English page renders. Do not derive it from heading text. Inline code, badges, or shortcodes can produce different IDs.
  2. Corresponding pages must have the same heading count, order, and IDs. If a translation needs an extra section, give it an independent stable ID. It must not conflict with an English ID.

This documentation site’s translation checker compares source structure and rendered heading IDs. The following command runs in the oink.pgsty.com checkout; the script is not part of a normal consumer site:

node scripts/check-doc-translations.mjs --public public

Before adapting it to your CI, change its fixed content scopes and EN/ZH file conventions. It locates source files relative to the script itself; --public only chooses the rendered output directory. For a manual check, compare the heading IDs in a representative translated pair’s generated HTML.

Add explicit English {#id} anchors when you create a page. This requires less work than adding them later.

Duo view

Set params.ui.compare: true to let readers open a page alongside one of its translations:

hugo.yaml
params:
  ui:
    compare: true

On Docs, Book, and blog pages that have a published HTML translation on the same origin, OINK adds an Open duo view button beside the page actions. Readers can also launch Duo View from the command palette or press B when keyboard navigation is on (try it on this page); pressing B again returns to the page. The current page stays on the reading-start side while the other pane loads the selected translation; if a page has more than two languages, readers can switch the target language from the toolbar menu. Below 900px, the view switches to a single-pane layout with a language toggle bar.

The Sync Scroll switch keeps both panes aligned at the same section by matching the heading IDs described above, so consistent {#id} anchors give the best result. If some headings have no counterpart, or the two pages share none, the reader estimates the position between matching headings or from overall reading progress. An orange ! beside the switch then says which; hover over it, focus it, or tap it to read the note. If heading IDs are duplicated or appear in a different order across languages, Sync Scroll turns off automatically while leaving both panes open for independent reading.

Enabling the duo view does not generate extra pages at build time. The reader fetches the two existing HTML pages inside same-origin frames only when a reader opens it. Pages without a translation, drafts, language-home fallbacks, and translations hosted on another domain are excluded automatically. To disable the duo view for a specific language—both as a host page and as a comparison target—set compare: false under languages.<lang>.params.ui.

Before enabling it in production, check two details:

  • Custom analytics snippets in hooks/head-end.html run inside each pane frame unless guarded with window.OinkComparePane; see Analytics.
  • Your Content Security Policy must allow frame-src 'self', and the server must not send X-Frame-Options: DENY or frame-ancestors 'none'; see Content Security Policy.

Right-to-left languages

Declare the writing direction under the language:

hugo.yml
languages:
  ar:
    label: العربية
    locale: ar
    direction: rtl
    weight: 3

The <html dir> value follows this setting. The theme also loads Bootstrap’s RTL stylesheet. Theme CSS uses logical properties throughout, such as margin-inline-start instead of margin-left. This automatically mirrors the layout. Use logical properties in site CSS too. Otherwise, RTL can position elements incorrectly.

Verify

  1. Build from your site’s root. Confirm that output exists for both languages. These paths assume English at / and Chinese at /zh/. Adjust them for your language settings. Check indexes only if local search is enabled:

    hugo --printPathWarnings
    ls public/index.html public/zh/index.html
    ls public/offline-search-index.*
  2. Check hreflang and canonical URLs against SEO behavior. hreflang lists only actual translations; each blog pagination page has its own canonical URL, and pages after page 1 omit language alternates.

    # Replace with an actual generated page in your site.
    PAGE=public/zh/docs/getting-started/index.html
    test -f "$PAGE" && grep -o '<link[^>]*hreflang[^>]*>' "$PAGE"
  3. On a translated page, expand the language picker and select the other language. Confirm that the same document opens. Repeat on an untranslated page. Confirm that the target language’s home page opens instead of a 404.

  4. Search the same concept once in each language and confirm both return results.

  5. Compare heading IDs in a translated page pair. Before adding this check to CI, adapt the documentation-site script as described above. Do not run it unchanged against a different content tree.

10 - Versions

Configure the version switcher and archive banner, and select a deployment layout for multiple documentation versions.

If a product supports several versions, its documentation usually needs versions too. The theme provides a navbar version switcher and an archive banner on older sites. The site selects the deployment layout. The theme does not build across versions. Each version requires a separate Hugo build.

The version switcher

List the menu versions under params.versions. If the list is nonempty, a branch-icon menu appears in the navbar’s utility area. An icon-only upward menu in the footer’s bottom bar shows the same content.

hugo.yml
params:
  # which version this site is
  version: v2.1
  # the accessible menu name; bottom-bar trigger remains icon-only
  version_menu: v2.1
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v2.0
      url: https://v2-0.docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com

A menu entry shows its version value by default. If name is given, it shows that name. An entry is selected if its version equals params.version or its url equals the site’s baseURL.

An entry without a url is a gray item that cannot be clicked. You can use it as a group heading. name: '---' creates a divider. A url on a divider causes a warning. name accepts inline Markdown:

hugo.yml
params:
  versions:
    - name: '**Current**'
    - version: v2.1
      url: https://docs.example.com
    - name: '---'
    - name: '**Older versions**'
    - version: v1.9
      url: https://v1-9.docs.example.com

The same list supplies “switch version” in the command palette. The menu and palette therefore agree.

version_menu_pagelinks: true appends the current page’s path to the target version’s URL. Version switching thus keeps the reader on the same document.

The target version may not have that page. Documentation structure can change between versions. If an older version lacks a new page, switching to it produces a 404. This site leaves the option off.

A single entry can override the global setting:

hugo.yml
params:
  version_menu_pagelinks: true
  versions:
    - version: v2.1
      url: https://docs.example.com
    - version: v1.9
      url: https://v1-9.docs.example.com
      pagelinks: false # this version's structure differs; go to its home page
Judge by how stable the structure is, not by how far apart the versions are

Enable it where the structure is stable. Disable it where the structure changed. An extra step to a version’s home page is preferable to a 404.

The archive banner

If a version is no longer maintained, identify its site as a snapshot:

hugo.yml
params:
  archived_version: true
  version: v1.9
  url_latest_version: https://docs.example.com

With archived_version: true, a banner appears at the top of every documentation and book page body. It states that the current version is no longer actively maintained and links to url_latest_version. The text uses the site’s language. You do not need to write it. The banner shows the version value as its version number.

The banner appears on documentation and book pages only, not on blog or landing pages.

params.version versus params.versions

These two parameters have different purposes:

  • params.versions is a cross-site list. It identifies the versions available in the menu and their locations. It describes other sites.
  • params.version identifies this build’s version. It selects the menu entry and supplies the archive banner’s version number. It is also the fallback when data/download/*.yaml omits version. See Releases and downloads.

It does not have to be a Git ref. If you need a resolvable release tag, declare a separate parameter. For example, an install command can use that parameter. Do not reuse params.version for this purpose. The full definitions of both keys are in Configuration.

Deployment layouts for multiple versions

Layout baseURL Characteristics
Subdomain https://v1-9.docs.example.com/ Versions are fully independent. Each needs its own DNS and certificate
Subpath https://docs.example.com/v1.9/ One domain concentrates SEO weight. The host must route paths to different artifacts

Each version is an independent build. Check out its content from the branch or tag. Build with that version’s hugo.yml. Publish to the matching address. The current version’s site lists every version. Older sites list them and add the archive banner.

On a subpath deployment, baseURL must include the path segment

Otherwise the search index, page actions and asset links all point at the domain root. The page looks correct, but search returns nothing. This is the most common subpath failure. For deployment details, see Deploy.

Verify

Run from your site’s root after a production build. In the commands below, replace public/docs/getting-started/index.html with an actual generated documentation page in your site (including a language prefix if needed).

  1. After a build, confirm the version menu reached the page:

    hugo --printPathWarnings
    PAGE=public/docs/getting-started/index.html
    test -f "$PAGE" && grep -c 'nav-version-menu' "$PAGE"

    With params.versions empty or unset, the menu is not generated at all.

  2. Check whether the current version is marked selected:

    grep -o 'td-nav-hover-menu__option td-is-active[^>]*' "$PAGE"

    If there is no result, params.version does not match an entry’s version field, or baseURL does not match that entry’s url. Check the trailing slash.

  3. Visit each menu link. With version_menu_pagelinks enabled, switch from a document that an older version lacks. Confirm that the destination is acceptable.

  4. On an archived site, open a documentation page. Confirm that the banner appears at the top of the body. It should use the site’s language and link to the current version.

  5. Press ⌘/Ctrl + K to open the command palette. Confirm that “switch version” lists the same versions.

11 - Taxonomies

Use tags and categories to index pages across directories, with automatic term pages, term cards, rail clouds, and navbar panels.

A directory tree gives a page one path. A taxonomy gives it a second. A PostgreSQL backup document can be in an “Operations” directory and on a “backup” tag page. To enable this, set Hugo’s taxonomies: configuration. The theme generates term pages, term cards, the rail cloud, and the navbar panel. You do not need to write a template.

This page has a category. The “Categories: Customization” line appears under the title. Counted chips appear under the outline in the right column. Neither requires configuration on the page itself.

Enabling a taxonomy

Hugo owns taxonomies. The theme adds no switch of its own. Write taxonomies: at the top level of hugo.yml, with the singular name as the key and the plural as the value:

hugo.yml
taxonomies:
  tag: tags
  category: categories

This site uses that configuration. Apply these three rules:

  • taxonomies: defines the complete list. It does not add to an existing list. To retain tags / categories, include them with custom taxonomies.
  • The plural is also the URL segment: /tags/, /categories/.
  • To disable all taxonomies, use disableKinds: [taxonomy, term].

To add a taxonomy for product modules, use:

hugo.yml
taxonomies:
  tag: tags
  category: categories
  module: modules

The six keys tag, tags, category, categories, module, and modules have localized titles in all theme language files. Other taxonomies use the humanized plural (products → Products). To set a custom name, write title / linkTitle in content/<plural>/_index.md and _index.zh.md. The theme gives that name priority:

content/modules/_index.md
---
title: Product modules
linkTitle: Modules
---

Tagging a page

The front matter key is the plural (the value column of taxonomies), and the value is always a list, even with one entry:

content/docs/ha/patroni.md
---
title: Patroni high availability
description: Managing PostgreSQL failover with Patroni.
categories: [High availability]
tags: [PostgreSQL, Patroni, failover]
---

If a whole section shares one category, set it in the section index’s cascade. Do not repeat it on every page:

content/docs/customize/_index.md
---
title: Customization
linkTitle: Customization
icon: fa-solid fa-sliders
cascade:
  categories: [Customization]
---

All six documentation sections on this site use this configuration. A page’s own categories: replaces the cascade. It does not merge with it. To add a category beside the section’s category, write both.

The term line on a page

Documentation and blog pages show assigned terms under the title and summary. Each term links to its term page. This page shows “Categories: Customization”. Its container is .taxonomy-terms-article. Each taxonomy adds a .taxo-<plural> class. Use those two selectors to style it.

By default, it lists every taxonomy except the reserved plurals authors and series. These have their own surfaces: a byline and a series strip. Chips would repeat that information. To include either taxonomy, name it in page_header.

To show only some, in a fixed order:

hugo.yml
params:
  taxonomy:
    page_header: [categories]

The key is listed in Configuration. It cannot hide the line. See Limits.

Two taxonomies the theme knows by name

authors and series are ordinary Hugo taxonomies. Declare them in the usual way. The theme adds no parameter for either. It adds a rendering for each taxonomy. The declaration alone enables that rendering:

hugo.yml
taxonomies:
  category: categories
  tag: tags
  author: authors
  series: series
Plural What the declaration turns on The term page becomes
authors Portraits and linked names in the article head, names on list rows, one <dc:creator> per author in the feed The author’s profile. The display name uses linkTitle, or title if absent. description supplies the short introduction. The body supplies the long introduction. The featured-image resolver selects the avatar
series A strip above the article body naming the series, this article’s position, the next part, and the whole list behind a <details> The series introduction, listing its members in reading order rather than newest-first

For complete details and required front matter, see Writing a blog. Keep these two rules in mind:

  • There is deliberately no data/authors file. The term page owns the profile, which prevents conflicting sources.
  • A series term page does not use reverse-date order. Members with a series_weight come first in ascending order. Other members follow by ascending date. A term page cannot give Hugo an order. The theme resolves the order once. Both surfaces use that result.

Term and taxonomy pages

Each taxonomy generates two levels of page:

Page URL Contents
Taxonomy list /categories/ The heading shows the taxonomy’s glyph, localized name (“Categories”), and term count. Cards show each term, most-used first. Each card shows its glyph (an author’s portrait), name, and page count
Term page /categories/customization/ The heading shows the term’s title and page count. If breadcrumbs are disabled, a “Categories” kicker links to the list. Member pages follow, newest first, in blog-list style

A Chinese term’s URL uses Chinese characters. The address bar shows 定制站点, and the HTML is percent-encoded. Hugo does not transliterate. For ASCII URLs, use English terms. Give each a display name with title in content/categories/<term>/_index.zh.md — Hugo’s term page content file mechanism.

A term page has no fixed location in the content tree. If all members belong to one top-level section, it uses that section’s sidebar tree and root link. A reader who clicks a documentation tag thus remains in the documentation navigation. If members belong to different sections, the page uses the site-level tree.

Term cards appear only on the taxonomy list page. Term pages show the rail cloud instead.

The rail cloud

Documentation, blog and term pages carry one group per taxonomy in the right column (under the outline), with counted, collapsible chips. The group is automatic by default. It appears where a taxonomy is defined and the current scope has terms. Set toc_taxonomies: false in a page’s front matter to hide its rail clouds and taxonomy switcher, or set params.ui.toc_taxonomies: false in hugo.yml site-wide. These display settings leave the page’s tags, byline, series and taxonomy membership intact.

Taxonomy list pages and term pages put a taxonomy switcher at the top of the column. Each declared taxonomy has one row with its glyph, name, and term count. The row links to its list page. The current taxonomy is highlighted. A list page counts its clouds site-wide. It excludes its own taxonomy because the adjacent cards show those terms. A site with a single taxonomy shows no switcher.

The count is per top-level section, not site-wide. The theme first looks for a section named after the page’s type. A type: docs page uses the /docs/ tree. Otherwise, it uses the page’s top-level section. “Tags: release 4” on a blog page means four posts in the blog. It does not mean four on the site.

Icons are configured by plural name:

hugo.yml
params:
  ui:
    taxonomy_icons:
      categories: fa-solid fa-folder
      tags: fa-solid fa-tags
      modules: fa-solid fa-cubes

Those two are the defaults for categories and tags. Other taxonomies default to fa-solid fa-shapes. An icon is one Font Awesome class pair, written as everywhere else on the site.

The taxonomy panel in the navbar

A main-menu entry that points to a taxonomy list page becomes a term-chip panel automatically. It shows counts and sorts by descending usage. No manual dropdown is required:

hugo.yml
languages:
  en:
    menus:
      main:
        - identifier: tags
          name: Tags
          pageRef: /tags
          weight: 60

Both pageRef: /tags and the older url: /tags/ are recognized. The theme resolves a URL-form menu entry to a site page before checking its kind. Migration from an older configuration needs no rewrite. Other ways to write menus are in Navigation and menus.

Bilingual terms

Hugo counts and links taxonomies per language. /categories/ and /zh/categories/ are separate trees. A Chinese page belongs only to the Chinese tree. Terms are written once per language in each front matter:

content/docs/ha/patroni.md
categories: [High availability]
tags: [PostgreSQL, Patroni, failover]
content/docs/ha/patroni.zh.md
categories: [高可用]
tags: [PostgreSQL, Patroni, 故障切换]

Apply these two language rules:

  • The same word in both languages (such as release) still creates two term pages: /categories/release/ and /zh/categories/release/. Each counts only pages in its own language. Do not use English terms on Chinese pages only for consistency. The rail chips would then show English.
  • For the six built-in keys, a taxonomy’s display name follows the language. A term’s name does not. It is the exact front-matter string. The theme does not translate it. If you write 高可用 on an English page, its chip shows 高可用.

The rest of running a multilingual site is in Languages.

Switching by content type

To retain the rail clouds on documentation but hide them on a blog section, set the display switch on that section index and its descendants:

content/blog/_index.md front matter
toc_taxonomies: false
cascade:
  toc_taxonomies: false

Taxonomy membership is a separate choice: it comes from the terms assigned to pages. For example, this documentation site uses:

Content categories tags Effect
content/docs/** Section-level cascade (the six sections) none The term line has one row, Categories
content/blog/** Per post (release, oink) Per post (Oink, Release) Two rows in the term line, two chip groups in the rail

To exclude a whole section from the taxonomy, delete categories from the section index’s cascade. No other change is needed. To exclude one page, write categories: [] in its front matter. The empty list overrides the cascade.

Verify

Choose a page in your own site with taxonomy terms assigned, then check:

  • Its title area shows the terms selected by params.taxonomy.page_header.
  • With toc_taxonomies enabled, the right rail shows term groups and counts. Disabling it hides the clouds but retains the page’s terms.
  • Your taxonomy index (for example /categories/) lists terms whose links open their member pages.

Run from your site’s root, replacing both sample paths with your own page and taxonomy output paths, including language prefixes:

hugo --printPathWarnings
PAGE=public/docs/getting-started/index.html
TAXONOMY_DIR=public/categories
ls "$TAXONOMY_DIR"
test -f "$PAGE" && grep -o 'taxonomy-term' "$PAGE"

Limits

  • page_header: [] does not hide the term line. An empty list is treated as unset and lists every taxonomy. To remove the line, stop tagging those pages. Alternatively, hide .taxonomy-terms-article in assets/scss/_styles_project.scss.
  • toc_taxonomies: false hides the rail clouds. There is no configuration key to limit the number of terms in a visible cloud.
  • Term pages have no cross-language pairing. Language switching does not guarantee the same term in the other language.

12 - Repository links and page info

Connect “edit this page”, “open an issue”, and “view history” to your repository. Show last-modified information, contributors, and feedback at the page end.

Repository entries in the action menu use a few github_* parameters. This menu appears at the breadcrumb row’s right end. The “last modified” line at the page end uses Git history. Both features assume that content is in a GitHub-style repository.

Every repository-related entry in the action menu derives from these keys:

hugo.yml
params:
  github_repo: https://github.com/pgsty/oink.pgsty.com # the documentation source repository
  github_project_repo: https://github.com/pgsty/oink # the product repository (optional)
  github_branch: main # defaults to main
  github_subdir: '' # path from the repository root to the Hugo site root

This site uses the configuration above. It gives this page’s action menu the following targets:

Menu entry Target
Edit this page …/edit/main/content/docs/customize/repository.md
View history …/commits/main/content/docs/customize/repository.md
Create child page …/new/main/content/docs/customize?filename=change-me.md&value=<template>
Open a documentation issue …/issues/new?title=Repository links and page info
Open a project issue https://github.com/pgsty/oink/issues/new

Follow these conventions:

  • github_repo must identify the content repository. If you use the theme repository, reader changes go to the wrong place. Without this key, the four documentation actions above are unavailable. The project issue depends only on github_project_repo.
  • github_project_repo identifies a second repository for product bugs instead of documentation errors. Do not configure it if readers cannot distinguish the two.
  • github_branch defaults to main. It identifies the content branch. Do not use the deployment branch or a branch generated by Pages.
  • github_subdir is the path inside the repository. If site source is at the repository root, leave it empty. If source is in a subdirectory, set its path, such as website for a repository with code and website/.

Set these values at site level, per language, in a section cascade, or in page front matter. These scopes support content from several repositories. See the complete definitions in Configuration.

Content from another repository

When content comes from an upstream repository, override the repository parameters with a section cascade. path_base_for_github_subdir removes or replaces the physical source path prefix before appending it to github_subdir. For source files copied inside the site, the path is relative to the site root:

content/reference/_index.md
---
title: Upstream reference
cascade:
  github_repo: https://github.com/OWNER/UPSTREAM
  github_project_repo: https://github.com/OWNER/UPSTREAM
  github_subdir: docs
  path_base_for_github_subdir: content/reference
---

content/reference/api/client.md therefore maps to the upstream’s docs/api/client.md.

Since OINK 1.2.0, the theme normalizes Windows and Unix source paths to / before matching and preserves filename case. For a physical mount outside the site, match its absolute source path rather than Hugo’s virtual mount target:

External source at /srv/upstream/docs/
path_base_for_github_subdir: '^/srv/upstream/docs/'

With github_subdir: docs, /srv/upstream/docs/api/client.md therefore maps to docs/api/client.md. After mapping and cleanup, the source must be a nonempty repository-relative path. Unmapped external files, absolute or drive-qualified results, . and parent-directory escapes suppress Edit, History, and Create child actions. Documentation and project issue links retain their own repository settings. Use / separators in Windows mapping expressions too.

The path_base_for_github_subdir value is a regular expression. If the source filename differs from the local filename, use a from / to mapping. For example, map each section’s _index.md to the upstream README.md:

content/reference/_index.md
path_base_for_github_subdir:
  from: content/reference/(.*?)/_index.md
  to: $1/README.md

OINK keeps .md and .zh.md together in one directory. Both languages share a path prefix, so the expression needs no language directory. After changing it, click “edit this page” from a leaf page, section index, and each language. If the expression removes too much, the URL can appear correct but return a 404.

Turning individual entries off

Every menu entry carries a stable action ID:

Menu entry Action ID
Copy as Markdown copy_markdown
View Markdown source view_markdown
Open in ChatGPT / Claude open_chatgpt / open_claude
View history view_history
Edit this page edit_page
Create child page create_child_page
Open a documentation issue create_issue
Open a project issue create_project_issue
Print the whole section print_section

If a host does not support an action, hide it with CSS:

assets/scss/_styles_project.scss
.td-page-actions__item[data-td-action='create_child_page'] {
  display: none;
}

The command palette uses the same IDs. Hiding a menu entry does not remove it from the palette. If the entire site cannot use a target, omit its configuration key. CSS can hide a link but cannot correct its target.

The whole menu can also be turned off per page with page_context_menu: false in front matter — see Page parameters.

The “create child page” action prefills content from the theme’s assets/stubs/new-page-template.md. To supply a site template, put your own file at assets/stubs/new-page-template.md.

Last modified

The last-modified line uses Git data, not file mtime. Enable Hugo’s Git support:

hugo.yml
enableGitInfo: true
params:
  github_repo: https://github.com/pgsty/oink.pgsty.com
  ui:
    lastmod_commit: subject # subject | hash | none

The page end then reads “Last modified August 17, 2026 · (a1b2c3d)”, with the commit part linking to …/commit/<hash>. The three values of lastmod_commit:

Value What is shown
subject (default) The commit subject plus the abbreviated hash
hash commit a1b2c3d
none The date only, with no commit link

Any other value warns (invalid params.ui.lastmod_commit) and uses subject.

Check these two conditions:

  • CI needs sufficient Git history. A shallow clone (fetch-depth: 1) cannot reach a file’s last commit. Its date can be missing or incorrect. Set fetch-depth: 0 in GitHub Actions.
  • An uncommitted file has no Git time. The line is absent when you preview a new local page.

If Git history is unavailable, do not use build time for “last modified”. Build time does not identify when content changed.

This line belongs to the annotation component, which is on by default and sits after feedback and before the pager. Turn it off for a page with annotation: false.

The annotation block also renders two kinds of provenance. Both use page front matter and require no template override:

  • Upstream attribution: for a derived page, set upstream_link and four required keys: upstream_name, upstream_copyright, upstream_license, and upstream_notice. The page end names the work, copyright holder, and license, with a link to the full notice. Add upstream_modified: true to append a “modified downstream” line.
  • Translation notice: params.ui.translation_notice contains the authoritative version’s language code. A translated page shows a link to that original. For a page authored natively in the current language, set translation_notice: false.

Both families are defined in full in Page parameters.

If you need customization, use one of three override points. Each covers one layer:

Partial to override What it changes
layouts/_partials/annotation-items.html Add, remove or reorder the lines, keeping the theme’s markup, icons, print rules and accessible label
layouts/_partials/page-meta-lastmod.html Replace the markup those lines render as
layouts/_partials/page-annotation.html Replace the block’s outer container

What the page end is made of

The five components have a fixed order. All reading layouts share one implementation:

Order Component Theme default Page switch
1 Share Off (params.ui.share is empty) share: false, or the page’s own list
2 Feedback Off feedback: true / false
3 Annotation On annotation: false
4 Pager On for docs / book / blog pager: false
5 Comments On when fully configured comments: false

This order follows reader actions after the last paragraph: share the page, give feedback, check provenance, open the next page, and join the discussion. Share appears first because it is the only outward action. Readers who intend to share have already made that choice before the feedback question. To configure the bar, see Writing a blog.

Configuring comments is in Comments.

The feedback widget

The widget asks “Did this page solve your problem?” with yes / no buttons. Choosing no expands four optional reasons. The widget is off by default:

hugo.yml
params:
  ui:
    feedback:
      enable: true
      reasons: true # whether to ask for a reason after "no"

To enable it for the documentation section only, use a cascade (a blog usually keeps just comments):

content/docs/_index.md
---
title: Docs
cascade:
  feedback: true
---

The widget has these boundaries:

  • A click completes it. There is no text box, no submit button and no sign-in.
  • The browser stores the choice in localStorage per page and language. Returning readers can see and change it.
  • If the site has Google Analytics (gtag), the widget sends a docs_feedback event with result (solved / not_solved), page_path, and language. Choosing a reason sends a second event with reason and refinement: true. This distinguishes it from the first count. Without analytics the widget still works and sends no reports. It requires no backend.
  • If the page enables comments, an anchor link labeled “add details in the comments” appears below the result. Feedback and giscus have independent data flows. The theme never writes comments for readers.

This page sets feedback: true in its front matter (the docs section defaults it off), so the real widget is visible at the page end.

The contributor wall

The contributors shortcode renders a GitHub avatar grid from a file under the site’s data/ directory. It never contacts GitHub at build time:

data/contributors.yaml
items:
  - github: Vonng
    name: Ruohang Feng
    role: Theme author
  - github: pgsty
    name: Pigsty
    role: Project organization
  - github: gohugoio
    role: Static site generator
    avatar: /icons/logo.svg
Source
{{</* contributors */>}}

The github field is required and must be a valid GitHub username. A duplicate produces a warning and skips the repeated entry. The name defaults to github. The role is optional. The url defaults to https://github.com/<github>. The avatar is optional. Without it, the shortcode renders an initial placeholder and makes no network request. If present, its value must be http(s):// or a site-root-relative path.

For several lists, use separate data files. Select each file with data=:

Source
{{</* contributors data="maintainers" */>}}

In Markdown and RSS output, the grid becomes a list of - [@handle](url) — role.

This site has no data/contributors.yaml

The example therefore does not render on this page. Add a data file to data/ to render it.

Verify

Run from your site’s root. Replace the example PAGE with an actual generated page whose source belongs to the configured repository:

hugo --printPathWarnings
PAGE=public/docs/getting-started/index.html
test -f "$PAGE" && grep -o '<a[^>]*data-td-action[^>]*>' "$PAGE"
  • Open the page’s title action menu. Confirm that “Edit this page” points to github.com/<your repository>/edit/<branch>/<source path>. Every source path segment must match. In command output, inspect the anchor with data-td-action="edit_page".
  • Repeat from a section index (_index.md): it also needs the correct source path.
  • Check the “last modified” line at the page end. It is expected to be absent on a new local page before commit.
  • Page parameters — annotation / feedback / pager / page_context_menu and the other page switches
  • Configuration — full definitions of github_*, ui.lastmod_commit and ui.feedback
  • Comments — the last block at the page end
  • Analytics and SEO — where feedback events are sent
  • AI-agent support — the Markdown and assistant entries in the action menu

13 - Print

Print one page with the browser’s Cmd/Ctrl+P. Use the print output format to combine a section into one continuous document.

Printing one page needs no configuration. The sidebar, outline, navbar, and buttons have d-print-none. The browser’s Cmd/Ctrl+P therefore prints only the body. The theme has no per-page “print this page” button.

To combine a whole section or book and its pages into one continuous document, configure print output. This document includes a table of contents. This page explains how to enable the output, understand its structure, and exclude pages.

Enabling whole-section print

The theme declares the custom print output format but does not enable it for the site. Add it to section in the site’s own hugo.yml:

hugo.yml
outputs:
  home: [HTML, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

This site uses the configuration above. Each key under outputs is a wholesale replacement, not a merge. When you add print, retain every format that the page kind already used (HTML, RSS, markdown). If you omit a format, you lose that output.

After you enable print output, each section has a print URL. The _print segment comes first after the language prefix:

Page Print view
/docs/customize/ /_print/docs/customize/
/docs/ /_print/docs/
/blog/release/ /_print/blog/release/

“Print the whole section” appears in the page action menu. You can also find it in the command palette by action ID print_section. It prints the current section. On /docs/customize/print/, it prints the entire Customization section, not only this page.

The structure of a print view

Each print view contains these items from top to bottom:

  1. A notice bar: “This is the multi-page printable view of this section. Click here to print. Return to the regular view of this page.” It carries d-print-none and appears on screen only, never on paper.
  2. The section title and summary.
  3. A whole-section table of contents, numbered 1:, 2:, 2.1: by level, linking to in-document anchors.
  4. Each page appears in sequence. Its title uses “number - title”, such as “1 - Configuration”. Its description introduces the body. The body is rendered unchanged.

Pages follow sidebar order (weight), with subsections expanded recursively. Each page after the first starts a new sheet. The first page starts a new sheet only if the section index body exceeds 50 words. A one-sentence index therefore does not occupy a separate sheet. You can adjust the threshold:

hugo.yml
params:
  print:
    section_break_wordcount: 120

To remove the table of contents:

hugo.yml
params:
  print:
    toc: false

It can also be turned off for one section, in the section index’s front matter:

content/docs/components/_index.md
---
title: Components
print:
  toc: false
---

Excluding pages

To exclude link-only pages, redirect notes, or pages with one large screenshot, set no_print:

content/docs/about/showcase.md
---
title: Showcase
no_print: true
---

This setting affects only the whole-section print view. It does not affect the page’s HTML or browser Cmd/Ctrl+P. The view automatically excludes sidebar dividers (sidebar_divider). If a divider is a section, its child documents remain in the print sequence.

How components look in print

Print is one of four outputs. Each component has a defined print form. Whole-section print and single-page browser print use the same rule: interactive content becomes static, and collapsible content expands.

Component Print shape
Callouts Static blocks. All collapsible kinds (- / + / DETAILS) expand. Borders become gray, and backgrounds are removed
Tabs The tab bar disappears and every panel is expanded in turn, each with its own heading
Code Blocks Copy and fold controls removed, max height and scrolling dropped, long lines wrapped
Tables Complete static tables with a keyboard-scrollable browser preview; print-media CSS expands them for paper and headers repeat across pages
Images Retains image and caption. Removes zoom attributes and limits width to the reading measure
Gallery The grid becomes a vertical stack
FileTree A static panel with all directories expanded. The split retains its build-time width
Fields A complete definition list, identical in both forms
Math Statically rendered KaTeX / MathML
Mermaid Dedicated Print retains source without an engine; ordinary HTML printing shows rendered diagrams or source when not rendered
Markmap The print view is HTML; its runtime renders normally
PlantUML Dedicated Print keeps source without a runtime; printing ordinary HTML retains rendered images or source when not rendered
ECharts · Infographic Shows the fence source block. Draws no chart
Asciinema · OpenAPI A labeled static link to the recording or specification. None of the three runtimes loads
Cards / steps / badges / keys Static, with content unchanged

Print excludes the page shell: sidebar, outline, navbar, page action menu, feedback widget, heading anchor links, and inline copy buttons.

When printing an ordinary HTML page with browser-rendered diagrams, confirm that they have finished drawing before triggering print.

Browser print styles

The theme ships a layer of @media print rules shared by single-page and whole-section printing:

  • A4 paper with 18mm 16mm 20mm margins; 10.5pt body text; the light palette forced.
  • Fonts use the --td-print-font-family typography token. See Brand and appearance.
  • Headings do not separate from their body (break-after: avoid-page), and paragraphs and list items keep three-line orphan and widow control.
  • Tables, images, blockquotes, callouts, cards, and tabs avoid page breaks where possible. Code blocks may break across pages. Long lines wrap instead of truncating.
  • Links are underlined and dark blue. Print does not append URL text. To append it, add this rule:
assets/scss/_styles_project.scss
@media print {
  .td-content a[href^='http']::after {
    content: ' (' attr(href) ')';
    font-size: 0.85em;
    word-break: break-all;
  }
}
  • A closed <details> always expands. Printed callouts and file tree directories therefore show all content.

Custom print styling goes in a @media print block in assets/scss/_styles_project.scss and needs no template change.

Replacing the print templates

To add a running header or change numbering, override the partial with the smallest relevant scope. Print partials are under layouts/_partials/print/:

Partial Responsibility
print/render.html The whole-section skeleton: notice bar, contents, recursive content
print/page-heading.html The title and standfirst at the top of the document
print/content.html How one page appears inside the whole-section view
print/toc-li.html One row of the table of contents

The last three also support overrides per content type. Create print/page-heading-blog.html or print/content-book.html. The theme gives the type-suffixed partial precedence.

Whole-book printing (type: book) uses a separate path. Chapter numbers, figure numbers, and cross-references remain continuous across the book. See Books.

Verify

In your site’s root, build and check the print output for a section where you enabled print. Replace the example path with that section’s actual output, including its language prefix if applicable:

hugo --printPathWarnings
PRINT_PAGE=public/_print/docs/index.html
test -f "$PRINT_PAGE"

Then open that section’s Print the whole section action on the running site:

  • Confirm the print view contains the section’s pages, excluding no_print: true pages.
  • Press Cmd/Ctrl+P. Confirm that print preview shows no notice bar, navbar, or buttons.
  • Use a page with tabs and a collapsed callout. Confirm that every panel expands in preview. See Tabs for authoring syntax.
  • Print a PDF and check pagination. If necessary, adjust section_break_wordcount.

14 - AI-agent support

Publish a .md version of each page and an llms.txt site index. Let readers open the current page in ChatGPT or Claude.

An HTML page includes a sidebar, scripts, and styles. A model must remove that shell before it reads the content. OINK can emit the same content as plain Markdown. It provides one .md per page, one llms.txt index at the site root, and a “copy as Markdown” button on the page. All three use build-time artifacts. They require no runtime service or content negotiation.

The site must declare all three under outputs. The theme does not enable them. Two other optional artifacts help an agent read more than one page: a full-text bundle per section and a navigation tree per language.

A .md per page

markdown is one of Hugo’s built-in output formats. Add it to the page kinds that need it:

hugo.yml
outputs:
  home: [HTML, markdown, LLMS]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

This site uses the configuration above. Each key under outputs is a wholesale replacement, not a merge. When you add markdown, include every format that the page kind already used (RSS, print). If you omit a format, you lose that output.

The URL rule is the page URL plus index.md:

Page Markdown
/docs/customize/agents/ /docs/customize/agents/index.md
/docs/customize/ (section index) /docs/customize/index.md
/ (site home) /index.md

Each HTML page’s <head> includes a discovery link. A crawler therefore does not need to guess the URL:

<link rel="alternate" type="text/markdown" href="https://oink.pgsty.com/docs/customize/agents/index.md">

What the .md contains

This output contains the source you wrote. It is not a conversion of rendered HTML. Front matter becomes an H1 and a blockquoted summary. The body follows verbatim. The theme expands shortcodes in place into their Markdown forms.

the start of /docs/customize/print/index.md
# Print

> A single page goes to the browser's Cmd/Ctrl+P; a whole section becomes one continuous document through the print output format.

---

LLMS index: [llms.txt](/llms.txt)

---

Printing one page needs no configuration: the shell (sidebar, outline, navbar,
buttons) all carries `d-print-none`, so the browser's `Cmd/Ctrl+P` yields a
clean body.

Native Markdown components retain their source in the .md. These include callouts, tables, field lists, image attribute lines, code fences, and data fences. The model reads the source you wrote. A section index also appends a Section pages: list of child links after the body.

Each shortcode has a defined Markdown fallback. A badge becomes emphasized text or a link. A key becomes Ctrl + K. Tabs become consecutive **Label** subsections. Fields become an item list. Each component page describes its fallback in the Output section.

If the site has not enabled LLMS output, the LLMS index: line does not appear. The theme never links to a file that it did not publish.

llms.txt

llms.txt is a plain-text manifest at the site root. It identifies site content and its machine-readable versions. To generate it, add the LLMS output format to the home page:

hugo.yml
outputs:
  home: [HTML, markdown, LLMS]

A multilingual site gets one per language: /llms.txt and /zh/llms.txt. The content is a generated site index:

/llms.txt (excerpt)
# OINK

> A local-first, Hugo-only theme for technical documentation

## Site index

- [Home page](https://oink.pgsty.com/index.md)
- [Docs](https://oink.pgsty.com/docs/index.md): OINK is a local-first Hugo documentation framework…
- [Blog](https://oink.pgsty.com/blog/index.md): Docsy articles, OINK engineering stories, and OINK release notes

## Documentation index

- [Introduction](https://oink.pgsty.com/docs/about/index.md): A local-first Hugo documentation framework evolved from Docsy…
  - [Highlights](https://oink.pgsty.com/docs/about/features/index.md): What separates OINK from an ordinary Hugo theme…
  - [Cases](https://oink.pgsty.com/docs/about/showcase/index.md): Find the production case closest to your site…
- [Get started](https://oink.pgsty.com/docs/start/index.md): Start from the official OINK Starter, establish a local baseline, and customize it in layers.
…

## Site locales

- [English](https://oink.pgsty.com/index.md)
- [简体中文](https://oink.pgsty.com/zh/index.md)

The Site index contains this language’s home page and the site’s main menu (menus.main). It links to an entry’s Markdown version when available. It includes description when present. The Documentation index contains the docs subsections and the level of pages beneath them. It indents entries by level and includes each page’s description. The Site locales section lists every configured language. The index omits off-site menu entries, such as GitHub or an issue tracker. These entries belong to navigation, not site content.

To improve llms.txt, change the main menu and each section index’s description. You do not need to change the template.

Full-text bundle

One .md per page suits an agent that knows which page it needs. To read the whole manual, an agent would otherwise crawl each page. The LLMSFULL output provides one llms-full.txt per top-level section. It contains every included page in reading order. OINK 0.8.0 introduced this output. It remains off until a section enables it.

The switch is the section index’s own front matter rather than the site configuration:

content/docs/_index.md
---
title: Docs
outputs: [HTML, print, RSS, markdown, LLMSFULL]
---

Front matter outputs replaces the page’s site-level list. Include the formats that the section already used. If you omit markdown or print, the section index loses those outputs. Front matter applies per language. For a bilingual site, repeat the line in _index.zh.md to generate the Chinese bundle.

The output contains one file per language at the section root: /docs/llms-full.txt and /zh/docs/llms-full.txt. It uses the sidebar and pager reading order. For a docs or book section with an explicit data/docs_nav.json tree, it uses that tree. Otherwise, it uses the weighted content tree. Pages excluded from the sidebar with toc_hide are also excluded from the bundle.

Each page is introduced by a separator carrying its source URL, and the body that follows is byte-identical to that page’s own .md:

/docs/llms-full.txt (excerpt)
================
Source: https://oink.pgsty.com/docs/customize/print/index.md
================

# Print

> A single page goes to the browser's Cmd/Ctrl+P; a whole section becomes one continuous document through the print output format.
…

================
Source: https://oink.pgsty.com/docs/customize/agents/index.md
================

# AI-agent support
…

Source: points at the page’s Markdown output, falling back to its HTML URL where the page publishes no .md.

Only a top-level section can publish a bundle. If you list LLMSFULL further down the tree, the theme warns (“LLMSFULL output requires a top-level section”) and emits nothing.

If at least one section has a bundle, llms.txt includes a ## Full-text bundles list for that language. An agent can discover bundles in the file it already fetches.

This site’s docs section enables the bundle. https://oink.pgsty.com/docs/llms-full.txt contains the entire English documentation in one file.

Navigation JSON

The sidebar is the site’s table of contents. An agent can read it to plan which pages to fetch. The NAVJSON output publishes the tree as navigation.json, with one file per language at the language root. OINK 0.8.0 introduced this output. It is off by default. Enable it for the home page:

hugo.yml
outputs:
  home: [HTML, markdown, LLMS, NAVJSON]

This produces /navigation.json and /zh/navigation.json. It uses the same tree as the sidebar and pager. For a docs or book section with an explicit data/docs_nav.json tree, it uses that tree. Elsewhere, it uses the weighted content tree:

/navigation.json (excerpt)
{
  "baseURL": "https://oink.pgsty.com/",
  "language": "en",
  "root": {
    "children": [
      {
        "children": [
          {
            "description": "Give every page a .md twin, the site root an llms.txt…",
            "id": "/docs/customize/agents/",
            "kind": "page",
            "markdown": "https://oink.pgsty.com/docs/customize/agents/index.md",
            "title": "AI-agent support",
            "url": "https://oink.pgsty.com/docs/customize/agents/"
          }
        ],
        "id": "/docs/",
        "kind": "section",
        "title": "Docs",
        "url": "https://oink.pgsty.com/docs/"
      }
    ],
    "id": "/",
    "kind": "home",
    "title": "OINK",
    "url": "https://oink.pgsty.com/"
  },
  "schemaVersion": 1
}
Key What it holds
id The page path without its language prefix. The same page has the same id in every language
url The absolute URL of this language’s HTML page
markdown The absolute URL of the page’s .md, present only where the page publishes one
title The navigation title (linkTitle, falling back to title)
description The page’s description, where it has one
kind home, section, or page for real pages. external or link for placeholders
children The ordered children, where the node has any

Array order is part of the contract. The theme never serializes weight because it has already applied the order. If a consumer sorts the array again, its order can differ from the source sidebar.

Placeholder rows retain the sidebar’s structure. A manual_link entry becomes an external node with the authored URL. A manual_link_relref entry becomes a link node with the resolved reference. Neither has page identity, an id, or a markdown URL. The tree omits sidebar dividers and pages that Hugo never renders. Their children remain in place.

The contract has a version. The value of schemaVersion is 1. The theme repository ships its JSON Schema as schema/nav.v1.schema.json. If you consume the file, validate it against this schema. If the site publishes it, llms.txt lists navigation.json for its language in the site index.

This site has it enabled: https://oink.pgsty.com/navigation.json is a live instance of the tree.

Agent actions on the page

Four entries in the action menu at the right of the breadcrumb row relate to agents:

Entry What it does When it appears
Copy as Markdown Copies this page’s .md to the clipboard. Prefetches on hover to avoid a perceptible wait after a click This page has a markdown output
View Markdown source Opens the .md in a new tab This page has a markdown output
Open in ChatGPT Opens ChatGPT with a prompt assistant_links: true
Open in Claude Opens Claude with a prompt assistant_links: true

The first two actions appear when markdown output is enabled. “Copy” is the left half of the split button, with the clipboard icon. After a successful copy, it briefly shows a check mark.

The last two are off by default and must be enabled explicitly:

hugo.yml
params:
  ui:
    page_context_menu:
      enable: true
      assistant_links: true

When the reader clicks an enabled assistant action, the runtime creates a prompt from the address bar’s full URL. It includes the real domain, query string, and anchor. In English, the prompt is “Please read the contents of so that I can ask you about it.” The action then opens the other site. Only the URL leaves this site. The body is never uploaded. The other site fetches the content itself. Do not put confidential information in a URL. Document this third-party boundary in the site’s privacy statement.

A page may restrict the site policy but cannot reverse it. The front matter page_context_menu: { assistant_links: false } disables assistant links for that page. If the site has not enabled them, setting true has no effect. To disable the entire menu for a page, use page_context_menu: false. See Page parameters.

Both assistant actions are also searchable in the command palette, from the same action manifest — see Command palette.

Opting a page out of .md output

Replace outputs in the page’s front matter. This replaces the complete list. Include only the formats that you want to keep:

content/legal/terms.md
---
title: Terms of service
outputs: [HTML]
---

To keep RSS and remove only Markdown, list the remaining formats:

content/blog/_index.md
---
title: Blog
outputs: [HTML, RSS, print]
---

Customizing the output

The theme renders Markdown output with layouts/all.md and generates llms.txt with layouts/index.llms.txt. The two optional formats use layouts/list.llmsfull.txt and layouts/index.navjson.json. To replace a complete template, put a file with the same name under the site’s layouts/. First consider an override with a smaller scope:

  • Per content type: a typed path such as layouts/blog/single.md or layouts/docs/list.md affects only that content kind. The theme specializes its print templates this way (layouts/blog/single.print.html). Check the template lookup order for your combination.
  • Per shortcode: a site shortcode can use an output-format-specific template. This can provide a more machine-readable form in Markdown output.
  • Per page: for a few high-value pages, writing the output by hand requires less work than changing a template.

The content of llms.txt follows the site’s structure. Before changing the template, check the main menu and each description for the problem. If you replace index.navjson.json, you also take responsibility for the nav.v1 contract. Your output must still satisfy schema/nav.v1.schema.json for consumers that validate it.

Verify

Run from your site’s root, with Markdown and LLMS outputs enabled. Replace PAGE_MD with an actual page’s generated Markdown file. The section paths below assume a docs section; adjust them and any language prefix to your site.

hugo --printPathWarnings
PAGE_MD=public/docs/getting-started/index.md
ls "$PAGE_MD" public/llms.txt
# Only if you enabled LLMSFULL on docs and NAVJSON on home:
ls public/docs/llms-full.txt public/navigation.json

Against a running local preview or production, use your own base URL and page path. BASE_URL includes the deployment subpath and, when testing a translated site, the language prefix:

BASE_URL=https://your-site.example/
PAGE_PATH=docs/getting-started/index.md
curl -fsS "${BASE_URL}${PAGE_PATH}" | head -5
curl -fsSI "${BASE_URL}llms.txt" | head -3
# Only if you enabled LLMSFULL on docs:
curl -fsS "${BASE_URL}docs/llms-full.txt" | head -3

Then check four things:

  • Confirm that the selected page’s HTML <head> has rel="alternate" type="text/markdown";
  • Click the copy button beside the title and paste the result. Confirm that it is Markdown instead of HTML;
  • llms.txt contains no off-site links;
  • If you enabled these outputs, confirm that each page in llms-full.txt starts with a Source: line. The same page must have the same id in each language’s navigation.json.

Limits

  • The theme produces four types of machine-readable build-time files: a .md per page, llms.txt, optional llms-full.txt per top-level section, and optional navigation.json per language. Hugo still owns sitemap.xml.
  • A bundle belongs to a top-level section. There is no whole-site llms-full.txt. To read everything, an agent reads the section bundles listed in llms.txt.
  • LLMS, LLMSFULL, and NAVJSON are non-alternative formats. They have no <head> alternate links or page actions. Agents discover them through conventional paths and their entries in llms.txt.
  • Server-side content negotiation (one URL returning Markdown for Accept: text/markdown) is outside the theme’s scope and belongs to the hosting layer.
  • Markdown output uses the source. Content generated only by browser JavaScript, such as a runtime-drawn chart, appears in the .md as fence source. It does not appear as a diagram.