This is the multi-page printable view of this section. .
Authoring
- 1: Writing pages
- 2: Organizing content
- 3: Page parameters
- 4: Blog posts
- 5: Books
- 6: Image albums with Expo
- 7: Releases and downloads
- 8: API reference pages
This section covers all content types supported by OINK: documentation pages, blog posts, books, Expo image albums, release and download pages, and OpenAPI references. They share a single Markdown dialect and front matter schema, while each content type adds its own layout conventions.
What a documentation page is made of
Every documentation page is a single Markdown file. YAML front matter between
the opening --- lines sets the page metadata (title, linkTitle,
description, and weight), followed by standard Markdown and OINK’s native
components:
Save the file as content/docs/install.md and run hugo server. The page is
served at /docs/install/ with an Install entry in the left sidebar.
Common Markdown patterns
Most everyday components use standard Markdown plus a Goldmark attribute block rather than custom shortcodes:
| Pattern | Syntax | Guide |
|---|---|---|
| Explicit heading anchor | ## Prerequisites {#prerequisites} |
Writing pages |
| Callout / admonition | > [!NOTE] (TIP, IMPORTANT, WARNING, CAUTION, DETAILS) |
Callouts |
| Code tabs | Adjacent code fences with ```bash {tab="macOS"} |
Tabs |
| Numbered steps | An ordered list followed by {.steps} on the next line |
Steps |
| Navigation cards | A bullet list of links followed by {.cards} on the next line |
Cards |
| Parameter / field table | A Markdown table followed by {.fields} on the next line |
Fields |
| Captioned or sized image |  followed by {width="800" caption="..."} |
Images |
| File tree | A ```filetree fenced block using a YAML-like list |
FileTree |
Content types and where they are covered
| What you are writing | Where to go |
|---|---|
| A documentation page: front matter, heading anchors, links, images, drafts | Writing pages |
The tree and the sidebar: _index.md, weight, icons, folding, multiple sidebar roots |
Organizing content |
| Looking up what a front matter key means | Page parameters |
| A blog post, a release announcement, RSS | Blog posts |
| A book: chapter numbering, figures and tables, cross-references, whole-book print | Books |
| An image album: file structure, metadata, layouts, and the image viewer | Expo albums |
| A release and download page: version cards, asset tables, checksums | Releases and downloads |
| An OpenAPI reference page | API reference pages |
| Writing in two languages: paired files, aligned anchors, fallback for untranslated pages | Languages |
| A component’s syntax and parameters | Components |
1 - Writing pages
This page covers the complete process for writing a documentation page. It explains file location, front matter, heading anchors, links, images, drafts, and page-end controls. The site must already build locally. If it does not, start with Quick start.
Creating a page
A page is a Markdown file under content/. Its location determines its URL.
For example, content/docs/install.md is published as /docs/install/. The Chinese
translation is a .zh.md file of the same name in the same directory, sharing
one logical path with the English page.
Use a single file for a page without attached resources. If a page has images,
cast files, or example configuration, create a directory. Name the page file
index.md and put the resources beside it. Hugo calls this a
page bundle:
the two page shapes inside content/
- content/
- docs/
- _index.mdsection index, English
- _index.zh.mdsection index, Chinese
- install.mdsingle-file page → /docs/install/
- install.zh.mdits Chinese translation
- anatomy/page bundle → /docs/anatomy/
- index.md
- index.zh.md
- shell.webppage resource, shared by both languages
- docs/
hugo new content docs/install.md generates an empty file with front matter
from an archetype. See the Hugo documentation.
You can also write the file manually.
When a Chinese page has no English counterpart, Hugo does not give it
resources without a language suffix. In that case the resource filename
needs the .zh. infix (shell.zh.webp) while the body still writes
shell.webp.
The front matter you need
Between the two --- lines at the top of the file is YAML front matter. Four
keys belong on every page:
Use description to state in one sentence what the reader can accomplish.
It appears on section index cards, in search results, and on social cards.
weight determines sidebar order. Only equal weights use alphabetical order.
Other keys are optional. These include the icon, draft status, search weight, comment switch, and page shell. For the full table, see Page parameters.
Heading levels and stable anchors
Start body sections at ##. Reserve # for title. The theme renders the page
heading. Another # in the body creates a second top-level heading. The right
column outline starts at ##. Hugo’s markup.tableOfContents determines its
maximum depth. This site uses ####.
Write an explicit English anchor {#id} on every ## and ###:
There are two reasons:
- Cross-language alignment. Hugo derives an ID from heading text. A Chinese heading produces a Chinese ID.
/docs/install/#prerequisitesand/zh/docs/install/#前提条件identify equivalent places with different anchors. A translation audit cannot compare them. Give the translated heading the English page’s ID. Both pages then share one fragment. - Link stability. Revisions can change heading text. They should not break public links. After publication, an explicit ID is a public route. If you must rename it, leave an empty anchor for the old ID:
Use lowercase English with hyphens, unique within the page. This site’s translation audit compares the heading IDs rendered by the English and Chinese pages and fails on a mismatch.
Writing links
Use one of these three forms, according to its purpose:
| Form | Example | When to use it |
|---|---|---|
| Absolute site path | [Configuration](/docs/customize/config/) |
The default. It points at a published route, is easy to audit and replace site-wide, and survives source files moving |
| Relative path | [another page](../organize/),  |
Resources inside the same page bundle, or a neighboring page that should follow the source directory |
The ref / relref shortcode |
[Configuration]({{</* ref "/docs/configure/overview" */>}}) |
If the target must exist at build time. A missing target fails the build instead of leaving a broken link |
All three carry a trailing slash and point at directory-style routes
(/docs/write/pages/), matching Hugo’s default permalinks.
The theme has no link render hook. It passes links to Goldmark unchanged.
External links do not automatically receive target="_blank". If you need a
new tab, write HTML or use the site’s layouts/_markup/render-link.html.
Plain Markdown links are not checked for target existence. Use these rules:
- Prefer absolute paths for internal links. After restructuring the site, use
grepto replace them site-wide. - When you move a page, add
aliasesfor the old path. Update internal links to the new route. Do not use an alias for navigation indefinitely. - If you are unsure that a target exists, use
ref. The build then checks it.
In a bilingual site, link to the logical page (/docs/write/pages/) rather than
to a .zh.md filename, and keep fragment IDs language-neutral.
Where images go
Put a page’s screenshots in its page bundle. Put shared images in
assets/images/. Put large files that require no processing in static/.
Use  for all three. An attribute line controls caption,
size, zoom, and numbering. See Images.
Drafts and publishing
A page with draft: true never reaches the build output:
Preview with hugo server -D to show drafts (-D is --buildDrafts). A page
whose date is in the future is also excluded. -F shows those pages. A production
build uses neither switch, and plain hugo publishes only finished content.
OINK’s Markdown extensions
The body is standard Markdown (Goldmark) plus the native forms below. Each is ordinary Markdown syntax with one attribute line, and each stays readable as source on GitHub:
| Component | Shortest syntax | Page |
|---|---|---|
| Callouts | > [!NOTE] on the first line of a blockquote |
Callouts |
| Tabs | Two adjacent fences each carrying {tab="Homebrew"} |
Tabs |
| Steps | An ordered list followed by a {.steps} line |
Steps |
| Cards | A list of links followed by a {.cards} line |
Cards |
| Field lists | A table followed by {.fields meta="type default"} |
Fields |
| Table extras | A table followed by {.matrix} or {caption="…"} |
Tables |
| Code blocks | {title="hugo.yml" copy=false} on the fence info line |
Code Blocks |
| Images | A standalone image followed by {caption="…" width="600"} |
Images |
| File trees | A filetree fence, one - name/ # comment per line |
FileTree |
| Mathematics | A math fence, or display math wrapped in $$ |
Math |
| Diagrams | A mermaid fence (also plantuml, markmap, echarts) |
Mermaid |
The remaining components use shortcodes. These include badges, keys, file includes, terminal recordings, and the Book figure and table family. For syntax and parameters, see Components.
A combined example: code fences and a callout inside steps.
- Install Hugo Extended, 0.168.0 at the oldest:
- Clone OINK Starter and preview it:
Tip
Add
-Dto preview drafts as well.
What appears at the end of a page
The theme generates these four blocks in a fixed order. Do not write them in the body. An optional Share bar appears before them:
| Position | What it is | Default | Where to configure |
|---|---|---|---|
| 1 | Feedback: the two “Was this page helpful?” buttons | Off | Repository links and page info |
| 2 | Last modified: the time and the most recent commit subject, linked to GitHub | On when Git information is available | Repository links and page info |
| 3 | Pager: previous and next, in sidebar tree order | On for docs / book / blog | Navigation and menus |
| 4 | Comments: giscus | When configured and enabled | Comments |
The theme also generates the action menu beside the title. It includes copy Markdown, edit this page, view history, open an issue, and print. Configure it in Repository links and page info.
To turn off a control for one page, set its front matter: feedback: false,
annotation: false, pager: false, comments: false. The keys are described
in Page parameters.
Verify
After writing a page, run a production build:
- The build must exit with
Total in …and no ERROR. An invalid attribute key or component parameter logs a warning with a source position and renders a safe fallback, whereas arefpointing to a missing target fails the build. --printPathWarningsflags any two pages that resolve to the same output path, which is most common in multilingual sites or after editingpermalinks.
Then confirm three things in the browser:
- The page appears in the sidebar at the position determined by
weight. - The right-hand outline lists your
##headings. Clicking a heading adds an English anchor to the URL. - The English and Chinese versions of the same heading share an anchor (this site audits that with
node scripts/check-doc-translations.mjs --public public).
Related
- Organizing content — how the directory structure decides the sidebar
- Page parameters — the full front matter table
- Components — each component’s syntax and parameters
- Languages — paired bilingual files and fallback for untranslated pages
- Local preview — the
hugo serverswitches worth knowing
2 - Organizing content
_index.md, weight, index styles, icons, folding, hidden pages, and documentation paths.OINK requires no separate navigation configuration. The directory structure
under content/ creates the sidebar tree. This page covers how directories and files are
arranged, section indexes, ordering, icons, folding, hiding, and multiple
sidebar roots.
Directories are the sidebar
Hugo calls a directory a section. Its Markdown files are pages. A nested
directory is a subsection. The sidebar renders this tree level by level.
weight determines order. linkTitle supplies labels, with title as fallback. The tree on the left comes from this source:
the first two levels of content/docs/
- content/
- docs/
- _index.mdsection root: type: docs + cascade
- about/Introduction
- _index.md
- features.md
- start/Get started
- _index.md
- write/Authoring (this section)
- _index.mdweight: 30
- pages.mdweight: 10
- organize.mdweight: 20
- frontmatter.mdweight: 30
- components/Components
- _index.md
- docs/
Every directory needs an _index.md
A section index is the _index.md inside the directory (_index.zh.md for
Chinese). Without this file, Hugo still creates the section. It has no title,
description, icon, or weight. The sidebar shows the directory name. You cannot
control its order.
A section _index.md also supports cascade. It applies shared settings to
the whole subtree. You do not need to repeat them on each page.
Ordering: use multiples of 10 for weight
Pages in a section use ascending weight order. Only equal weights use date
and linkTitle. Always use multiples of 10, such as 10, 20, and 30. You can
then insert a page between others without changing their weights. A section’s own
weight decides its position among its siblings.
A page with no weight counts as 0, and Hugo places those after every page that
does have one, ordered among themselves by date and title. That order changes as
content changes. Give every page a weight.
Single file or page bundle
A page with no resources of its own is a single slug.md. For a page with
images, cast files, or example files, use a directory. Put index.md and the
resources in that directory. The two shapes look identical in the sidebar and
produce the same URL. See
Writing pages.
List or cards on a section index
After the body of an _index.md, the theme appends an index of the child pages
in one of two styles:
list is the theme default. It shows one line per child page with its title
and description. cards is a grid of link cards reading each child’s icon,
linkTitle and description. This site uses cards, and this section’s index
page is the example. Override it in a single section’s front matter when that
section needs the other style:
Two page-level switches work independently of the style. simple_list: true
renders a compact bulleted list. no_list: true generates no index. Use the
latter when the page body supplies its own navigation.
In the card style, description is the card body. Keep it to one sentence
that fits on a single line.
Sidebar icons
Write one Font Awesome class pair in a page’s or section’s front matter:
Icon density is a site-level policy, so that leaf pages do not all carry icons:
| Value | Effect |
|---|---|
all |
Every entry that declares an icon shows it (the compatibility default when unset) |
groups |
Only the root and nodes with children show icons. Ordinary leaf pages do not |
none |
No entry icons in the sidebar |
For a new site, set groups explicitly. Groups then keep their identifying
icons, and leaf pages omit icons. This site uses that setting. Only the six
sections on the left have icons.
Expanding and folding
A section with children carries a fold arrow in the sidebar. OINK saves the whole sidebar’s collapse, width, and scroll state. To persist individual branch choices, add optional site code using the sidebar runtime API. By default, the path containing the current page is expanded. Other paths are collapsed. Blog-type sections are expanded by default.
Site-level folding, compact mode, initial expansion depth, width and truncation are configured in Layouts and page types. The full key definitions are in Configuration.
Hiding from the sidebar
| Front matter | Effect |
|---|---|
toc_hide: true |
The page is absent from the sidebar tree (it is still published, and links to it still work) |
hide_summary: true |
The page is absent from the section index |
sidebar_divider: true |
The entry stops being a link and becomes a group heading in the sidebar |
manual_link: https://… |
The sidebar row points elsewhere. Pair it with manual_link_title and manual_link_target: _blank |
toc_hide and hide_summary control two different entry points, so set both
only when the page should appear in neither.
Groups without a landing page
Since OINK 1.1, a divider section keeps its children while its title has no
link. This fixes the missing children in v1.0.0. Use this
_index.md when the directory should only organize child pages:
The title is a group label. If sidebar folding is enabled, its button folds
the children. The children remain in the pager, search, navigation JSON, and Print. Without JavaScript,
the group stays expanded. Omit build to keep publishing the section page
while still showing a non-link sidebar label. Leaf dividers keep their old
separator appearance.
toc_hide hides a section’s entire subtree. no_list only removes the child
list from a section’s body, and hide_summary removes an entry from its parent
page. None of these is a replacement for a group-only section. build.render: link retains a permalink without publishing a page. For an unpublished group,
prefer never. This prevents other navigation from creating a destination.
The shell follows type, not the path
The documentation shell (sidebar, table of contents, breadcrumbs, pager) does
not depend on the directory name. It depends only on whether the page’s type
is listed in params.ui.shell_types:
Documentation can therefore live at any path, with type assigned by a cascade.
To put a handbook at content/handbook/, the section root reads:
When the documentation directory is not called docs, sidebar_root_for: self
is needed alongside type: docs. Otherwise the sidebar looks for its root at
params.ui.docs_section (default docs), and a reader under /handbook/
sees the /docs/ tree.
Multiple sidebar roots
By default, the current top-level section is the sidebar root. A row above the tree names that root. A large subtree can have its own root. For example, use a separate root for a versioned API reference or a self-contained handbook:
| Value | Meaning |
|---|---|
self |
The section’s index page and all its descendants take it as their sidebar root |
children |
The index page stays in the parent tree. Only descendants use this root |
The switcher above the root is site-wide. It lists every top-level section and
every section that declares sidebar_root_for: self. With one entry, it shows
a plain link. With two or more entries, it shows a dropdown. To keep a
top-level section or nested self-root out of the global choices, write
sidebar_root_menu: false in its _index.md. The current root remains as a
location marker when browsing that section.
Below the switcher, the section index remains the tree’s first link. The
switcher selects a tree. The root link opens a document.
sidebar_root_link_self: false makes that row point at the parent section
instead.
Verify
The build must complete with Total in … and no ERROR. --printPathWarnings
flags any two pages that resolve to the same output path when restructuring
directories.
Then confirm each of these in the browser:
- The sidebar order matches the
weightvalues you wrote, and a new section appears where expected. - The section index lists every child (a missing one comes from
hide_summaryor a missing_index.md). - Breadcrumbs and the pager follow the same order as the sidebar, because the pager reads the same tree.
- The tree has the same shape after switching language (every
_index.mdneeds a.zh.mdcounterpart).
When sidebar entries exceed params.ui.sidebar_menu_truncate, the build warns
and says what to raise it to. Do not ignore that warning. Truncated entries
never appear in the sidebar.
Controlling a branch from site code
The window.OinkSidebar API is available since OINK 1.1. v1.0.0 does not
provide it. Load site code after the theme scripts, for example through
layouts/_partials/hooks/body-end.html, and wait for ready before reading or
restoring branch state. This example expands the first sidebar group:
Use the button’s existing aria-controls value as the region ID.
getState(id) returns {id, expanded} or null. A change sends one
oink:sidebar-disclosure event on document, after the button, region and
accessibility state agree. Its detail is {id, expanded, source}. Repeated
writes of the same value send no event. Restoring through the API keeps the
current page’s ancestor groups open, while a reader can still fold them.
The theme does not save individual branch preferences. A site that adds this should own the storage key’s language and navigation-version scope, tolerate unavailable storage, and ignore IDs absent from the current page. The sidebar contract defines the lifecycle.
Related
- Writing pages — how to write a single page
- Page parameters — the full definition of every front matter key used here
- Layouts and page types — site-level shell, sidebar and table-of-contents settings
- Navigation and menus — the navbar menu, breadcrumbs and pager
- Languages — keeping a bilingual tree consistent
3 - Page parameters
This page lists all page-level parameters that OINK reads, including explicit
1.x compatibility no-ops. It omits keys that the theme reads only to warn about
a rename or removal. Those keys are in
Migration, and they are also kept out of the
generated editor schema. Hugo’s own front matter fields (slug, url, build,
sitemap, expiryDate and others) work as usual. For their meaning, see the
Hugo documentation. Site
parameters (params.* in hugo.yml) are in
Configuration.
How to read the tables
Precedence, highest first:
- The page’s own front matter.
- The nearest
cascade. If several cascade layers set the same key, the closest layer takes precedence. - The site parameter in
hugo.yml.
Keys whose Default column says “site value” fall back to the site parameter of the same name when unset.
Write page keys at the top level of front matter, without the site key’s ui.
prefix. For example, the site’s params.ui.section_index becomes the page’s
section_index. Do not nest these keys in a ui: block: the theme neither
reads nor reports a ui: block there. If a setting has no effect, check its
key name against this page.
Inside a cascade, use the same key names one level deeper:
An invalid value does not abort the build: the theme logs a warning naming the
key, supplied value, and fallback, then renders the page with the default listed
below so a single typo does not return HTTP 500 across hugo server.
When continuing with a default would publish misleading metadata—such as an
incomplete upstream attribution—the theme logs a warning and omits the block
entirely. Unresolved content references (ref / relref) still fail the build
through Hugo.
Basics
title, ,- Page heading, browser title, search result title. Required on every page
linkTitle, ,- Short name in the sidebar, breadcrumbs, pager and cards
description, ,- One-sentence summary for section cards, search snippets, and
meta description. Blog pages also show it as an introduction above the body weight, ,- Order among siblings. Use multiples of 10.
0(unset) sorts after every page with a weight. See Organizing content draft, ,- A draft never reaches build output. Use
hugo server -Dto preview it. See Writing pages date, ,- Blog date and release-page sort key. A future date excludes the page by default
lastmod, ,- The page-end “last modified” time. No manual value is needed if the site enables
enableGitInfo aliases, ,- Redirects an old path to this page. Use for page migration rather than everyday navigation
type, ,- Decides the template and the shell:
docs,book,blog,swagger— see Organizing content layout, ,- Picks a layout for one page:
landing,releases cascade, ,- Applies the keys below to the whole subtree
Sidebar and navigation
The guide is Organizing content.
icon, ,- Icon in the sidebar, section cards and search results, e.g.
fa-solid fa-rocket toc_hide, ,- Excludes this page and its subtree from sidebar navigation and the pager sequence, in both content-derived and explicit trees
hide_summary, ,- Absent from the section index
sidebar_divider, ,- A non-link group heading, excluded from pager destinations. The 1.1 implementation retains a section’s children. Use
build.render: neverfor a group without its own page sidebar_expanded, ,- This section is expanded by default in the sidebar
sidebar_root_for, ,- Makes this section a sidebar tree root.
selfincludes the section index.childrencovers descendants only. Any other value warns and is ignored sidebar_root_link_self, ,- The root row links to itself.
falselinks to the parent section instead. A non-boolean warns and usestrue sidebar_root_menu, ,- Includes a top-level section or nested self-root in global switcher choices. An excluded current root remains a location marker. The nested-root exclusion is fixed in 1.1
toc_root, ,- When the sidebar root is the site home, excludes this whole top-level section from the tree and the pager sequence
manual_link, ,- The sidebar and section index row points elsewhere
manual_link_relref, ,- The same link, resolved with
relref. A missing target fails the build manual_link_title, ,- Hover title for the manual link
manual_link_target, ,- For example
_blank. The theme addsnoopener no_list, ,- The section index generates no child list
simple_list, ,- The child index renders as a compact bulleted list
section_index, ,- Style of the child index. An invalid value warns and falls back
section_index_columns, ,- Column count in the card style
notoc, ,- Hides the right-hand page outline
pager, ,falseturns off previous / next for this page. A non-boolean warns and is ignorednavbar_enabled, ,- Whether this page renders the navbar
navbar_autohide, ,- The navbar hides itself on pointer devices
breadcrumb, ,- Whether this page renders breadcrumbs. Docs/Book default on. Blog defaults off
theme_color, ,#rgb/#rrggbbhex value for this page’s accent backgrounds. In a section root’scascade, it gives the whole section an identity. See Brand and appearancetheme_color_dark, ,- The dark-mode accent. If a page overrides
theme_colorunder a cascade that sets this key, it inherits that dark value. Override both.theme_color: falseopts the page out of an inherited section color entirely page_context_menu, ,- The page action menu on the title row (copy Markdown, edit this page, print, …)
page_context_menu.assistant_links, ,- The ChatGPT / Claude link items, written
page_context_menu: { assistant_links: false }. A page may only restrict the site policy. It may never enable these links alone
Page shell
Site-level defaults and what they do are in Layouts and page types.
page_width, ,- Width of the content column. An invalid value warns and falls back
reading_width, ,- Reading width on Book pages. Applies only to
type: book footer_style, ,- Footer shape. An invalid value warns and falls back
body_class, ,- A class appended to
<body>for the site’s own CSS reading_time, ,- Whether this page shows a reading time.
falsehides it sidebar_enabled, ,- Whether this page shows the left sidebar.
falsehides it scroll_spy, ,- Silent 1.x compatibility no-op. The normal shell runtime always provides active-heading tracking
keyboard_nav, ,- Single-key keyboard navigation — see Keyboard navigation. A non-boolean warns and falls back
lastmod_commit, ,- How the commit is shown after “last modified”. An invalid value warns and falls back
sidebar_expand_levels,sidebar_menu_compact,sidebar_menu_foldable,sidebar_item_overflow, ,- Each page can override sidebar behavior. The values are in Configuration
sidebar_width_min,sidebar_width_max, ,- Per-page minimum and maximum for desktop sidebar resizing. A minimum above its maximum warns and restores the site pair
code_copy, ,- Default copy control for code blocks on this page. An explicit fence
copy=takes precedence toc_style, ,- Fixed right-rail panel or a wider rail beginning in the content flow
toc_taxonomies, ,- Whether taxonomy clouds join the right-rail outline
taxonomy_icons, ,- Per-taxonomy icon overrides for this page or section cascade
Search
The guide is Search.
search_keywords, ,- Extra search terms, including synonyms and other languages
search_boost, ,- Ranking multiplier. The final score is the text match score times this value. A non-numeric, non-finite, zero or negative value warns and falls back to
1.0 search_exclude, ,- Keeps the page out of the local index
Output formats
The guides are AI-agent support (.md and
llms.txt) and Print.
outputs, ,- The output formats this page generates.
[HTML]disables the.mdversion no_print, ,- Excluded from the whole-chapter and whole-book print aggregate
Page end: comments, feedback and provenance
The order is fixed: feedback → provenance → pager → comments. See Writing pages.
comments, ,- Whether this page shows the giscus comment section — see Comments
feedback, ,- The map form takes
enableandreasons. Anything else warns and falls back annotation, ,- The “last modified / provenance” block at the page end. Only a boolean is accepted. Other values warn and fall back
backlinks, ,- Whether the right rail shows the “Backlinks” group beside the table of contents. A section can cascade it. Only a boolean is accepted; anything else warns and falls back — see Navigation and menus
translation_notice, ,- The language code of the authoritative version, so a translation can say so and link back. Write
falseon a page authored natively in this language
Upstream attribution
When a page is derived from material elsewhere, upstream_link declares the
source and the page-end provenance line gives the work, the copyright holder,
the license, and a link to the full notice. This family resolves site parameters
→ the data/upstreams entry named by upstream_source → this page’s front
matter. The most specific declaration takes precedence.
upstream_link is read from front matter only (a cascade counts, site
parameters do not). A site-wide value would make every page claim the same
source. A companion key without upstream_link warns and the attribution is omitted.
upstream_link, ,- The address of the material this page is derived from. An empty string opts out of an inherited cascade value
upstream_name, ,- The upstream work, as the attribution names it. Required once
upstream_linkis set upstream_copyright, ,- The copyright notice, retained as upstream wrote it. Required
upstream_license, ,- Must be found in
data/licenses, or it warns and the attribution is omitted. Required upstream_notice, ,- The page carrying the full notice (licence text, warranty disclaimer, upstream NOTICE, snapshot pin). Required
upstream_ref, ,- The tag or commit the snapshot pins, shown in parentheses after the work
upstream_source, ,- The entry name in
data/upstreams, for upstream facts shared by many pages. A missing entry warns and omits the attribution upstream_modified, ,- Changes the credit verb to say the work was adapted. If the site has repository information, the same attribution sentence also includes a “view history” link. A non-boolean warns and the page is treated as unmodified
Missing any one of the four required keys (upstream_name,
upstream_copyright, upstream_license, upstream_notice) warns and omits the attribution.
A partial attribution can mislead readers more than an obvious omission. The theme ships an SPDX
table at data/licenses.yaml, and a site adds to or overrides it with a file of
the same name.
Image zoom
image_zoom, ,- Whether images on this page open full size — see Images. A non-boolean warns and falls back
Blog posts
The guide is Blog posts.
See List layouts for the four presentation choices.
gallery and blog_gallery are available in OINK v1.4.0;
the supported layouts are list, cards, table, and gallery.
author, ,- Post byline. Inline Markdown is allowed. Ignored on a page that has
authors authors, ,- Terms of the
authorstaxonomy, in byline order — see Authors and bylines. Needsauthor: authorsundertaxonomies: series, ,- Terms of the
seriestaxonomy. The strip above the body uses the first one — see Series series_weight, ,- Place in the series. Weighted members come first in ascending order, the rest follow by ascending date
tags, ,- Tags — see Taxonomies
categories, ,- Categories, likewise
images, ,- The first entry becomes the post’s featured image and share card. Put it in a section
_index.mdcascade for a section-wide default.images: []opts the page out of an inherited cascade value. It does not suppress an image the page bundle already supplies under afeatured,coverorthumbnailname byline, ,- Credit shown with the resolved featured image when that image is rendered
featured_image, ,- How this article renders its own featured image.
herocreates a full-width image shell. An invalid value warns and falls back blog_index, ,- Blog section index layout. A standalone
tablewithblog_index_toggle: falselists the whole section without pagination. An invalid value warns and falls back blog_index_columns, ,- Card columns at wide breakpoints. Medium and narrow layouts retain their responsive limits
blog_index_size, ,- Posts per page for
list,cards,gallery, and all four views when switching is enabled. A standalonetableignores it blog_index_toggle, ,- Publishes all four layouts and remembers the reader’s choice. When false, publishes only the configured layout and ignores saved layout choices
blog_gallery, ,- Replaces the whole site gallery block. Omitted fields use built-in defaults; invalid fields warn and fall back. Reader choices for mode and size take precedence
blog_gallery.mode, ,- Justified rows with 6px gaps, masonry with visible captions, or rows without gaps. Independent of the outer
blog_indexlayout blog_gallery.size, ,- Target gallery tile size in CSS pixels; independent of the posts-per-page setting
share, ,- The page-end share targets. Replaces any inherited list.
falseopts this page out. See Share. An unknown target warns and is dropped summary, ,- Fallback excerpt for gallery entries and post rows on tag and category pages.
descriptiontakes precedence
Book
The guide is Books. A whole book sets type: book through
a section cascade.
book_number, ,- Chapter number, shown before the page title and the sidebar entry
book_status, ,- Marks a draft chapter: flagged in the sidebar and contents, and left out of the indexes by default
sidebar_headings, ,- Expands the h2–h4 branch under the current sidebar entry. Out of range warns and falls back
book_draft_banner, ,- Adds a banner at the top of a draft chapter. A non-boolean warns and falls back
Expo albums
OINK 1.3.0 uses type: expo for album pages. See Expo albums for the authoring guide.
expo, ,- Replaces the site block; absent fields use the built-in defaults below
expo.images, ,- Pattern for image resources in the page bundle
expo.mode, ,- Initial mode when the reader has no stored choice
expo.size, ,- Target size from 160 to 360 CSS pixels; a stored reader size takes precedence
Image titles, captions, credits, weights, explicit IDs, and separate originals
use native Hugo resources metadata. See Image metadata
for the fields and an example.
Landing
The guide is Home and landing pages. Any page with
layout: landing uses the landing shell.
landing, ,- Data is taken from
data/landing/<key>/<language>.yaml sections, ,- Section definitions inlined in front matter, taking precedence over
landing. A non-array value warns. No sections render
Release pages
The guide is Releases and downloads. A section with
layout: releases ignores weight and sorts by release date and SemVer,
newest first.
release_url, ,- One GitHub release URL,
https://github.com/<owner>/<repo>/releases/tag/<tag>. The theme extracts the owner, project and tag and generates source archive links. The date comes from the page’sdate. Download assets come from the release body’schecksumsblock (see Releases). Anything else warns and the release block is skipped
Related
- Writing pages — the handful of keys every page needs
- Organizing content — what the sidebar and navigation keys actually do
- Configuration — the full table of site parameters in
hugo.yml
4 - Blog posts
Write a blog post’s body like a documentation page. The shell differs. A post has a date, author, tags, and featured image. The list uses date order, newest first. The section has an RSS feed. This page covers creating the blog section, a post’s front matter, featured images, list layouts, pagination and feeds.
The blog directory
A blog is a section under content/, and type: blog gives it the blog shell.
Subdirectories divide it by publisher and audience, with posts sitting flat
inside. Year directories are unnecessary: the list orders posts by their
date.
this site's content/blog/
- content/
- blog/
- _index.mdtype: blog + cascade
- _index.zh.md
- oink/engineering notes and announcements
- _index.mdcascade: images: [/images/oink.webp]
- oink-announcement.md
- oink-announcement.zh.md
- release/versioned release notes
- _index.mdcascade: images: [/images/releasenote.webp]
- 0.4.0.md
- 0.4.0.zh.md
- blog/
The section root applies the type to the whole subtree. It sets the section’s shared behavior:
params.ui.blog_section (default blog) names where the blog root is. Rename
the directory and either change that parameter or use sidebar_root_for: self
as above.
Blog sections are expanded by default in the sidebar and ordered by date, newest
first. To place one post at the top, give it a weight.
A post’s front matter
Where it differs from a documentation page:
dateis required. It decides the post’s place in the list and its RSS timestamp. A future date excludes the post from the default build. Usehugo server -Fto preview it.descriptionappears as an introduction above the body and as a search snippet. Write a sentence for the reader.authoraccepts inline Markdown, so[Vonng](https://vonng.com)works. For more than one author, a portrait, or a profile page, use theauthorstaxonomy below. The two do not interfere. A post rendersauthorifauthorsis absent.- The date display format comes from
params.time_format_blogand can be set per language (this site usesMonday, January 02, 2006in English and2006年1月2日in Chinese).
Bilingual posts are stored in pairs, keeping date, author, weight and
aliases identical across the two. Titles, descriptions and tags are
translated. Do not translate commit IDs, version numbers, commands, or URLs.
Featured image
Each row on a list or tag page has a thumbnail on the left. The resolver uses the first match in this order:
imagesin the post’s front matter, first entry;- An image resource in the page bundle whose filename matches
featuredorfeature, thencoverorthumbnail(it is cropped to a thumbnail, and the resource’s ownbylinebecomes its caption); - An
imagesvalue inherited from an ancestor section’scascade, nearest first.
A section-wide default uses Hugo’s native cascade over the whole subtree.
This site sets one for each of its two subsections:
To clear an inherited image on one post, write images: [] in its front matter.
To clear it for a whole subsection, put it in that level’s cascade. This does not suppress
an image supplied by the page bundle. To hide the image on the article itself,
use featured_image: none. List thumbnails and share cards use images separately.
The site-level params.images feeds the share card only and is never rendered
as a list thumbnail.
On the article itself
By default the resolved image appears on list rows and in the social card. Set
params.ui.featured_image to use the same image on the article itself:
| Mode | What the article shows |
|---|---|
none |
No article image. This is the theme default |
banner |
The image above the title in a fixed 16:9 figure. Articles use a consistent layout |
wash |
A faint image behind the article header, fading before the body |
hero |
A full-width image header |
The page key is featured_image. A subsection’s cascade enables it for that
tree. An individual post can opt out. A post without an image shows none in
any mode. A section can therefore enable it even if only some posts have images. These modes need no additional script.
List layouts and pagination
After the section _index.md body, the theme appends the post index, sorted
by date, newest first, without year groups. Choose its layout with blog_index:
| Value | Layout | What the reader sees |
|---|---|---|
list |
Horizontal entries (default) | Thumbnail, title, date, subsection, tags, and a summary |
cards |
Regular card grid | A cropped 16:9 cover above the title, metadata, and summary |
table |
Compact table | Date, title, and tags in one row per article |
gallery |
Image gallery | Proportional covers with titles and descriptions; click to open the article |
OINK v1.4.0 includes list, cards, table, and gallery.
Set the site default with params.ui.blog_index in hugo.yml, or set
blog_index in a blog section’s _index.md front matter to override it.
Use a section’s cascade to apply it to descendant sections. These settings
control native blog section indexes; term and taxonomy pages keep their own
layouts, and custom homepages need their own template integration.
List, card, and gallery views show 12 posts per page by default. Set the theme’s
blog_index_size in hugo.yml to change it:
The same key in a blog section’s front matter overrides the site value. The
theme explicitly passes this size to Hugo’s paginator. pagination.pagerSize
does not control these lists.
The card form
params.ui.blog_index: cards renders the same list as a grid of content cards
instead of rows. Each card shows a 16:9 image crop above the title, a date and
subsection line, and a three-line summary.
The column count applies above the xl breakpoint. Between md and xl, the grid
has two columns. Below md, it has one. If a card image resource supports
processing, Hugo applies .Fill, so readers download cropped previews.
Table and layout switching
A standalone blog_index: table with blog_index_toggle: false lists the
entire section without pagination. Set blog_index_toggle: true to add the
layout switch beside the title. In OINK 1.4.0, it cycles through
list → cards → table → gallery → list:
All layouts preserve date order and manual_link destinations. With switching
enabled, all four views show the same current page of posts, using
blog_index_size. Only the standalone table shows the entire section.
The switch remembers the reader’s choice. Set blog_index_toggle: false to
publish only the configured layout, regardless of a saved reader preference.
Hidden views use lazy images, although their markup and generated thumbnails
still contribute to build work. In v1.4.0, the switch cycles through all four
layouts.
Gallery form
gallery makes each article a linked cover,
using the existing images field or bundled featured image. The default wall
joins images into rows while preserving their proportions. Hover or keyboard
focus reveals the title and description; touch devices show them below the
image. Clicking opens the article. Posts without a cover keep a title tile.
The gallery toolbar offers three arrangements:
blog_gallery.mode |
Arrangement | Captions |
|---|---|---|
wall (default) |
Justified rows with 6px gaps | On hover or keyboard focus; below images on touch devices |
seamless |
The same rows without gaps | On hover or keyboard focus; below images on touch devices |
cards |
Masonry columns | Always visible below images |
blog_index: cards selects the regular card grid. blog_index: gallery with
blog_gallery.mode: cards selects masonry inside the gallery.
blog_gallery.size sets the target tile size, from 160 to 360 CSS pixels,
with a default of 240. It is independent of blog_index_size, the number of
posts per page. Readers can change the arrangement and size; their choices
are remembered separately from Expo albums.
Site defaults use the same blog_gallery block under params.ui; a page or
cascade block replaces it in full. Omitted fields use wall and 240;
invalid values warn and use those defaults. These settings are available in
v1.4.0. See the
site parameters and
page parameters for the reference tables.
RSS
outputs determines which pages produce a feed. Adding RSS to section
gives every section its own feed:
Setting outputs replaces all Hugo defaults. Include RSS explicitly if you
need feeds. If you omit it, that page kind has no feed. The build does not warn.
This site therefore has /blog/index.xml (the whole blog) and
/blog/release/index.xml (release notes only). A section feed recursively
includes every subsection’s posts. Subscribing to /blog/ covers the whole blog. An individual post has no .xml of its own.
Each language has its own feed at that language’s route plus index.xml. The
item limit is Hugo’s services.rss.limit. On the blog root and its first-level
subsection pages, the first action button beside the title row is the RSS link,
so readers do not need to construct the address manually.
To drop feeds site-wide, turn the kind off with disableKinds, which is more
thorough than removing RSS from each page kind:
Components use their static form in a feed. Disclosures are expanded, and interactive controls are removed. The four-output rules are the same for blog posts as for documentation.
Categories and tags
tags and categories are Hugo’s taxonomies, and the theme renders them as
chips in the post header, a tag cloud in the right column, and a filter menu in
the navbar. Enabling them, bilingual term labels, and switching them per content
type are covered in Taxonomies.
Release notes
A versioned release announcement is an ordinary post, conventionally under
blog/release/, with the version in linkTitle (Oink v0.4.0). For a download
page with release cards, asset tables and checksums, see
Releases and downloads.
Components in a post
Callouts, tabs, code blocks, images and tables work exactly as on a
documentation page. The syntax is in Components. Headings
in a post body take explicit English {#id} anchors too.
The four blocks at the end of a post — feedback, last modified, pager, comments — behave as on a documentation page. See Writing pages. A blog usually turns feedback off and keeps comments.
Authors and bylines
Declare the taxonomy to enable this feature. The theme adds no parameter:
A post then names its authors in order:
The article header renders portraits and linked names in that order. List rows
show the names. The blog feed includes each author alongside the site-level
managingEditor.
An author’s profile is the taxonomy term page. No data/authors file is needed:
The display name is the term page’s link title. It uses linkTitle if
available, otherwise title. A profile can use a full name and the byline a
short handle. description gives a one-line introduction. The body gives the
long introduction. The featured-image resolver selects the avatar. images:
and a bundled portrait follow the same rules as an article’s image. A bilingual profile is an _index.zh.md beside it.
An author without a profile page still has a byline. It shows the link title,
an initial, and an archive link.
The 0.4 author: string is untouched wherever authors is absent, and neither
form warns about the other.
Series
A series is a reading path through articles that each stand alone. Numbering, cross-references, and aggregate output belong to Book. A series has less structure. Declare the taxonomy to enable it:
An article names the series and may place itself in it:
The article then shows a strip above its body. It names the series, position,
and next part. A <details> contains the full list. This requires no JavaScript
or bundle member.
The term page content/series/<name>/_index.md is the introduction, and an
_index.zh.md beside it makes the pair bilingual.
Members with series_weight come first in ascending order. Other members follow
from oldest to newest. The content path breaks ties. The series strip
and term page use this same reading order. For implementation details, see
Authors and series.
A member of several series shows one strip, for the first term it names. A series of one shows none.
Neither authors nor series appears in the generic taxonomy chip row on an
article, because each has a surface of its own. Name one in
params.taxonomy.page_header to put it back.
Share
params.ui.share puts a share bar at the top of the page end. It is empty by
default, so nothing renders until a site names its targets, in the order it
wants them:
Sixteen targets are available: x, bluesky, mastodon, facebook,
linkedin, reddit, hackernews, telegram, whatsapp, line,
pinterest, weibo, chatgpt, claude, email, and copy. An unknown name
warns and is dropped. Discord is deliberately absent. It provides no share-intent URL. Use copy
for Discord. The theme does not infer a private scheme.
The page key is share, so a cascade scopes the bar to one tree, a page’s own
list replaces the inherited one, and share: false opts a single page out:
Only regular pages render the bar. Lists, term pages, and the home page have no single item to share. Print, Markdown, and RSS omit the bar.
Share targets are links carrying the page’s permalink and title, plus a local copy button. The bar loads no third-party scripts or stylesheets. It contacts a target only when the reader clicks its link. See the Share contract for the implementation rules.
chatgpt and claude hand that same build-time permalink to an assistant with
a prompt asking it to read the page. They are not the “open in ChatGPT” /
“open in Claude” entries of the page action menu, which the runtime rewrites at
activation time to the live browser URL and which therefore stay behind
page_context_menu.assistant_links.
The copy button is the built-in copy_link action, so the Command
Palette includes it on every page of every site. This applies even if no bar
is configured.
Verify
The build must complete with Total in … and no ERROR. Then confirm:
- The post appears in the right date order at
/blog/, with the date in the expected format. public/blog/index.xmlexists, contains the post, and its links are complete absolute addresses.- The thumbnail shows in the list (a missing one means none of the three featured-image sources matched).
- Tag chips lead to the corresponding tag page.
Related
- Writing pages — how to write the body
- Page parameters — the full definition of
author,imagesand the rest - Organizing content — directories and the sidebar
- Taxonomies — tags and categories
- Releases and downloads — version cards and asset tables
5 - Books
type: book: chapter numbering, numbered figures and tables, cross-references, generated indexes and whole-book print.A book is a content tree with type: book. The directory determines chapter
order. Front matter determines chapter numbers. Each figure, table, equation,
and example has a manually assigned number and stable anchor. Cross-references
resolve in all four outputs. The book root can generate whole-book print HTML.
Two settings are required. Enable attribute lines and passthrough in the site’s
markup.goldmark (see Components). Keep book in
params.ui.shell_types. The theme default includes it.
For a new book, start with the directory below. For an existing manuscript, see Migrating an existing manuscript.
A book’s directory
The book root is an ordinary Hugo section. Chapters are its subdirectories. Sections are pages inside each chapter. There is no second chapter list. The sidebar, pager, and generated contents all read this tree.
content/handbook/, one book
- content/handbook/
- _index.mdbook home: type: book + cascade, holding book-toc and the indexes
- ch01/
- _index.mdchapter 1 front page: book_number: 1
- install.mdsection 1.x
- bootstrap.md
- ch02/
- _index.mdchapter 2: numbered with book_number, optionally marked draft
- replication.md
- failover.md
- appendix.mdan unnumbered appendix, still in the sidebar and the reading order
Assign chapter numbers manually. book_number displays exactly what you write.
The theme never numbers chapters by directory order. The num on a figure,
table, equation, or example also uses an author-controlled string.
2-1, 5.3, and A-2 are valid. Rendering does not compute an index.
Rearranging the tree never changes a number that has already been printed.
The book home and chapter pages
The book root declares the type, cascades it to descendants, and explicitly
requests the print output. That aggregate is expensive to build, so the theme
does not turn it on for a consuming site:
A book section uses Hugo’s section output kind. home applies
only when the book sits at the site root:
A chapter page needs only its number and its order:
book_number appears before the page title, in the sidebar and in the generated
contents. book_status: draft is a visible editorial label and does not change
Hugo’s publication state. A draft chapter builds and publishes as usual.
sidebar_headings defaults to false and accepts true (h2 only) or a maximum
level from 2 to 4. A page or section cascade can override the site setting.
The right outline remains available when this left branch is disabled.
Give every heading that will be referenced an explicit ID, such as
## Synchronous replication {#sync-replication}. A generated slug works for
navigation. Do not use it as a long-term reference target.
The full key definitions are in Configuration and Page parameters.
Numbering: the native form
Each of the four numbered kinds has a native form. Put an attribute line
immediately after one Markdown block. Use num= for the number, #id for
the anchor, and caption= for a plain-text caption.
Figures
An attribute line follows the image block. Omitting #id defaults it to
fig-<num>.

The native figure form requires the site to set
markup.goldmark.parser.wrapStandAloneImageWithinParagraph: false. Otherwise,
the attribute line attaches to the paragraph and is ignored. The alternative
text comes from the Markdown image itself and is never replaced by the caption.
Tables
An attribute line follows a pipe table, and the default ID is tbl-<num>.
| Isolation level | Dirty read | Non-repeatable read | Phantom read |
|---|---|---|---|
| Read Committed | Not possible | Possible | Possible |
| Repeatable Read | Not possible | Not possible | Possible |
| Serializable | Not possible | Not possible | Not possible |
Equations
An attribute line follows a $$ block, and the default ID is eq-<num>. The
number and caption sit to the right of the formula on wider screens. On narrow
screens, they move below it and wrap. A wide formula can scroll horizontally.
Short captions keep the equation easy to scan.
The native form depends on the site enabling Goldmark passthrough. Without it,
use the eq shortcode below, which goes through local server-side KaTeX.
Examples
A code fence with num= and caption= is a numbered example, and the default
ID is eg-<num>. An #id on the fence names the enclosing <figure>, which
is the reference target. The caption is required: a caption without a number is
ignored, and a number without a caption is dropped with a warning. A numbered
example renders in one frame where the caption forms the header and the body
sits inside; a single code block shares the frame border without adding a
second border.
Numbering: the shortcode form
The four shortcodes fig, tbl, eq and eg render a <figure> identical to
the native form, register into the same target table, and sort by source
position. Use them when the native form is insufficient. Examples include figures with
several images or other Markdown, several tables under one number, sites without
passthrough, and examples with several fences and prose. A single
numbered image can use link in its native attribute line. It does not need
fig just for an outbound link.
fig takes src= (it also accepts inner Markdown content, and the two are
mutually exclusive) and additionally supports link, alt, width, height,
class, and the migration alias title:
tbl wraps the label, the table, the caption and the anchor in one semantic
figure:
| Output | Label | Anchor |
|---|---|---|
| HTML | Visible | Stable |
| Visible | Stable |
eq hands its content to local server-side KaTeX, so it does not depend on
passthrough:
Use a bare {{< eq >}} without parameters for unnumbered display math.
It registers no target. xref cannot reference it. It does not appear in the
equation index.
eg is a wrapping shortcode whose body renders under the page’s Markdown
policy, usually holding one or more fences:
IDs must be unique within a page, and within one kind a number maps to a single ID. A duplicate logs a warning with the first registration’s line number and keeps the first registration.
Hugo renders each shortcode body as a separate Goldmark document, whereas
footnotes belong to the page. A [^label] inside the body of tbl, eg,
fig, card, tab, field, or include logs a warning naming the file,
line, and label: if the definition sits on the page, the reference would print
literally as [^label]; if the definition sits inside the shortcode body, it
would generate a second footnote list whose fn:N IDs collide with the page’s
own footnotes.
If a table or code block needs footnotes, use the native form. A table,
image, or fence with {num=… caption=…} keeps its content in the page
document. Its footnotes then use normal numbering, links, and backlinks.
The rendered figure is the same either way, so this is usually a one-line
change. Text that resembles a footnote in code remains unchanged. This includes a
[^0-9] character class in a listing or a code span.
Cross-references
A target on the same page can be reached with a plain Markdown link: Table 2-1 points at the isolation table above. You must write the label and number manually. If you change a number, you must find its references yourself.
xref combines the label, number, and anchor. It works across pages and
languages:
See Figure 2-2 and Example 2-1; with an explicit anchor: Figure 2-1.
The rules:
- At most one kind key (
fig,tbl,eq,eg). The kind supplies the localized label (Figure / Table / Equation / Example) and derives the default anchor<kind>-<num>. anchor=overrides the derived anchor, for a target that wrote an explicit#id.page=references another page through Hugo’s page lookup in the current language, so the source never hard-codes a/zh/prefix.- Without a kind, both
anchor=and inner link text are required:{{< xref page="../ch01/install" anchor="sync-replication" >}}synchronous replication{{< /xref >}}. - A reference may precede its target. Nothing reads the registry at render time. Forward references are valid.
A plain cross-page Markdown link is still a site URL inside the whole-book
print. A reference that must also jump within the aggregate document is written
as an xref.
Indexes: contents and lists of figures
Five index shortcodes walk the same book tree, triggering descendant content and
aggregating what it registered. They usually sit on the book home
(_index.md) or on a dedicated “list of figures” page.
These five appear here only as source. They start at the current page’s
navigation root and process its descendants. In an ordinary documentation tree,
one would list the whole docs tree as a book. For the real effect, read
Write Beautiful Docs and inspect its
content/book/_index.md
source.
book-toctakes adepthof 1 to 3: 1 lists chapters, 2 adds nested sections, 3 also projects each page’s heading tree.drafts=falsefiltersbook_status: draftrows out of this generated list only, and does not affect publication.book-figures,book-tables,book-equationsandbook-examplestake no parameters. Each lists one kind, with entries like “Figure 2-1 — caption” linked to the stable ID.- In whole-book print, all of these links become in-document fragments.
Sequential reading and drafts
The pager is on by default for docs, book, and blog. It uses a pre-order
walk of the sidebar tree. The section index comes first, followed by its
children in weight order. Turn a whole type off with params.ui.pager_types, and a
single page off with pager: false.
Entries hidden with toc_hide, manual_link link-only placeholders and
sidebar_divider rows never become pager destinations.
Besides the “draft” label in the sidebar, a draft chapter can carry a banner above its body:
The banner appears only on pages that are both type: book and
book_status: draft, and its wording comes from the localization key
book_draft_notice.
Printing the whole book
Once the book root has the print output, it generates a cover, a local table
of contents, the root page’s body and every descendant chapter in visible
reading order, all inside one HTML document. Pages with no_print: true,
link-only nodes, divider rows and hidden placeholders never become chapters.
Inside the aggregate, the IDs of numbered components are preserved byte for
byte. Markdown heading and footnote IDs within a page are prefixed with their
source page to avoid collisions when several chapters share an anchor such as
summary or start with fn:1. Generated links are rewritten to match. A
page rendered alone as Print keeps the same page-local IDs as ordinary HTML.
Only a multi-page section or whole-Book aggregate adds the namespace.
The output is print-oriented HTML. An opt-in BookManifest output records that
same reading order as JSON, and the theme ships bin/book-epub.py and
bin/book-pdf.py, which turn the manifest and the print HTML into EPUB and
PDF.
The switches themselves, and per-chapter print, are covered in Print.
Migrating an existing manuscript
An existing manuscript usually expresses figure and table numbering with the
site’s own figure shortcode, bold pseudo-captions, and bare links to #fig_*.
The theme repository ships a migration script that rewrites those legacy forms
into fig, tbl and xref while preserving the public anchors already
published. Pin the site to a released OINK version that includes the Book
components first, then migrate the content.
Four profiles cover the legacy conventions of three real manuscripts (DDIA contributes one each for v1 and v2), and each recognizes only the forms actually observed in them:
--profile |
Legacy form it recognizes |
|---|---|
tpme |
A pseudo-h6 caption beside an image, a caption beside a table, and bare /en/...#fragment links |
ddia-v2 |
The site’s own figure shortcode, classified by number into figure / table / code example |
ddia-v1 |
A bare image with an adjacent bold numbered caption, with the ID derived from the image filename |
pg-internal |
A bold or italic “Figure N” caption in Chinese or English next to an image, and a numbered table caption next to a table |
--profile- Required; one of the four values above
--root- Required; the consuming repository’s root
--path- Restricts to a file or directory under
--root; repeatable. The default scans the whole content tree --write- Applies the rewrite. The default is a dry run that writes nothing
--no-diff- Suppresses the diff while keeping the summary and the report
--report- Writes the machine-readable JSON report
The diff goes to standard output, the summary to standard error, and the report
carries files_scanned, files_changed, counts, skipped and idempotent.
The script rewrites only targets it can identify uniquely. If the number is
unclear, the caption is not unique, or the marker form is unrecognized, it
preserves the text. It records the item in skipped for human review. Bold text, inline
code and formulas inside a legacy caption degrade to plain text, because a Book
caption is plain text by contract.
After reviewing the diff, apply it on a dedicated branch and run a second pass to confirm idempotency:
The second report should show files_changed: 0, empty counts, and
idempotent: true. The script signals idempotency with exit code 0.
The profiles recognize only the legacy forms actually observed in those three
manuscripts. Where a manuscript’s conventions fall outside the four, the script
does not apply and the rewrite is manual, following
Numbering: the native form. The theme repository’s
bin/check-book-migrations.py covers all four profiles with a dry-run and an
idempotency check.
Verify
- Build with visible diagnostics:
hugo --printPathWarnings. A malformed number, a duplicate ID and a missing caption all produce warnings that need review. - The page should show a localized label such as “Figure 2-1”, clickable
xreflinks, and anchors that land correctly. - Compare the chapter order across all four places: sidebar, pager,
book-tocand whole-book print. - Check the Markdown output:
curl -s http://localhost:1313/handbook/ch02/index.md. The shortcode form should degrade to**Figure 2-2.** captionplus the original body, and the native form should keep its source block and attribute line as they are. - Run the anchor check from the theme repository against the build output:
It verifies that every reference’s target anchor exists, that kind and number agree, that page-local IDs are unique, and that a numbered image has alternative text appropriate for its caption.
Book shortcode parameters
num, ,- Required (except for the bare
eqform). Matches[0-9A-Za-z.-]+and must be quoted id, ,- Matches
[A-Za-z][A-Za-z0-9_.:-]*and is preserved byte for byte caption, ,- Required for
eg. Optional forfig,tbl, andeq. Not Markdown class, ,- Appended to the
<figure>. Requiresnum src, ,figonly. Mutually exclusive with inner content, and follows the shared image resolution orderlinkaltwidthheight, ,figonly. Width and height are positive integerstitle, ,figonly. A migration alias forcaption, mutually exclusive with it
xref:
figtbleqeg, ,- At most one. Supplies the localized label and derives the anchor
anchor, ,- Required when no kind is given, together with inner link text
page, ,- Resolved through page lookup in the current language. A missing page warns and renders text without a link
book-toc:
depth, ,- 1 chapters / 2 with nested sections / 3 with the heading tree
drafts, ,falsefilters draft chapters out of the generated list
book-figures, book-tables, book-equations and book-examples take no
parameters.
Limits
- There is no automatic numbering. Assign chapter, figure, and table numbers manually. Only an explicit edit changes a number. A build does not change it.
- The attribute line must touch its block, with no blank line between. If a tool such as Prettier moves an attribute line, it fails silently. The figure becomes a plain image.
book_kindandbook_partare metadata keys the contract acknowledges but the current templates do not render. The ones with a visible effect arebook_numberandbook_status.- The index shortcodes trigger descendant content rendering, which noticeably lengthens the build on a very large tree. The same reason is why whole-book
printhas to be requested explicitly. - A footnote reference cannot appear inside a shortcode body; the theme logs a warning and points to the native form instead (see Numbering: the shortcode form).
- Packaging requires explicit selection and runs outside the build.
BookManifestplusbin/book-epub.py/bin/book-pdf.pyproduce EPUB and PDF. Hugo alone emits neither file. Typeset pagination, font embedding, and index compilation remain outside the contract.
Related
- Organizing content — how the tree becomes the sidebar and the reading order
- Images — captions, sizing, zoom and image processing
- Tables — table attribute lines and full-width tables
- Math — KaTeX and passthrough configuration
- Print — per-chapter and whole-book print
6 - Image albums with Expo
Expo displays image collections as albums. A sidebar groups the albums. The main area shows the images in the selected album. Each image opens in a viewer.
Expo is included in OINK v1.3.0.
Open the example albums to try the controls. Use the Gallery component for an image grid inside a text page.
Create an album
Use one directory for each album. Put the images in that directory’s images/
folder. One index.md describes the album. Filenames supply the default image titles.
Expo does not require a Markdown or YAML file for each image.
-
Create the section entry:
content/photos/_index.md -
Create a topic entry for each group of albums:
content/photos/nature/_index.md -
Create the album page:
content/photos/nature/field-notes/index.md -
Put the images in the album’s
images/folder.
The section lists its child topics and albums. The sidebar follows the same content tree. On narrow screens, open the navigation drawer to select an album. The album body is optional. If supplied, it appears above the images.
Split large collections into separate albums. Expo has no automatic image pagination. A section card uses the first sorted image as its cover. A topic without images uses the first available image from its descendant albums. The cover fills a 4:3 frame and can crop the preview.
Add image metadata
Add a resources entry to the album front matter when an image needs a title,
description, credit, or fixed position. The src path is relative to the album
directory.
| Field | Use |
|---|---|
title |
Image title. If omitted, Expo derives a title from the filename |
params.alt |
Text that describes the image. If omitted or empty, it uses the title |
params.caption |
Plain-text description |
params.byline |
Plain-text credit |
params.weight |
Numeric image order. Lower values come first. The default is 0 |
params.id |
Stable image ID within the album |
params.original |
Optional path to another image in the same album bundle |
Images with equal weights keep the resource name order. To set a complete order, give each image a weight. Images without a weight come before positive weights.
Use ASCII letters or digits for the first ID character. The remaining characters can
also include _ and -. Keep IDs unique within an album. The example creates
/photos/nature/field-notes/#img-fern. This link stays valid after a filename
change if the album URL and explicit ID stay the same. Without an explicit ID,
Expo uses a filename hash. Renaming that file changes the link.
To use a separate original, put it in originals/ and set
params.original: originals/fern.jpg. Keep the preview and original at the same
aspect ratio. Keep originals outside the expo.images pattern to avoid duplicate
entries. Expo reads bundled images; it does not fetch remote files for an album.
Set the defaults
Set site defaults in hugo.yml:
| Key | Allowed value | Built-in default |
|---|---|---|
images |
A pattern for image resources in the album bundle | images/* |
mode |
wall, cards, or seamless |
wall |
size |
An integer from 160 to 360, in CSS pixels |
240 |
Use a top-level expo block in album front matter to replace the site block:
This override replaces the whole block. Omitted fields use built-in defaults,
not values from the site block. A section can supply the block through cascade.
The size is a layout target, not a fixed width and height for every image.
The browser saves the reader’s layout and size choices for the same site origin. These choices take precedence over author defaults. They remain in use after a reload, an album change, or an appearance change. If browser storage is unavailable, Expo uses the author defaults when the page loads.
Select a layout
| Mode | Display |
|---|---|
wall |
Rows of image tiles with 6 CSS pixels between them |
cards |
Columns of cards with visible titles, descriptions, and credits |
seamless |
Rows of image tiles with no gaps between them |
The toolbar has three layout icons, a play/pause button, and an image-size slider. On devices with a mouse, Wall and Seamless show captions on hover or keyboard focus. Images with extreme proportions can have space inside their tiles. The album tiles contain the whole image.
GIFs play by default. Select Pause to show still previews. If the system requests reduced motion, Expo starts with still previews. Select Play to start them. The play button is disabled when the album has no GIFs. Images load as they approach the visible area; large GIF files still require their full transfer size.
Use the image viewer
Select an image to open the viewer. A small image starts at its original size. A large image shrinks until both dimensions fit the available image area.
| Control | Action |
|---|---|
| Reset | Restore the initial size and center the image |
| Expand to fit | Enlarge or shrink the image until its limiting edge fits the image area |
| Zoom out / Zoom in | Divide or multiply the current scale by 1.25 |
| Open original | Open the original image file in a new tab |
| Locate in album | Close the viewer and move to this image in the album |
| Previous / Next | Show the adjacent image in the same album |
| Close | Close the viewer and restore focus to an image link |
Expand to fit keeps the whole image visible. It does not switch the browser to fullscreen. Manual zoom can make the image larger than the viewing area. Hold the left mouse button and drag to move the enlarged image. Movement stops at the image bounds. On a touch screen, an enlarged image uses native scrolling. When the image fits, swipe horizontally with one finger to change images; pinching keeps native browser behavior. Double-click alternates between the initial fit and a closer view: a reduced image opens at 100% under the pointer, while an image already at its original size expands to fit.
Changing images resets the scale and position. Previous and Next stop at the ends of the album. The percentage uses CSS pixels: at 100%, one source pixel occupies one CSS pixel.
Use keyboard shortcuts
These shortcuts work while the viewer is open. They take precedence over the page’s single-key navigation. They do not handle text input, input method composition, or Ctrl/Command/Alt combinations.
| Key | Action |
|---|---|
| W / A / S / D | Move the enlarged image up / left / down / right |
| Q or H | Previous image |
| E or L | Next image |
| J or − | Zoom out |
| K or + | Zoom in |
| R or 0 | Reset the size and position |
| F | Expand to fit |
| Escape | Close the viewer |
WASD moves the image by 80 CSS pixels per press, only along an axis that
overflows. Left and Right arrow keys change images when horizontal scrolling
is unnecessary. When the image is wider than the viewing area, the arrows
retain native scrolling. The keyboard_nav setting controls page shortcuts;
it does not disable the viewer controls.
Use the site appearance
Expo uses Paper, Slate, Ink, and Terminal with the site’s light or dark mode. Select these options in the shared navigation. The album body has its image toolbar and no article action menu.
To expose all four presets and keep the top navbar visible, use:
Expo uses the full available page width by default and has no right-hand outline.
Set page_width in page front matter if the album needs a narrower body. If your
site overrides params.ui.shell_types, include expo to retain its sidebar.
Translate and export an album
Add index.zh.md beside index.md for a Chinese album. Add _index.zh.md for
each translated section. Both languages can share the image files. Translate
the title, description, and resource metadata in each page. Keep image IDs the
same when they refer to the same image.
HTML works without JavaScript: image links open the original files, and captions remain visible. When enabled, Print uses still previews. Markdown and LLMSFULL include image links and metadata. RSS includes static image descriptions. See Print and Agent outputs for output configuration.
Check an album
- Run
hugo --printPathWarningswith a theme version that includes Expo. - Open each album and confirm its image order, titles, and descriptions.
- Test a small image, a wide image, a long image, and a GIF if the album has one.
- Test Reset, Expand to fit, zoom, dragging, keyboard navigation, and Locate in album.
- Check both languages, narrow screens, the four presets, and light/dark mode.
If an album is empty, check its type, bundle structure, and expo.images pattern.
If a default seems to have no effect, check the stored reader choice and the
whole-block override rule. For required behavior and maintainer checks, see the
Expo contract and design decision.
7 - Releases and downloads
OINK stores release metadata in two local places: a page’s front matter
release_url identifies its GitHub release, and data/download/<key>.yaml
records installation instructions. Release cards, asset tables, download blocks,
and index pages derive their links from those records without contacting GitHub
at build time.
Its front matter holds a release_url (OINK v0.4.0), and the card, asset
table and download block below are really rendered. The checksums and asset
filenames are fabricated. The URLs are derived locally from the repository and
tag. Their target files do not exist in any real release.
Do not use these hashes to verify anything.
Components and where the facts come from
| What you want | What renders it | Facts come from |
|---|---|---|
| A version summary card (tag, date, archives, repo) | release-card |
The page’s release_url |
| A checksum asset table | The checksums fence / release-assets |
sha*sum lines in the body |
| A multi-channel download block | download |
data/download/<key>.yaml |
| A chronological release index | layout: releases |
Each page’s release_url, or its title |
The page owns the release facts
One front matter key contains the release record. It is the GitHub release URL for an exact tag:
The URL supplies the owner, project, and tag. The page’s date supplies the
date. An invalid exact-tag GitHub release URL warns and skips the release block.
The 0.5
release map (product / version / repo / tag / date / prev / checksums) and
its string shorthand are removed. A page that still uses either gets a warning
that names release_url.
Put a parameterless shortcode where you want the summary. The call accepts no release facts:
The card shows four locally derived links: the release, both source archives, and the repository. Checksum files belong in the asset table below a note, and comparisons live on GitHub.
The release index page
A section can switch to the release index layout. It lists every regular page in the section, newest first by page date. Within one day, the tag’s version breaks ties. It uses SemVer precedence with a deterministic fallback for non-SemVer tags:
If release_url parses, the entry shows project tag, such as oink v0.4.0,
above the page description. A page without that URL keeps its own title. A
plain note between releases is therefore an ordinary entry and causes no warning. The 0.5
release_products filter and release_group_by_product grouping are gone;
Using either warns.
This site’s Releases currently uses the ordinary blog list.
Switch to layout: releases when a strict chronology is wanted.
Checksum assets
The checksums fence is the native form of a checksum table, holding the
verbatim output of a sha*sum command:
| File | Checksum |
|---|---|
| oink-0.4.0-linux-amd64.tar.gz Linuxamd64SHA-256 | 1e2f4c8a9d05b7361f8ac25d0e7b4913a6c8df215047eb9c3a1d6b8250f9e7c4 |
| oink-0.4.0-darwin-arm64.tar.gz macOSarm64SHA-256 | 7b3d9e0c145a8f26d0b7e93c48156aa2f0d9c7b31e846a5029df1b6c7a3e8250 |
Only two line shapes are accepted: <hex><two spaces><filename> and
<hex><space>*<filename>. Blank lines and lines starting with # are ignored.
The hash length determines the algorithm (MD5 / SHA-1 / SHA-256 / SHA-512), and
each block holds a single algorithm. Malformed lines log a warning with the
line number and are skipped. Each filename must be a single path segment;
package type, OS, and architecture badges are inferred from the filename when
recognized.
If the page has release_url front matter, the base for asset links is derived
as https://github.com/<repo>/releases/download/<tag>/. A page without release
facts must set base= explicitly. Having both is an error.
release-assets is the shortcode form of the same parser and renderer. It adds
one parameter that the fence lacks, src=. Use it for a checksum file stored
as a page resource or global asset. src and inner content are mutually
exclusive. group="auto" groups by platform and architecture:
.rpm
| File | Checksum |
|---|---|
| oink-0.4.0-1.el9.x86_64.rpm Linuxamd64SHA-256 | 5a0c7d1e93b4826f0ad35c9e17b6402d8f1c95ae63d70b28c4e19a5f38207db6 |
| oink-0.4.0-1.el9.aarch64.rpm Linuxarm64SHA-256 | c93f16a8d052b7e41ac68d3907b25fe0a41d8c7362b95e0187ac4d63f9520ea8 |
HTML shows a truncated hash. The accessible name and copied text retain the full value. The copy button uses a local runtime loaded on demand. With JavaScript disabled it is still a complete linked table. Print expands the full hash without controls, and Markdown and RSS emit a pipe table of full hashes.
Download channel data
Installation instructions belong to the product rather than one release. Store
them in data/download/<key>.yaml. This site’s real record is
data/download/prd5.yaml:
The record has five top-level fields: version, repo, tag, published,
and channels (any unknown top-level key logs a warning and skips the record).
version may be omitted here and supplied by the site’s params.version
instead.
version, ,- Missing in both places warns and skips the block
repo, ,- Required once a pinned channel has a link or assets
tag, ,- URL-safe characters only
published, ,falsemeans the immutable release does not exist yetchannels, ,- Must be non-empty
Each channel:
id, ,- Unique within the record. Used as the anchor
kind, ,- Decides whether release facts may be interpolated
title, ,- Must resolve to a non-empty value
note, ,- One line of explanation under the channel
icon, ,- For example
fa-solid fa-bolt url, ,- Interpolatable on
pinnedonly steps[], ,- Code steps go through OINK’s enhanced code renderer
checksums, ,pinnedonly. Mutually exclusive withchecksums_srcchecksums_src, ,- Reads the checksum file as a Hugo asset
Two rules:
- Localization resolves by suffix:
<field>_<exact language>→<field>_<base language>→<field>. A Chinese site resolvestitle_zh_cn, thentitle_zh, thentitle. camelCase aliases are not accepted. - Only a pinned channel’s
urlandsteps[].codeinterpolate${version}and${tag}. A rolling channel refuses interpolation, so a stable install command is never bound to one version. Titles and notes never interpolate.
Rendering the download block
download takes exactly one positional parameter, the data key:
Install script
The rolling channel deliberately contains no version interpolation.
Source archive
Release assets
| File | Checksum |
|---|---|
| oink-0.4.0.tar.gz SHA-256 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
HTML renders a row of anchor chips and one section per channel. Code steps reuse the enhanced code block and its on-demand copy runtime. A checksum channel reuses the asset table above. Print statically expands the same content, Markdown emits the titles, source fences and full hashes, and RSS omits the component.
Before you create the tag and upload assets, mark the record unpublished:
Rolling channels keep working. Pinned channels become an unclickable “pending release” state, omit the pinned commands, and disable asset links and copy controls. After the tag and assets resolve, change the publication state. Do not write a guessed link in the prose.
The same record can supply a landing page’s download section. No second version
model is required. See
Home and landing pages.
How this relates to blog release notes
The two have different jobs:
- A release note in the blog (this site keeps them in
content/blog/release/) explains what changed, how to upgrade, and what breaks. Its front matter carriesrelease_url, and arelease-cardcan sit at the top. For writing instructions, see Blog posts. - Download data identifies the channel, command, and hash. It is separate from the version number. An upgrade changes one place.
For a release, follow this order: update version in data/download/<key>.yaml → write a
new content/blog/release/<version>.md with its release_url → set
published to true after the tag and assets are in place.
Verify
- Build with visible diagnostics:
hugo --printPathWarnings. A malformed hash line, mixed algorithms, a missingbaseand a misspelled channel field all produce warnings that need review. - On the page: the card’s tag and date match the repository, and every asset row opens a real download URL.
- Check hashes against the actual artifacts manually. The component only displays them. It verifies nothing.
- Confirm the hashes are complete in non-HTML output:
- Test with
published: falsefirst. Set it totrueonly after the tag and assets exist. Test each language and a subpath deployment.
Related
- Blog posts — where release notes live and how they are ordered
- Code Blocks — code rendering and copying inside download steps
- Home and landing pages — the landing
downloadsection - Configuration —
params.versionand the related site parameters - Upgrade — how a consuming site tracks theme versions
8 - API reference pages
An API reference page is one OpenAPI specification plus one shortcode. Choose Swagger UI when readers need to try requests, or Redoc for browsing endpoint descriptions and schemas. Both runtimes ship with the theme and load only on pages that use them in HTML output, without a CDN. Swagger UI’s online validator is disabled. Remote specifications and API requests still contact their configured hosts.
Put the specification file under static/. Create a page with the shortcode.
If the page needs the dedicated shell, change its type to swagger.
Where the specification file goes
Put the specification under static/. Hugo publishes it unchanged at the site
root. Both shortcodes then receive a URL that the browser can fetch:
where the specification lives
- static/
- openapi/
- docs-demo.yamlpublished as /openapi/docs-demo.yaml
- openapi/
- content/
- docs/
- write/
- openapi.mdthis page
- write/
- docs/
Do not put the specification beside the page. Both shortcodes treat a local
value as a path under static/. Neither resolves page resources. A .yaml
file beside a content page is a page resource. A shortcode reference to its
name does not publish it. The browser therefore receives a 404.
Both shortcodes accept a remote specification starting https://…. This
creates a network dependency and exposes the reader’s metadata to that host. Intranet deployments and sites with a CSP should use a same-origin
specification. Only http and https are accepted. Any other scheme, a
protocol-relative //host, or an empty value warns. The shortcode then renders
nothing.
To try the examples, download docs-demo.yaml and save
it as static/openapi/docs-demo.yaml in your site. It describes a demonstration
cluster-management API with no reachable server behind it.
Swagger UI
swagger has one named parameter, src, whose value is a URL from the site
root. It passes through the theme’s URL validation, so a subpath deployment
resolves correctly:
In your local preview, this displays expandable API operations, request
parameters and response schemas. “Try it out” sends requests to the
specification’s servers address. The sample has no working backend.
This page shows Swagger UI source and a live Redoc example below. Both widgets have known accessibility limitations. See Limits.
Redoc
redoc takes exactly one positional parameter, the specification path. A
second parameter warns and the shortcode renders nothing.
OpenAPI specification — https://oink.pgsty.com/openapi/docs-demo.yaml
An http or https URL remains remote. Any other accepted value is a path
under static/. Leading and non-leading slash forms are equivalent. For
example, openapi/docs-demo.yaml and /openapi/docs-demo.yaml both become
https://example.com/preview/openapi/docs-demo.yaml when the site baseURL is
https://example.com/preview/. Unlike swagger, Redoc receives this absolute
URL based on baseURL.
The theme pins five attributes — hide-hostname, hide-logo,
suppress-warnings, lazy-rendering, native-scrollbars — and hides the
Redocly brand mark with CSS. Redoc’s remaining attributes are not exposed to
authors. If a site needs them, override
layouts/_shortcodes/redoc.html.
The dedicated page shell
API reference pages are often wide and long. Use the swagger page type for
this layout:
swagger is one of the theme’s default shell types (params.ui.shell_types
defaults to [docs, book, blog, swagger], and a site that overrides the list
needs to keep it). It differs from the docs shell in exactly two ways. It
adds a td-swagger class to <body> for styling hooks. It omits the version banner.
Sidebar, table of contents, breadcrumbs, pager and page end all behave normally.
Shells and page width are covered fully in Layouts and page types.
Output
| Output | What appears |
|---|---|
| HTML | The full interactive Swagger UI / Redoc. Only HTML loads the runtime, on demand from local files without a CDN |
| A labeled static link showing the specification’s address. Neither runtime loads | |
| Markdown | A plain Markdown link, [OpenAPI specification](/openapi/example.yaml). It does not become an endpoint list |
| RSS | The same plain link |
Outside HTML, the API reference contains only a link to the specification. To include endpoint information in print or agent output, describe key endpoints in prose on the same page. Body text outside the shortcode remains intact in all four outputs.
Limits
- Both components derive their container ID from the page address and the shortcode’s ordinal, so several on one page never collide.
- The two can coexist on one page, but the page becomes long and its HTML output loads both runtimes. Pick one for a production site.
- Both embedded third-party widgets have upstream accessibility limitations: Swagger UI renders unnamed server controls and scrollable regions without keyboard access, and Redoc’s operation descriptions fall below AA contrast ratios. Evaluate these trade-offs against your site’s accessibility requirements, or document key endpoints directly in Markdown prose when strict conformance is required.
redocaccepts no attribute parameter. A second positional argument warns and the shortcode renders nothing.- A local
redocpath starts understatic/. A leading/is optional. Page resources are not resolved. - The browser must be able to fetch the specification. Put it in
static/. After a build, confirm that the file exists underpublic/. - There is no mock server. Swagger UI’s “Try it out” sends a real request to the address in
servers. The sample specification’s address is unreachable.
Verify
- Build with visible diagnostics:
hugo --printPathWarnings. - The specification really was published:
ls public/openapi/docs-demo.yaml, or openhttp://localhost:1313/openapi/docs-demo.yaml. - Expand endpoints on the page and confirm that their schemas appear. The browser console must show no 404 or cross-origin error.
- Disconnect from the external network while keeping the local preview server reachable, then reload. Local runtimes and a same-origin specification should still appear.
Related
- Writing pages — page front matter and body basics
- Layouts and page types —
shell_types, page width and the sidebar - AI-agent support — why a component that is interactive only in HTML needs prose beside it
- Code Blocks — the lighter alternative of request / response examples instead of a whole UI