This is the multi-page printable view of this section. .
Customization
- 1: Configuration
- 2: Brand and appearance
- 3: Home and landing pages
- 4: Navigation and menus
- 5: Layouts and page types
- 6: Search
- 7: Command palette
- 8: Keyboard navigation
- 9: Languages
- 10: Versions
- 11: Taxonomies
- 12: Repository links and page info
- 13: Print
- 14: AI-agent support
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 | |
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
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):
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.enabledorparams.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: solarizedreportsinvalid params.ui.typography "solarized" (allowed: technical | system) -- using "technical". The site still builds. The settingsfooter_style: thin,page_width: huge, andsection_index: gridbehave the same way. One typo therefore changes one setting instead of producing HTTP 500 on every URL underhugo server. -
One warning keeps the value instead of dropping it. If
theme_coloris 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 theignoreLogsid 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 belowmodule.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:
- The page’s own front matter;
cascadein an ancestor section’s_index.md(nearer wins);- 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.
A cascade sets a whole subtree at once:
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:
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,- Site name, shown in the navbar,
<title>and the footer baseURL,- The production domain. Include the path segment for a subpath deployment
copyright,- Fallback for the copyright line, rendered as HTML when
params.copyrightis unset enableGitInfo, ,- Required before “last modified” and commit information exist
enableRobotsTXT, ,- Generates
robots.txt enableEmoji, ,- Allows
:smile:shortcodes
Theme parameters:
params.logo, ,- Brand mark. May use an
assets/resource or astatic/path. See Brand and appearance params.wordmark,- Horizontal wordmark. If set, replaces “icon + site name” in the navbar
params.description,- Site description, the meta fallback when a page has no
description params.copyright,- A string renders as Markdown. A map accepts
authors,from_year, andto_year. The valuepresentmeans this year params.footer_center_info, ,- Inline Markdown in the footer center. An empty string hides it
params.author,- The RSS author. A map accepts
nameandemail params.ui.theme_color,#rgb/#rrggbbhex color for shell accent backgrounds. Does not affect prose links or inline code. See Brand and appearanceparams.ui.theme_color_dark, ,- The dark accent color. If omitted, the theme derives it from
theme_coloruntil 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, ,- Which types use the reading shell with a sidebar — see Layouts and page types
params.ui.docs_section, ,- The documentation section’s root directory name, used for navigation resolution only
params.ui.blog_section, ,- The blog section’s root directory name
params.ui.docs_sidebar_root, ,- With
section, a docs sidebar starts at the documentation section. Withhome, it starts at the site home. An invalid value warns and uses a fallback params.ui.quick_links, ,- Top-level menu identifiers listed by the command palette on an empty query — see Command palette
params.ui.sidebar_root_enabled, ,- Allows a subsection to become its own sidebar tree with
sidebar_root_for: self params.ui.sidebar_root_menu, ,- Shows the section switcher above the sidebar. With only one entry, it becomes a plain link
params.ui.section_index, ,- Child list style on a section index:
listorcards, overridable per section params.ui.section_index_columns, ,- 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, ,- Pattern for image resources in the bundle
params.ui.expo.mode, ,wall,cards, orseamlessparams.ui.expo.size, ,- 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, ,- Controls the article’s featured image on single pages and section indexes. The mode
nonerenders nothing. The modebannershows a 16:9 figure above the title. The modewashshows the image behind the article header at a tenth of its opacity. The modeherouses a full-bleed shell background and moves the opening down. It uses the same image as the page card andog:image, so they cannot differ. Without an image, every mode renders nothing params.ui.blog_index, ,listshows horizontal entries,cardsshows regular image cards,tableshows compact rows, andgalleryshows linked covers. All sort by date, newest first. Only a standalonetablewithblog_index_toggle: falseshows the complete section without paginationparams.ui.blog_index_columns, ,- 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, ,- Posts per page for
list,cards,gallery, and all four views when switching is enabled. A standalonetableignores it params.ui.blog_index_toggle, ,- 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, ,- Gallery arrangement:
wallhas 6px gaps,seamlesshas no gaps, andcardsuses masonry with visible captions. This is independent of the outerblog_indexlayout params.ui.blog_gallery.size, ,- Target gallery tile size, 160–360 CSS pixels. Does not set the number of posts per page
params.ui.toc_style, ,- Right-rail presentation. The mode
fixedpins a panel to the viewport. The modeflowuses a wider panel in content flow. It starts with the article and pins only on scroll params.ui.toc_taxonomies, ,- 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.
Navbar and footer
params.ui.navbar_enabled, ,- Whether the site navbar renders; overridable with a top-level
navbar_enabledon a page — see Navigation and menus params.ui.navbar_autohide, ,- 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, ,fatis a multi-column grid plus the copyright line,slimis the copyright line only,nonerenders nothing. An invalid value warns and falls backparams.ui.dark_mode, ,trueenables the dark palette and theme control. For only the control, usedark_mode: { show_menu: true }params.ui.breadcrumb, ,- Breadcrumbs;
falseturns them off. A top-level section already omits a one-level breadcrumb params.ui.page_context_menu.enable, ,- The page action split button beside the title
params.ui.page_context_menu.assistant_links, ,- Shows “Open in ChatGPT / Claude”; clicking sends the full URL off-site
params.ui.page_context_menu.links, ,- Custom external actions;
urlsupports the{url},{title}and{markdown_url}placeholders params.ui.github_stars,- Star count on the navbar GitHub mark. Uses a local constant and makes no request
params.ui.alt_site,- Sibling-site link in a single-language footer. Requires both
labeland an absolutehttp(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, ,- Expands only the current branch and its neighbours
params.ui.sidebar_menu_foldable, ,- Lets the reader expand and collapse sections
params.ui.sidebar_menu_truncate, ,- Maximum rendered entries in one section. Truncates the remaining entries
params.ui.sidebar_cache_limit, ,- 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, ,- Lower bound in pixels for drag-resizing on the desktop
params.ui.sidebar_width_max, ,- Upper bound in pixels for drag-resizing
params.ui.sidebar_item_overflow, ,ellipsistruncates a long title,wrapwraps itparams.ui.sidebar_icon_policy, ,- Icon density:
alleverywhere,groupsonly on the root and nodes with children,nonenowhere. An invalid value warns and falls back toall params.ui.sidebar_expand_levels, ,- Tree levels expanded by default
params.ui.sidebar_headings, ,- For
type: bookonly. Expands a heading branch below the current sidebar row. Accepts an integer from 2 to 4. The valuetruemeans 2 params.ui.sidebar_enabled, ,- The left sidebar. The value
falsedisables it, usually per page instead of per site params.ui.taxonomy_icons,- 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, ,- Hugo’s own: the highest heading level collected
markup.tableOfContents.endLevel, ,- Hugo’s own: the lowest heading level collected
params.ui.scroll_spy, ,- 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, ,- Page-end share targets, in the order given, from
xblueskymastodonfacebooklinkedinreddithackernewstelegramwhatsapplinepinterestweibochatgptclaudeemailcopy. 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, ,- 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, ,- The “last modified” and provenance block at the end of the body; the upstream attribution line is driven by the page’s
upstream_linkfamily — see Page parameters params.ui.backlinks, ,- 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, ,- 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
falseto opt out — see Duo view params.ui.translation_notice, ,- 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, ,- Shows a reading time under the page title
params.ui.book_draft_banner, ,- Adds a banner at the top of a draft Book page
Search and command palette
Local search is off by default, and the command palette appears only once it is
on (the navbar magnifier, Cmd/Ctrl with K, /, \).
params.offline_search, ,- Generates one local index per language and enables the command palette — see Search
params.offline_search_on_serve, ,- Also builds the index under
hugo server, so preview matches production. For a very large site, setfalseto reduce local rebuild time params.offline_search_index, ,- Index scope, cumulative:
title,heading,summary,content. An invalid value warns and usescontent params.offline_search_summary_length, ,- Word cut-off for the
summaryscope’s excerpt params.offline_search_max_results, ,- Result cap, bounding both Lunr and the CJK substring fallback
params.ui.landing_search, ,- Whether a
layout: landingpage keeps a search entry point params.ui.command_palette.commands, ,- Custom commands, each with either
urlor a built-inaction— see Command palette params.gcs_engine_id,- A Google Programmable Search engine ID; enabling it brings in an external service
params.search.algolia,- Algolia DocSearch. You must supply
appId,apiKey, andindexNameexplicitly. 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, ,- 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, ,- 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, ,- Site-wide visual preset:
paper,slate, or the explicit experimentsink,terminal. Available in 1.2.0; chooseslateto retain the previous appearance params.ui.preset_menu, ,trueoffers Paper, Slate and the site default; a list explicitly opts into experiments and must include the site default. Independent ofdark_modeparams.ui.typography, ,technicaluses the selected preset’s local fonts (Paper: Plex Sans; Slate: Inter);systemuses the platform stack only and requests no brand font. An invalid value warns and falls backparams.ui.fonts,- Font-family names for the
ui,body,heading,code,display,meta,brand, andprintroles. The theme validates names but never loads font files. End each list with a generic family params.page_width, ,- Overall shell width:
normal,wide,full; overridable per page params.reading_width, ,- 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, ,- The site-level comment switch; a page overrides it with the front matter
comments— see Comments params.comments.type, ,- Only
giscusactually renders today params.comments.giscus.repo,- The GitHub repository hosting the discussions; required
params.comments.giscus.repoId,- The repository ID; required
params.comments.giscus.category,- The discussion category name; required
params.comments.giscus.categoryId,- The discussion category ID; required
params.comments.giscus.mapping, ,- How pages map to discussions
params.comments.giscus.term,- The discussion title or number when
mappingisspecificornumber; the attribute is omitted when unset params.comments.giscus.strict, ,- Strict title matching
params.comments.giscus.reactionsEnabled, ,- Shows reactions on the main post
params.comments.giscus.emitMetadata, ,- Sends discussion metadata to the parent page
params.comments.giscus.inputPosition, ,- Whether the input box sits above or below the list
params.comments.giscus.theme, ,- The giscus theme;
autofollows the site’s light/dark state params.comments.giscus.lightTheme, ,- The giscus theme or custom CSS URL used in light mode
params.comments.giscus.darkTheme, ,- The giscus theme or custom CSS URL used in dark mode
params.comments.giscus.loading, ,- The iframe loading strategy
params.comments.giscus.lang, ,- 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 toen params.comments.giscus.ariaLabel, ,- The comment container’s
aria-label. The default is English. For a multilingual site, write one per language params.comments.giscus.errorMessage, ,- Text shown after loading fails. The default is English. For a multilingual site, write one per language
params.ui.feedback.enable, ,- The two “was this page helpful?” buttons at the page end. There is no backend. Records a structured event if
gtagis present params.ui.feedback.reasons, ,- 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,- 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, ,- The product repository URL, for “open a project issue” and the navbar GitHub entry
params.github_branch, ,- The branch edit links point at
params.github_subdir,- The content site’s subdirectory inside a monorepo
params.path_base_for_github_subdir,- Rewrites normalized
/source paths. The map acceptsfromandto. External mounts require an explicit mapping to a repository-relative result. See repository links. params.github_url, ,- 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, ,- What follows “last modified”:
subjectthe commit subject,hashthe short hash,nonenothing. An invalid value warns and falls back params.images, ,- Site-level social card. Supplies
og:imageif a page has no image. Used only for metadata. Never rendered as a list thumbnail params.upstream_source, ,- Default
data/upstreamsrecord name for pages that declareupstream_link; page front matter can override it params.upstream_modified, ,- Site default for whether attributed material is adapted. A page can override it. No attribution renders without
upstream_link params.default_featured, ,- Removed. Use
params.imagesor a sectioncascadewithimages. 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:
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, ,- Enables the mind map fence site-wide — see Markmap
params.mermaid,- Configuration passed to
mermaid.initialize(). Keys are lowercase. Dark mode automatically overridestheme params.plantuml, ,trueenables local rendering;falsedisables all PlantUML renderingparams.plantuml.enable, ,- Enables local PlantUML rendering — see PlantUML
params.plantuml.svg_image_url,- Optional PlantUML service endpoint; absent means local browser rendering
params.plantuml.svg, ,- Server mode only: inline SVG instead of an
<img> params.drawio.enable, ,- Enables the edit button on
.drawio.svgimages — see Draw.io params.drawio.drawio_server,- Draw.io editor address. Required when enabled. If absent, the theme warns and leaves Diagrams.net off
params.highlight_classes, ,- Emits Chroma classes for highlighting;
falsereturns to Hugo’s inline styles params.ui.code_copy, ,- Copy button on code blocks. The value
falseremoves it globally. A fence’s owncopy=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.
| 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, ,- Generates a table of contents at the top of the print page. The value
falseomits it params.print.section_break_wordcount, ,- 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, ,- The primary language, served without a path prefix
languages.<lang>.label,- The language’s endonym, shown in the language menu
languages.<lang>.locale,- The full locale, used for
<html lang>and SEO languages.<lang>.weight,- Language order, and the cycle order when clicking the language icon
languages.<lang>.title,- The site name in that language
languages.<lang>.direction, ,- Set
rtlfor a right-to-left language
Paired files, anchor alignment and fallback for untranslated pages are in Languages.
Version parameters:
params.version,- The identifier of this site variant, which need not be a Git ref — see Versions
params.version_menu, ,- The version menu’s title
params.version_menu_pagelinks,- On switching version, try the same path on the target site first
params.versions,- Version entries:
version,url,kind;name: '---'is a divider params.archived_version,- Shows the “this is an archived version” banner at the top
params.url_latest_version,- The link to the current version inside that banner
params.time_format_blog, ,- Blog date format, overridable per language
params.time_format_default, ,- All other date formats, overridable per language
Miscellaneous
taxonomies,- Hugo’s own: enables
tag: tags/category: categories— see Taxonomies params.taxonomy.page_header,- Shows only listed taxonomies in a post header. If unset, shows all
services.googleAnalytics.id,- Hugo’s own: the analytics script is injected in production builds only — see Analytics and SEO
module.hugoVersion.min, ,- The theme’s declared Hugo floor. An older version fails the build
module.hugoVersion.extended, ,- 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:
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:
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:
The theme declares the minimum in hugo.yaml and theme.toml. The site’s
module.hugoVersion.min should match it.
Related
- Brand and appearance — site name, logo, colors, fonts
- Navigation and menus — navbar menu, page actions, footer
- Layouts and page types — shell, sidebar, table of contents
- Page parameters — the full front matter table
- Troubleshooting — locating a build failure
2 - Brand and appearance
This page 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:
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:
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:
The top-level title is the fallback. The value of languages.<lang>.title takes precedence.
Logo and wordmark
The theme ships assets/icons/logo.svg and uses it by default. To replace it,
put the icon file in the site’s assets/ or static/ and point the
configuration at it.
params.logois the square mark used by the navbar, sidebar, and footer. Underassets/, it uses Hugo’s resource pipeline and can be fingerprinted. Understatic/, Hugo publishes it unchanged. The path is relative to theassets/orstatic/root.params.wordmarkis the horizontal wordmark. If you set it, the navbar replaces “icon + site name” with it. On a narrow screen, the navbar falls back toparams.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:
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:
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.
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:
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.
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:
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:
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.uistill supplies the main face; usefonts.bodyfor 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:
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:
Roles inherit through normal CSS rules. To change the font for one content kind, you do not need component selectors:
A monospace stack needs a CJK fallback, or mixed code blocks fail to align:
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
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.
Footer
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 modoverwrites it); - Do not
@importthe theme’s internal partials individually. They are not a public Sass interface, and their import order may change; - Do not override
baseof.htmlto 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
- 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.
Related
- Configuration — types and defaults of the brand parameters
- Navigation and menus — navbar menu, page actions and footer data
- Layouts and page types — shell, sidebar and table of contents
- Images — images in the body, light/dark pairs and captions
- Home and landing pages — hero, sections and landing data
3 - Home and landing pages
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:
Section data is a file per language:
home page data
- data/
- home/
- en.yamlEnglish home page
- zh.yamlChinese home page
- home/
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.
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/).
Hero
The hero is the first screen. It is the only section with a large title and an illustration.
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:
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:
These fragments come from the theme repository’s executable regression
fixture tests/site/data/landing/demo/en.yaml.
You can copy the field names.
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.
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
- pricing/
- landing/
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:
sectionsin the page’s front matter;data/landing/<key>/<exact language>.yaml;- The exact-language entry inside a single
data/landing/<key>.yaml; - The English or language-less record.
You can put small amounts of data in front matter. However, landing: and
sections: are mutually exclusive:
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:
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 |
| 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
- Run
hugo --printPathWarnings. This detects misspelled types, missing data keys, and simultaneouslandingandsections. - Open the home page and any landing page. Compare sections with their data files. Check every language.
- Reload with JavaScript disabled. Confirm that content remains visible without motion.
- Check light and dark modes. Confirm that
image.lightandimage.darkshow the correct images. - For a subpath deployment, confirm that all internal links and images include the prefix.
Related
- Brand and appearance — site name, logo, colors, and fonts
- Navigation and menus — navbar, footer and the language menu
- Releases and downloads — the data behind the
downloadsection - Languages — enabling languages and splitting data by language
- Configuration — full definitions of
params.ui.landing_searchand the rest
4 - Navigation and menus
This page covers the ways a reader moves between pages: the navbar menu, the section switcher, breadcrumbs, page actions, previous / next, and the footer. The sidebar tree and the outline belong to Layouts and page types.
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:
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”:
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:
- Every entry is one icon and one title on its own row, in one
moderate-width column. A child’s
params.descriptionis 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.columnsparameter 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:
iconin the target page’s front matter;- The menu entry’s own
params.icon; - A built-in default matched by identifier or section name (
docs,blog,examples,community,about,download,githuband others); fa-solid fa-linkwhen none matched.
An icon is one Font Awesome class pair, with the free faces supplied locally by the theme:
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.
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
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
It can also be turned off for one page or one section:
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.
To let a large subtree become a root of its own (a versioned API reference, a
self-contained handbook), in its _index.md:
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.
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 |
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:
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:
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.
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:
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.
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.
Backlinks
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:
A page overrides it in front matter, and a section cascades it to everything below:
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 footer
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:
- If
brand.nameandbrand.logoare absent, the footer uses the site’s brand name, logo, and wordmark. The fieldstaglineandsloganrender Markdown. - An internal
urlresolves against the current language root. The settingexternal: trueopens a new tab withrel="noopener noreferrer". - The grid has as many columns as the data does.
- A single-language site can use
data/footer.yaml. - If
fatis configured without data, the footer automatically falls back toslim. 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
After changing navigation, check each of these:
- Confirm that the build has no
Navbar menu … supports one interactive child levelwarning. 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.htmlfinds 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.
Related
- Layouts and page types — sidebar tree, outline and shell types
- Configuration — defaults of the navigation parameters
- Command palette — page actions and custom commands
- Repository links and page info — the edit, history and issue links
- Organizing content — how the directory structure decides the sidebar
5 - Layouts and page types
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:
| 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:
Section roots are only navigation starting points
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:
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:
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):
The third sets the sidebar root to the site home. The sidebar and pager then share one tree:
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:
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.
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:
sidebar_menu_compactexpands only the current branch and adjacent branches. The valuefalseexpands the complete tree.sidebar_menu_foldablelets readers expand and collapse sections manually. Blog sections start expanded. To start one collapsed, setsidebar_expanded: falsein its_index.md.sidebar_expand_levelsis how many levels are expanded by default.sidebar_menu_truncatelimits rendered entries per section. This keeps the HTML usable for a thousand-page tree.sidebar_width_min/sidebar_width_maxset desktop drag-resizing limits in pixels. The browser stores the adjusted width locally. Double-click the divider to restore the default.sidebar_item_overflowdefaults toellipsis, which truncates long titles. For many long titles, usewrap.
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:
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.jsoncontaining asectionskey; - The page’s type is
docsorbook; - 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:
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:
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:
| 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:
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:
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:
list(the default): one title plus description paragraph per child page;cards: a grid of cards reading each child’stitle(orlinkTitle),descriptionandicon.
You can override this setting per section. An invalid value warns and uses a fallback:
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
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:
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:
The behaviour is in Navigation and menus and Brand and appearance, and the key definitions in Page parameters.
Verify
- The build prints
Total in …with no ERROR; - Confirm that a new
type: docspage has a left sidebar. If it does not, check its cascade andshell_types; - Drag the sidebar divider and reload. Confirm that the width persists. Double-click to restore the default;
- Below
mdthe sidebar becomes a closable drawer, and belowxlthe 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: wideis wider than adjacent pages; - With documentation at the site root,
hugo --printPathWarningsreports no duplicate output paths.
Related
- Configuration — defaults for the shell, sidebar and outline parameters
- Organizing content — directory structure,
weightand the sidebar tree - Navigation and menus — navbar, section switcher and pager
- Home and landing pages — writing the data for
layout: landing - Page parameters — the front matter keys used for per-page overrides
6 - Search
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
This key controls the page’s index reference, Lunr runtime, and search dialog. All three conditions must hold:
params.offline_searchis 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 withparams.ui.landing_searchon; - 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:
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.
| 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.
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:
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:
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
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.
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
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:
- If any page covers every term, show only those pages. Otherwise, show partial matches, labeled with matched/total terms, in descending coverage order.
- Within equal coverage, a contiguous complete phrase ranks first.
- Apply
search_boostto 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
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
A landing page for the results is needed too:
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
-
Build, and confirm one index per language was generated:
A development build uses
offline-search-index.zh.json. A production build fingerprints the filename, such asoffline-search-index.zh.7ab….json. Confirm one file per language. If a file is missing, that language’s pages never reached an index. -
Inspect the index first when diagnosing “Chinese finds nothing”:
The entry count should be close to the number of Chinese pages, and the
keywordsandboostfields should show what the front matter set. -
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.
-
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”.
Related
- 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
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.
Quick links
Select quick links from Hugo’s main menu by identifier. You do not need to define them again:
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:
This site uses the command above. Commands have seven fields. An unsupported key or invalid record warns and discards that command:
idis 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.titlesupplies the displayed title. Thedescriptionsupplies the smaller line below it. Theiconis one Font Awesome class pair.keywordsis an array of possible reader search terms. It participates in matching but is not displayed.urlandactionare mutually exclusive and one is required. Theurlaccepts a fullhttp/httpsaddress, site path, or in-page anchor beginning with#. An address with a host opens in a new tab. Theactionreferences a built-in action ID.
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:
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:
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:
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.
How it relates to full-text search
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:
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).
-
After a build, confirm the command manifest reached the page:
This confirms that HTML contains the action data. The remaining steps check the palette interface with local search enabled.
-
Open the site. Press ⌘/Ctrl + K without typing. Confirm this order: quick links, page actions, preferences, commands.
-
Type
>. Confirm that only commands and actions remain. A new command should appear after “open the GitHub repository”. -
Repeat step 3 in another language. Confirm that command titles change and order remains the same.
-
Open print preview (⌘/Ctrl + P). Confirm that it contains no palette.
Related
- Search — where the palette’s page results come from
- Keyboard navigation — f, c and the other single keys
- Navigation and menus — the source of quick links and group order
- Repository links and page info — prerequisites for the edit, history and issue actions
- Configuration — full definitions of
ui.command_paletteandui.page_context_menu
8 - Keyboard navigation
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.
Search and commands
| 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
contenteditableregion; - 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-motionenabled, 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:
For one page (interaction-heavy demonstration pages often need this), or for a whole section by cascade:
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).
-
After a build, confirm the cheatsheet button is in the page:
With keyboard navigation off and local search not enabled, the button is not generated at all.
-
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.
-
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.
-
Click in the search box and press J. The page should not scroll. The character should appear normally. Repeat with a Chinese input method.
-
Enable “reduce motion” in the system and press J. Confirm instant positioning without animation.
-
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.
Related
- 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
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
This site uses the configuration above. The four fields have these functions:
labelis the name shown in the language picker, written in that language’s own script:简体中文, notChinese.localeis the standard language tag. It supplies<html lang>,hreflangalternate links, and Open Graph metadata.weightdecides both language order and the picker’s cycle order, lowest first.paramscontains 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: . 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:
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:
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.
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:
Follow these two rules:
- 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.
- 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:
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:
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.htmlrun inside each pane frame unless guarded withwindow.OinkComparePane; see Analytics. - Your Content Security Policy must allow
frame-src 'self', and the server must not sendX-Frame-Options: DENYorframe-ancestors 'none'; see Content Security Policy.
Right-to-left languages
Declare the writing direction under the language:
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
-
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: -
Check
hreflangand canonical URLs against SEO behavior.hreflanglists only actual translations; each blog pagination page has its own canonical URL, and pages after page 1 omit language alternates. -
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.
-
Search the same concept once in each language and confirm both return results.
-
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.
Related
- Search — per-language indexes and CJK queries
- Navigation and menus — per-language menus and where the picker sits
- Home and landing pages —
data/home/<lang>.yaml - Writing pages — how to write explicit heading IDs
- Analytics and SEO — how
hreflangand the sitemap are consumed by search engines
10 - 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.
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:
The same list supplies “switch version” in the command palette. The menu and palette therefore agree.
The trade-off in page-for-page links
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:
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:
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.versionsis a cross-site list. It identifies the versions available in the menu and their locations. It describes other sites.params.versionidentifies this build’s version. It selects the menu entry and supplies the archive banner’s version number. It is also the fallback whendata/download/*.yamlomitsversion. 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.
baseURL must include the path segmentOtherwise 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).
-
After a build, confirm the version menu reached the page:
With
params.versionsempty or unset, the menu is not generated at all. -
Check whether the current version is marked selected:
If there is no result,
params.versiondoes not match an entry’sversionfield, orbaseURLdoes not match that entry’surl. Check the trailing slash. -
Visit each menu link. With
version_menu_pagelinksenabled, switch from a document that an older version lacks. Confirm that the destination is acceptable. -
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.
-
Press ⌘/Ctrl + K to open the command palette. Confirm that “switch version” lists the same versions.
Related
- Navigation and menus — where the version menu sits in the navbar and sidebar
- Command palette — “switch version” in the palette
- Deploy —
baseURL, subpaths and multi-target publishing - Releases and downloads — download data falling back to
params.version - Configuration — full definitions of
version/versions/archived_version
11 - Taxonomies
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:
This site uses that configuration. Apply these three rules:
taxonomies:defines the complete list. It does not add to an existing list. To retaintags/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:
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:
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:
If a whole section shares one category, set it in the section index’s
cascade. Do not repeat it on every page:
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:
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:
| 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/authorsfile. The term page owns the profile, which prevents conflicting sources. - A series term page does not use reverse-date order. Members with a
series_weightcome 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:
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:
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:
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:
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_taxonomiesenabled, 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:
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-articleinassets/scss/_styles_project.scss.toc_taxonomies: falsehides 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.
Related
- Page parameters —
categories/tagsand the other front matter keys - Blog posts — how the blog list works with taxonomies
- Navigation and menus — how to write navbar entries
- Languages — per-language content and menus
- Configuration — full definitions of
params.taxonomy.*andparams.ui.taxonomy_icons
12 - Repository links and page info
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.
Configure links with four keys
Every repository-related entry in the action menu derives from these keys:
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_repomust 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 ongithub_project_repo.github_project_repoidentifies a second repository for product bugs instead of documentation errors. Do not configure it if readers cannot distinguish the two.github_branchdefaults tomain. It identifies the content branch. Do not use the deployment branch or a branch generated by Pages.github_subdiris 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 aswebsitefor a repository with code andwebsite/.
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/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:
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:
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:
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:
The page end then reads “Last modified August 17, 2026 · …/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. Setfetch-depth: 0in 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_linkand four required keys:upstream_name,upstream_copyright,upstream_license, andupstream_notice. The page end names the work, copyright holder, and license, with a link to the full notice. Addupstream_modified: trueto append a “modified downstream” line. - Translation notice:
params.ui.translation_noticecontains the authoritative version’s language code. A translated page shows a link to that original. For a page authored natively in the current language, settranslation_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:
To enable it for the documentation section only, use a cascade (a blog usually keeps just comments):
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
localStorageper page and language. Returning readers can see and change it. - If the site has Google Analytics (
gtag), the widget sends adocs_feedbackevent withresult(solved/not_solved),page_path, andlanguage. Choosing a reason sends a second event withreasonandrefinement: 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:
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=:
In Markdown and RSS output, the grid becomes a list of
- [@handle](url) — role.
data/contributors.yamlThe 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:
- 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 withdata-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.
Related
- Page parameters —
annotation/feedback/pager/page_context_menuand the other page switches - Configuration — full definitions of
github_*,ui.lastmod_commitandui.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
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:
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:
- 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-noneand appears on screen only, never on paper. - The section title and summary.
- A whole-section table of contents, numbered
1:,2:,2.1:by level, linking to in-document anchors. - 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:
To remove the table of contents:
It can also be turned off for one section, in the section index’s front matter:
Excluding pages
To exclude link-only pages, redirect notes, or pages with one large screenshot,
set no_print:
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:
A4paper with18mm 16mm 20mmmargins; 10.5pt body text; the light palette forced.- Fonts use the
--td-print-font-familytypography 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:
- 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:
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: truepages. - 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.
Related
- Books — numbering, indexes and print for a whole book
- Organizing content — print order is sidebar order
- Brand and appearance — the print font token
- AI-agent support — the other non-HTML output
- Configuration — full definitions of
outputsandparams.print.*
14 - AI-agent support
.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:
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:
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.
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:
A multilingual site gets one per language: /llms.txt and
/zh/llms.txt. The content is a generated site index:
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:
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:
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:
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:
| 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:
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
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:
To keep RSS and remove only Markdown, list the remaining formats:
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.mdorlayouts/docs/list.mdaffects 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.
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:
Then check four things:
- Confirm that the selected page’s HTML
<head>hasrel="alternate" type="text/markdown"; - Click the copy button beside the title and paste the result. Confirm that it is Markdown instead of HTML;
llms.txtcontains no off-site links;- If you enabled these outputs, confirm that each page in
llms-full.txtstarts with aSource:line. The same page must have the sameidin each language’snavigation.json.
Limits
- The theme produces four types of machine-readable build-time files: a
.mdper page,llms.txt, optionalllms-full.txtper top-level section, and optionalnavigation.jsonper language. Hugo still ownssitemap.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 inllms.txt. LLMS,LLMSFULL, andNAVJSONare non-alternative formats. They have no<head>alternate links or page actions. Agents discover them through conventional paths and their entries inllms.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
.mdas fence source. It does not appear as a diagram.
Related
- Print — the other non-HTML output
- Command palette — the other entry point to the assistant actions
- Page parameters —
outputs/assistant_links/page_context_menu - Navigation and menus —
llms.txt’s site index comes from the main menu - Configuration — full definitions of
outputsandparams.ui.page_context_menu.*