Use OINK Starter and establish a local preview before customizing.
This is the multi-page printable view of this section. .
Components
- 1: Callouts
- 2: Images
- 3: Code Blocks
- 4: Tabs
- 5: Tables
- 6: Fields
- 7: Steps
- 8: Cards
- 9: FileTree
- 10: Math
- 11: Mermaid
- 12: Component presentation
- 13: PlantUML
- 14: Markmap
- 15: Draw.io
- 16: ECharts
- 17: Infographic
- 18: Gallery
- 19: Badge
- 20: Kbd
- 21: Includes
- 22: Asciinema
Use this section to write components in Markdown. Each page starts with the shortest example, then gives more detailed examples. The page also gives the output matrix, parameter table, and limits. Use the cheatsheet below for a quick syntax reference.
Two forms
The native form uses Markdown blockquotes, lists, tables, images, or fences, followed by one {…} attribute line.
This form stays readable on GitHub and in Markdown editors. Markdown output preserves the source instead of rendered HTML.
Use a shortcode for features that the native form cannot express. Examples include tabs in prose and parameter tables with block descriptions. Cards with icons and badges, and terminal recordings, also need shortcodes. Follow these five rules:
- Write every shortcode as
{{</* name */>}}. Only{{%/* steps */%}}uses the%delimiter because its body is page-level Markdown. - Use nested names (
tab,card,field) only inside their parent. - Invalid author parameters never fail silently. Ordinary previews warn, identify the source position, and use the documented fallback or omit unsafe content. Review the warning and rendered fallback before publication.
- Public string parameters, such as captions, labels, and titles, are plain text. They are not parsed as Markdown.
Only bodies are Markdown:
tab,cardandfieldbodies, files loaded byinclude, and Bookfig/tbl/egbodies. - Components that a page does not use load no runtime. HTML references only the stable capability chunks that the page needs. Print, Markdown, and RSS load no interactive runtime.
Site prerequisites
Components need three Goldmark settings. OINK Starter configures these settings. If you start from scratch, copy this snippet:
renderer.unsafe: truekeeps raw HTML in content. Goldmark drops it by default. Without this setting, HTML inside component bodies disappears.parser.attribute.block: trueenables attribute lines. Without it,{.steps}and{caption="…"}appear as text.parser.wrapStandAloneImageWithinParagraph: falseprevents<p>wrappers around standalone images. This permits captioned figures and attribute lines after images.
Some components need other settings. Mathematics needs Goldmark passthrough. Draw.io needs an explicitly configured editor service. Each component page explains its requirements. Configuration lists all configuration keys.
OINK 1.4.0 renders PlantUML locally when enabled without an endpoint, using two bundled scripts. An explicit endpoint keeps server mode; see the PlantUML guide for both modes.
Cheatsheet
The Form column uses three labels. Native means Markdown syntax plus an attribute line.
Fence means a fenced block with a language tag. Shortcode means {{</* … */>}}.
The Runtime column shows whether the component loads JavaScript on the page.
| Component | In one line | Shortest form | Form | Runtime |
|---|---|---|---|---|
| Callouts | Separate prerequisites, warnings and asides from the prose | > [!NOTE] |
native | none |
| Images | Captions, sizing, zoom, numbering and build-time processing |  |
native | site switch |
| Code Blocks | Highlighting, titles, copy, folding, linkable lines | ```sh |
fence | per page |
| Tabs | One thing, several platforms or languages | attribute {tab="Linux"} |
native + shortcode | per page |
| Tables | Plain tables plus full-width, matrix, caption and numbering | {.full-width} |
native | tabs or .expand only |
| Fields | Parameter lists with type / required / default chips | {.fields meta="type default"} |
native + shortcode | none |
| Steps | A procedure with an order | {.steps} |
native + shortcode | none |
| Cards | A set of parallel destinations | {.cards} |
native + shortcode | none |
| FileTree | Directory structure with an aligned comment column | ```filetree |
fence | per page |
| Math | KaTeX inline and display formulas | $$ … $$ |
native | none |
| Mermaid | Flowcharts, sequence diagrams, Gantt charts | ```mermaid |
fence | per page |
| PlantUML | UML diagrams; local rendering in OINK 1.4.0 | ```plantuml |
fence | site switch |
| Markmap | A Markdown outline becomes a mind map | ```markmap |
fence | site switch |
| Draw.io | Diagrams that stay editable; needs a server |  |
native | site switch |
| ECharts | Declarative statistical charts | ```echarts |
fence | per page |
| Infographic | AntV infographics | ```infographic |
fence | per page |
| Gallery | A set of images sharing one zoom dialog | ```gallery |
fence | site switch |
| Badge | Inline status markers | {{</* badge text="Beta" */>}} |
shortcode | none |
| Kbd | Key names and chords | {{</* kbd "Ctrl" "K" */>}} |
shortcode | none |
| Includes | Pull in files, print site parameters, drop build-time notes | {{</* include file="parts/x.md" */>}} |
shortcode | none |
| Asciinema | Terminal recordings | {{</* asciinema file="images/x.cast" */>}} |
shortcode | per page |
Four notes on the Runtime column:
- A code block loads
code-block.jsonly if a block on the page has a copy or fold control. A file tree loadsfiletree.jsonly if it has a comment column. This runtime lets readers drag the splitter. - Images and galleries share one zoom dialog runtime. It needs site-level
ui.image_zoomand at least one eligible image on the page. - KaTeX renders mathematics to HTML and MathML at build time. The page loads a KaTeX stylesheet and fonts, but no script.
- Draw.io loads only on pages whose rendered content has PNG or SVG candidates. It inspects each distinct image URL once.
Every component defines its behavior in four outputs: HTML, print, Markdown, and RSS. See Output on each component page.
1 - Callouts
> [!NOTE] blockquotes without shortcodes.A callout is a GitHub / Obsidian style blockquote. Put > [!TYPE] on the first line and the body below it.
Use callouts to separate prerequisites, warnings, and asides from prose. If a prose sentence is sufficient, a callout is unnecessary.
Shortest form
Hugo Modules need Go on the machine; an offline archive does not.
If you omit the title, the callout uses the localized type name: “Note” in English or 「注意」 in Chinese. GitHub displays the source as a GitHub callout. Other Markdown readers display a plain blockquote. All content remains available.
Ten types
The first five types match GitHub. OINK adds five semantic types. Each type has a default icon and accent color.
hugo server -D previews drafts.
The floor is Hugo Extended 0.168.0; anything older fails the build outright.
hugo --cleanDestinationDir empties public/.
The first build after deleting resources/_gen is much slower.
Build passed with reviewed warnings — ship it.
Never commit go.work.
Should the site have comments? See enabling comments.
pgsty.com is a documentation site built from callouts and tables alone.
Documentation is a love letter that you write to your future self.
Type names are case-insensitive.
Custom title
Text after the marker on the same line becomes the title. It accepts inline Markdown, including code, bold text, and links.
public/Check that baseURL points at the production domain before a production
build, or every absolute link will be wrong.
Body content
The body uses page-level Markdown. It can contain lists, fenced code, tables, images, and nested callouts.
Start every line with >, including fence lines.
- Clone:
git clone https://github.com/pgsty/oink-starter my-docs - Enter the directory and preview:
- Open http://localhost:1313/
| Port | Purpose |
|---|---|
| 1313 | Hugo development server |
Collapsing
A - after the type makes the callout initially closed. A + makes it initially open.
Both use native <details> and load no JavaScript. Use them for full command output, alternatives, or background information that can remain hidden initially.
Hugo downloads themes through Go’s module system (hugo mod get). A submodule
or an offline archive works without Go installed.
The closed state is not remembered; a reload returns to the default.
The neutral disclosure, DETAILS
[!DETAILS] is a disclosure without a semantic color. It is closed by default; [!DETAILS]+ is open.
Use it for long output, complete configuration files, or other content that must be collapsible.
hugo version outputCustom icon
To replace the default icon, put {icon="fa-solid fa-xxx"} after the blockquote. Use one Font Awesome class pair.
The attribute line must immediately follow the blockquote, with no blank line between them.
Pigsty v4 installs PostgreSQL 18 by default.
Nesting
To nest callouts, add one > per level. Callouts can also appear inside list items or steps.
One nesting level is sufficient.
A theme version bump can change how a page renders.
git tag pre-upgrade is enough — rolling back is git checkout pre-upgrade.
Unknown types and common slips
Unknown type names do not fail the build or remove content. The block renders as an ordinary blockquote with its [!TYPE] marker visible.
[!NOTICE] Not a valid type
The marker stays on the page to tell you so.
Other common problems:
- Formatters such as Prettier can merge titles into the body. Keep an empty
>line below the title to prevent this. - Formatters can move attribute lines. Wrap marker lines such as
{icon=…}in<!-- prettier-ignore-start -->/<!-- prettier-ignore-end -->. style,onclick, and unsupported attributes warn and are ignored. The attribute line accepts onlyiconandclass. See the table below.
Output
| Output | Shape |
|---|---|
| HTML | Static types are <div class="td-callout" role="note">; collapsible types are a native <details> + <summary> |
All static and expanded; disclosures carry a data-td-callout-collapsible marker |
|
| Markdown | The source blockquote is preserved, [!TYPE] marker and title included |
| RSS | Same as print — static and expanded |
Callouts load no script.
Parameter reference
The marker line > [!TYPE]± Title:
TYPE, ,NOTETIPIMPORTANTWARNINGCAUTIONSUCCESSDANGERQUESTIONEXAMPLEQUOTEDETAILS; case-insensitive; an unknown value renders as a plain blockquote±, ,-collapses closed,+collapses open; bareDETAILSis closedTitle, ,- On the same line as the marker
The attribute line {…}, immediately after the blockquote:
icon, ,- For example
fa-solid fa-database;DETAILShas no default icon class, ,- Passed through verbatim for site CSS
style, on*, and other keys warn and are ignored.
Limits
- Colors cannot be customized. The type sets the color. If you need a new meaning, choose the nearest type and write a title.
- The collapsed state is not saved.
- Callouts work inside
{.steps}list items and{{%/* steps */%}}steps. See Steps. Start every blockquote line with>and align it with the list item’s indentation.
Related
- Steps — callouts inside a procedure
- Tabs — the same note split per platform
- Writing pages — when to use a callout and when to use prose
2 - Images
Write images with Markdown’s  syntax.
For an image in its own paragraph, add a {…} attribute line to enable captions, zoom, numbering, or Hugo processing.
The theme has no image shortcode.
Shortest form

This image is in the page’s directory, which forms a page bundle.
The theme reads its intrinsic dimensions and writes width/height to prevent layout changes during loading. All images use lazy loading.
You should always write alternative text for screen readers and search engines. Empty alt text marks a decorative image, which is excluded from zoom.
Where images come from
Sources resolve in this order. Use the corresponding path form for each location:
| Placement | How it is written | Suited to |
|---|---|---|
Beside the page (a bundle: index.md plus the image) |
 |
A screenshot only this page uses; it travels with the page and is shared by translations |
Current section bundle (_index.md and its resources) |
 |
Images belonging to a section; use the resource path relative to that section |
Global resource assets/images/… |
 |
Images several pages share, especially ones needing processing (resize / crop) |
Static directory static/images/… |
 |
Large images and downloads that need no processing; supply width/height where the theme cannot measure them |
| Remote URL |  |
Rare: nothing is downloaded at build time and nothing can be processed |
The theme resolves relative paths as page resources, current-section resources, then global resources. If no resource matches, it emits a static path. It does not check whether static paths or remote URLs exist. If image processing cannot find a processable resource, ordinary previews warn and preserve the unprocessed image. Review the warning and rendered fallback before publication.
Markdown alternative text takes precedence over resource metadata, including explicitly empty alt text for decorative images.
Resource params.alt must be a string. Invalid metadata warns and is ignored, preserving the authored alt text.
Review the warning and rendered fallback before publication.
Inline versus block
An image within a text line is inline. It renders as one <img> and accepts no attributes.
An image in its own paragraph is a block image and accepts an attribute line.
This image
is inside a sentence, so it is inline.

Inline images display at their intrinsic dimensions: 50×32 in this example.
An inline SVG without intrinsic dimensions fills the container width. Use a block image with explicit width/height for SVG.
Block images need markup.goldmark.parser.wrapStandAloneImageWithinParagraph: false.
This site has that setting. See Configuration.
Without it, Goldmark wraps standalone images in <p> and treats attribute lines as prose.
Captions
caption="…" creates a <figure> with a <figcaption>. Captions are plain text and are not parsed as Markdown.

A Markdown "title" is a hover tooltip. It never becomes a caption.
Size
width/height take positive integers and override the resource dimensions.
For static or remote images, they reserve space to prevent layout changes. They can also display a large image at a smaller size.
The browser scales the image. The file stays unchanged.

Processed images
Hugo can process page and global resources at build time. Provide both command and options.
Commands are Fit, Resize, Fill, or Crop. Options use Hugo’s image-processing syntax.
The rendered src points to the derivative. With zoom enabled, the dialog opens the original.


Static paths, remote URLs, and SVG do not support processing.
Using command for these sources warns and preserves the unprocessed image.
Hugo image processing documents anchors, quality, and format conversion, such as 300x150 webp q80.
Linked images
Two forms, for different purposes:
- No caption, and the image itself is the link: wrap it in a Markdown link,
[](href). - A captioned figure that is clickable as a whole: add
link="…"to the attribute line (which requirescaptionornum).

Linked images never zoom. Using link= without a caption warns and removes the link, recommending [](…).
Numbered figures
For books or long manuals, add num to the attribute line, with an optional #id.
The author writes the number as a string, such as 2-1 or 3.4. The theme never counts automatically.
The caption receives a localized “Figure 2-1” prefix. #id defaults to fig-<num>.
Reference it with [Figure 2-1](#fig-2-1) or xref. See Books for the whole-book figure list.

See Figure 2-1.
A numbered figure can be a processed image at the same time (num plus
command), and can carry a link.
Zoom
Image zoom is off by default. When enabled, block images, figures, and gallery images with alt text become clickable buttons.
They open the full image in a native <dialog>. Esc closes it and restores the previous focus.
This page enables zoom in front matter, so every image above is clickable.
Since OINK 1.1, the button’s accessible name includes the preview action and image description.
Copied articles receive no helper text. Copied HTML keeps images and authored captions for rich-text editors.
In v1.0.0, a hidden preview label can appear after pasting. Until you upgrade, use image_zoom: false and rebuild to avoid it.
Inline images, decorative images with empty alt text, linked images, and images with data-no-zoom never zoom.
The runtime loads only if the page has an eligible image. Print, Markdown, and RSS have no dialog.

Light and dark images
The theme has no parameter to switch images by color scheme.
If you need two images, give each a class. Use [data-bs-theme="dark"] in site CSS to display the image for each scheme:
Replace sidebar-light.webp and sidebar-dark.webp with your images.
The theme sets data-bs-theme on html. These selectors display only the matching image.
class passes through for site CSS.
Output
| Output | What appears |
|---|---|
| HTML | Inline <img>; block <img class="td-image">; with a caption or number, <figure class="td-figure"> plus <figcaption>; a zoom candidate carries data-td-image-zoom |
| As HTML, with the zoom controls removed | |
| Markdown |  and the attribute line as they stand |
| RSS | The image src becomes absolute; no zoom |
Parameter reference
The attribute line {…} (the line immediately after a block image):
caption, ,- Its presence makes a figure; not parsed as Markdown
#id, ,[A-Za-z][A-Za-z0-9_.:-]*; the anchor and the Book target IDnum, ,[0-9A-Za-z.-]+; registers a Book figure target and prefixes the caption with “Figure N.”width/height, ,- Overrides the size; static and remote images use it to avoid layout shift
command, ,Fit,Resize,Fill,Crop; must accompanyoptions; page and global resources onlyoptions, ,- Hugo image processing options such as
600x300,300x150 Left,800x webp q80 link, ,- Wraps the figure in a link; requires
captionornum; a linked image does not zoom class, ,- Passed through for the site’s CSS
data-*/aria-*, ,- Passed through
style, on*, alt, title, src, and unsupported attribute-line keys warn and are ignored.
Write alt, title, and src in the Markdown image itself.
Limits
- Captions do not support Markdown. Public string parameters are plain text. Put detailed explanations in a paragraph below the image.
titleis not a caption. Thecinis a hover tooltip.- Only resources support processing. Move images that need processing from
static/to the page bundle orassets/. - Remote images are never downloaded at build time.
- Zoom has no drag, pan, or previous / next controls. Use a gallery for related images.
Related
- Gallery — a set of images sharing one zoom dialog
- Books — the list of figures and
xrefcross-references - Brand and appearance — where the site logo and favicon go
- Cards — images on cards
3 - Code Blocks
A code block uses an ordinary Markdown fence. Hugo’s embedded Chroma highlighter runs at build time. The browser has no highlighter.
Use code blocks for commands, configuration snippets, and source code.
The {…} attributes on the fence’s info line control the title bar, copy behavior, line numbers, and line anchors.
Diagram fences such as mermaid, echarts, and filetree use their own render hooks.
Optional presentation
A one-line fence with {class="td-code-command"} becomes a compact command strip with a separate copy column. OINK 1.4.0 supports this variant; see examples and fallback rules. Multiline, numbered, or collapsed blocks warn and retain regular presentation.
Shortest form
A fence without attributes still has the complete shell and a copy button. Without a title, there is no empty title bar.
The copy button appears at the top right on hover or when focus enters the block. It is always visible on touch devices.
The shell does not display the language. It stores the lexer name in data-language for stylesheets and tests.
The language tag is Chroma’s lexer name. A diff fence displays a patch with Chroma’s styles for added and removed lines.
It needs no additional component:
Filename titles
title adds a visible title bar, usually containing a filename or path. It also sets the block’s accessible name.
filename is a historical alias for title. If you provide both, the theme warns and uses filename.
Line numbers, start line and highlighting
lineNos accepts inline or table. Inline numbers share the code column.
Table numbers have a separate column, can be selected separately, and are never copied.
lineNoStart sets the first displayed number. hl_lines marks source lines for emphasis.
It counts from 1 inside the fence, independently of lineNoStart.
lineNos="table" puts numbers in a separate column. The copy button removes line numbers in both modes:
tabWidth sets the number of spaces per tab. The theme passes it and style directly to Chroma.
This site uses class-based Chroma palettes for light and dark modes.
Here, style takes effect only if Hugo is changed to inline style mode.
Wrapping long lines
wrap=true changes only the display. It preserves the source and copied text. Without it, long lines scroll horizontally.
wrap=true cannot be combined with table line numbers. Wrapping misaligns the separate number and code cells.
If you provide both, the theme warns and disables wrapping. It suggests lineNos="inline" or removing wrapping.
Folding long code
collapse=N initially shows N lines, with a “show all N lines” button below them.
The server emits complete code. After measuring line N, the browser clips the visual display.
The complete code remains available without JavaScript, in screen readers, and in print.
If the block is no longer than collapse, no button appears. Wrapping and folding can be combined.
Folding measures the bottom of the Nth source-line node, so it never cuts a wrapped line in half.
What gets copied
By default, the copy button copies the complete source. For console and shell-session lexers, it copies only commands.
It keeps prompted lines but removes prompts and output lines. The example below copies two commands, without $ or output.
To include prompts and output, use copy="all".
On ordinary lexers such as bash or sh, copy="command" warns and uses copy="all", because those lexers cannot distinguish prompts, commands, and output.
For multiline commands, put a continuation prompt, usually >, on each continuation line. Otherwise, those lines are treated as output and excluded.
If a session-lexer block has no prompt, copying fails. The icon shows an error, and an error is logged to the console. The clipboard stays unchanged. The button never falls back to copying everything.
copy=false removes a block’s copy button. Use it for counter-examples that readers should not paste:
To disable copying by default, use params.ui.code_copy: false. An explicit copy fence attribute overrides the default.
See Configuration.
The copy button uses only an icon. Success or failure changes the icon and announces a localized status.
Copied text keeps indentation, blank lines, and Unicode. It removes line numbers and ends with exactly one newline.
Line links and stable IDs
To link “see line 3”, give the fence an explicit id, then enable anchorLineNos=true.
Line numbers become links of the form #<id>-<line>.
Jump to line 4.
Without an id, the theme generates an ID that is unique on the page. It depends on the fence’s position.
Adding another fence above it changes the ID. Only an author-provided id is a permanent link.
IDs must contain no whitespace or control characters. They must not duplicate viewport, tab, panel, title, or line-anchor IDs on the page.
Invalid or duplicate IDs warn and use a generated fallback.
Numbered examples
For books or long manuals, use num and caption to create a numbered Book “example” target.
xref can reference the target, which also appears in the book-wide list of examples.
The author provides the number. The theme never counts examples. id defaults to eg-<num>.
See Example 4-1.
num and caption must appear together. A caption without a number is ignored. A number without a caption is removed with a warning.
num cannot be combined with the tab attribute tab.
For figure, table, and equation numbering and indexing, see publishing books.
A set of fences as tabs
The browser combines consecutive fences with tab into a tab set.
Add group to the first fence to enable shared links, synchronization, and saved selections.
See Tabs for group syntax, URL hashes, synchronization across groups, and tabs in prose.
Common errors
- Showing a shortcode in the docs: a fence does not stop Hugo from parsing, so a
{{< tabs >}}written inside a code block still executes. To display it verbatim, add a comment marker inside each delimiter —{{</* tabs */>}}, and{{%/* steps */%}}for the percent form. Every shortcode shown on this page is written that way. - Fences inside fences: four backticks outside, three inside — every “Source” block on this page does it. Add another backtick when the inner block has fences of its own.
- Attributes go on the info line: a fence’s attributes follow the language on the opening line. Only tables and images take their attributes on the line below. Put them on the next line and you get a visible line of braces.
- Unknown, unsafe, and theme-reserved attributes warn and are ignored; the message lists the allowed names.
- Fences in list items: indent them to line up with the item’s content (three
spaces after
1.), or the fence leaves the list.
Output
| Output | Shape |
|---|---|
| HTML | A <div class="td-code"> shell around Chroma’s .highlight/.chroma; copy and fold buttons ship hidden and appear once the script confirms it can run |
| Complete code; copy, fold and the fade are removed; long blocks may break across pages; the title bar stays | |
| Markdown | The source fence, {…} attributes and all, emitted as written |
| RSS | A static code block with no buttons |
A page with no copy or fold control never loads code-block.js; print, Markdown
and RSS never load it.
Parameter reference
Inside the {…} after the language on the opening line, OINK’s own attributes:
title, ,- The visible title bar (usually a filename) and the accessible name
filename, ,- Historical alias of
title; both together warn and usefilename copy, ,trueisall;commandis allowed only onconsole/shell-sessionwrap, ,- Visual wrapping, source unchanged; mutually exclusive with table line numbers
collapse, ,- Lines shown initially; ignored when the block is shorter
label, ,- Accessible name, not displayed; mutually exclusive with
aria-label id, ,- Stable block ID and line-anchor prefix; no whitespace
tab, ,- Tab label, see Tabs; mutually exclusive with
num group, ,- On the first fence of a set; enables hash / sync / persistence; requires
tab value, ,- Required on every fence of a group, forbidden without one; requires
tab num, ,- Numbered example (Book
eg); must appear withcaption caption, ,- The numbered example’s caption; must appear with
num class, ,- Appended to the
.td-coderoot element data-*/aria-*/role, ,- Passed through to the root element
title, filename, and label give the block an accessible name and role="group".
If you also provide aria-label, aria-labelledby, or role, the theme warns and ignores the conflicting attribute.
These three attributes pass through only if the block has neither a title nor label.
The same line accepts Chroma options. The theme passes them to Hugo unchanged:
lineNos, ,- Line-number style;
tableis mutually exclusive withwrap=true lineNoStart, ,- First displayed number; does not affect how
hl_linescounts hl_lines, ,- For example
"2 4-5", counted over the source lines in the fence anchorLineNos, ,- Line numbers become anchor links prefixed with the block’s
id tabWidth, ,- Spaces a tab expands to
Limits
- The highlighter cannot be replaced. There is no Shiki, Twoslash, browser highlighting, or runnable playground.
For patches, use a
difffence. Chroma’s.gi/.gdstyle added and removed lines. copy="command"supports only session lexers. Other languages warn and copy everything.- Generated IDs are not permanent links. Write
idfor a link that you plan to share. mermaid,math,chem,markmap,plantuml,echarts,infographic,checksums,filetree, andgalleryare not code blocks. Each has its own render hook, without a code shell or copy button.
Related
- Tabs — the full rules for assembling adjacent fences
- Include — pull a real file from the repository in as a code block
- Publishing books — numbered examples, cross references, the list of examples
- Print — what long code looks like on paper
4 - Tabs
{tab=} to adjacent fences or tables to create tabs. Add a group to enable links, synchronization, and saved selections.Use tabs for equivalent alternatives, such as package managers, distributions, YAML / TOML / JSON, or environment variables and configuration keys. Do not use tabs for ordered steps or unrelated content. Readers see only one panel at a time.
The native form uses a tab attribute on adjacent blocks.
Use tabs/tab shortcodes for panels with prose, multiple paragraphs, lists, or callouts.
Both forms share one runtime, one DOM, and the same keyboard behavior.
Shortest form
Write two adjacent fences with tab, separated only by a blank line.
The server emits two complete titled code blocks. After page loading, the runtime combines adjacent blocks of the same kind into tabs. GitHub, print, and browsers without JavaScript display both complete blocks in sequence.
Groups: links, sync and memory
Write group only on the first block. This enables the public URL hash #<group>-<value>, in-page synchronization, and browser persistence.
Every block in the group must have value.
value is the machine identifier, matching ^[a-z0-9][a-z0-9_-]*$. tab is the independent human label.
The pnpm panel uses #pkgmgr-pnpm. Opening this page with that hash selects the panel.
Groups move together
The set below also uses group="pkgmgr". Changing either set’s package manager changes the other.
The selection is saved in localStorage under td-tabs:v1:pkgmgr. It also applies to the same group on other pages.
This set has no yarn panel. If a value is missing, that set keeps its current selection. A set always has a selection.
Initial selection follows this order: URL hash, stored value, shortcode default or first block, then first tab.
Opening with a hash selects the panel without replacing the reader’s stored preference.
Tables can be tabs too
Use the same attributes on table attribute lines to combine adjacent tables into tabs.
| Parameter | Default |
|---|---|
shared_buffers |
25% RAM |
max_connections |
100 |
| Parameter | Default |
|---|---|
shared_buffers |
128MB |
max_connections |
100 |
Fences and tables cannot form one set, even when adjacent. A native tab set contains only fences or only tables. To combine them, use the shortcode form below.
A label and a filename together
A fence can have both tab and title. The tab bar displays the label. The filename title bar remains inside the panel.
A lone block is just a titled block
A block needs an adjacent block of the same kind to form a tab set. A single block keeps its title instead of creating a one-tab bar.
Only blank lines may separate blocks. Prose, headings, or lists between blocks break the set.
HTML comments, commonly <!-- prettier-ignore-end -->, also break it.
A later block with its own group starts a new set. Only the first block in a set may have this attribute.
Tabs around running text
For panels with paragraphs, lists, callouts, or multiple blocks, use tabs/tab shortcodes. Their bodies use full Markdown.
The repository ships .github/workflows/; a push to main builds and publishes.
baseURL has to be the repository’s Pages address.
Connect the repository in the Cloudflare dashboard; the build command is:
default sets the initial panel. It must match a child’s value and requires group.
Without group, value is forbidden. The theme generates tab1, tab2, and later identifiers.
These ungrouped tabs switch locally without changing the URL or storage.
The shortcode form reports mistakes at build time; the attribute form reports them in the browser.
Output
| Output | Shape |
|---|---|
| HTML | <div class="td-tabs"> with role="tablist" buttons and panels; every panel is visible until the runtime takes over |
| Consecutive titled static sections, no tab bar | |
| Markdown | The fence form keeps the source fence, {tab=} included; the shortcode form emits **Label** plus the body |
| RSS | Same as print — stacked titled sections |
Only a page that uses tabs loads tabs.js; print, Markdown and RSS never do.
Parameter reference
Attributes on a fence info line or a table attribute line:
tab, ,- The visible label; on a lone block it is simply that block’s title
group, ,- On the first block of a set; enables hash, in-page sync and persistence; requires
tab value, ,- Required on every block of a group, forbidden without one; requires
tab
The tabs shortcode:
group, ,- As above: hash, sync and persistence
default, ,- The initially selected panel; requires
group label, ,- Accessible name for the tab bar; not displayed
The tab shortcode:
label, , required- The visible label
value, , required- Forbidden without a group, where
tab1,tab2… are generated
In a group, panel IDs use <group>-<value>.
If the same group appears again on one page, later sets receive -2 and -3 suffixes. Deep links still target the first set.
Ungrouped sets have generated IDs. The storage key is td-tabs:v1:<group>.
Clicks or keypresses update the hash through replaceState and write storage. Arriving with a hash only changes the selection.
Left and right arrows follow RTL direction. These keys and Home/End move and activate tabs, while focus stays on the tab.
Limits
- Invalid grouping or composition warns during Hugo builds and uses a safe fallback. The theme removes unusable group/value/default settings, ignores stray content, keeps later duplicates, or omits empty sets. Warnings identify the source position.
- In the attribute form, a sequence without usable
valueloses synchronization and remains local tabs. Grouping never silently creates an identity. - Fences and tables cannot form one set. Use shortcodes to combine prose and code.
- To collapse long output, use
> [!DETAILS]instead of tabs. See Callouts. groupnames are shared site-wide. Selecting pnpm on page A also selects pnpm in the same group on page B. Choose meaningfulgroupnames instead oftabs1.
Related
- Code blocks — the rest of the fence attributes (title, copy, line numbers, folding)
- Tables — the rest of the table attribute line
- Callouts — for folding rather than juxtaposing
- Steps — tabs inside a procedure
5 - Tables
Tables use ordinary GFM pipe syntax. The table render hook wraps each table in a horizontally scrollable region.
The {…} attribute line below selects captions, compatibility matrices, field lists, numbering, or tabs.
Merged cells, sorting, and filtering are unsupported. If you need these features, change the presentation of the data.
Shortest form
Without an attribute line, the result is an ordinary table. The delimiter row controls alignment.
Header cells use th scope="col".
| Component | Port | Purpose |
|---|---|---|
| PostgreSQL | 5432 | Database |
| Pgbouncer | 6432 | Connection pool |
| Patroni | 8008 | High-availability orchestration |
Wide tables scroll themselves
Wide tables scroll within their own region instead of widening the page. Press Tab to focus the region, then use arrow keys to scroll. Its accessible name is the localized “Scrollable table”.
| Cluster | Role | Version | State | Lag | Connections | Size | Backup |
|---|---|---|---|---|---|---|---|
| pg-meta | primary | 18.1 | running | — | 42 | 12 GB | 2026-08-17 |
| pg-test | replica | 18.1 | streaming | 12 ms | 8 | 12 GB | 2026-08-17 |
Captions
{caption="…"} adds a visible <caption>. The caption is plain text and does not number the table.
Its title has balanced padding inside the table frame and aligns with the column labels below it.
| Item | Value |
|---|---|
| Theme version | v0.8.1 |
| Hugo floor | 0.168.0 Extended |
| Licence | Apache-2.0 |
Compatibility matrices
Use {.matrix} for support matrices. The first column becomes a row header with th scope="row".
The header row and first column stay fixed while scrolling. Other cells are centered unless the delimiter row specifies another alignment.
Authors write ✅ and ❌ characters. The theme does not interpret them.
| OS / PG | PG18 | PG17 | PG16 | PG15 | PG14 |
|---|---|---|---|---|---|
| EL 9 | ✅ | ✅ | ✅ | ✅ | ✅ |
| EL 8 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Debian 13 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Ubuntu 24.04 | ✅ | ✅ | ✅ | ✅ | ❌ |
Using the whole canvas
{.full-width} removes the reading-column limit and uses the article’s full width. Use it for many short columns.
| Language | Code | Sidebar | Search | TOC | Status | |
|---|---|---|---|---|---|---|
| 简体中文 | zh |
✅ | ✅ | ✅ | ✅ | Reviewed |
| English | en |
✅ | ✅ | ✅ | ✅ | Reviewed |
Technical wide tables
.wide in OINK 1.4.0The short marker is included in the release. Existing technical-table markup remains supported.
Technical tables containing long configuration keys, environment variables, or
identifiers can produce awkward token breaks and very tall rows when forced into
the reading column. Adding {.wide .expand} to the attribute line opts the
inner table into natural intrinsic sizing (width: max-content), scrolling
horizontally within its wrapper when it exceeds the available space.
| Variable | Required | Default | Configuration key | Description |
|---|---|---|---|---|
HG_PD_GRPC_HOST |
Yes | None | grpc.host |
Advertised gRPC hostname/IP; use container hostnames within a container network. |
HG_PD_INITIAL_STORE_COUNT |
No | 1 |
pd.initial-store-count |
Minimum Store count needed for cluster availability. |
HG_PD_ACTUATOR_EXPOSURE |
No | health,metrics,prometheus |
management.endpoints.web.exposure.include |
Public Actuator endpoint allowlist; * is forbidden. |
Difference from .full-width
.full-widthcontrols the outer canvas: it expands the table container to break out of the reading column into the full width of the article layout. It suits tables with many short columns..widecontrols the inner table sizing: it sets the table to its natural intrinsic width (width: max-content), using horizontal scrolling to accommodate wide content. It suits tables with long technical identifiers.- Both can be combined:
{.full-width .wide}expands the container to the full canvas while allowing the inner table to keep its natural wide measure.
Applicability boundaries
- Explicit opt-in: Ordinary tables keep their existing layout. Only tables
marked
.wideuseoverflow-wrap: break-word,word-break: normal, and a softmax-width: 40chbody-cell bound. Very long tokens may still wrap; the bound is not a fixed column width. - Static outputs: This policy applies only on screen. Print and RSS use
static wrappers and retain their existing layout; Markdown preserves the authored
GFM table and attribute line. The marker has no effect on
.fieldsdefinition lists.
Expand selected tables
.expand in OINK 1.4.0The opt-in reader is included in the release.
Add .expand only to tables that benefit from a larger reading area. A small
expand icon sits at the top-right corner: desktop hover or keyboard focus reveals
it; touch devices keep it visible. Click once to open the table, then use Close
or Escape to return to the same reading position. Text size, links, and selection
stay intact; wide content still scrolls horizontally on small screens.
| Package | Version | Role |
|---|---|---|
pgvector |
0.8.1 |
Vector similarity search |
pg_stat_statements |
1.11 |
Statement statistics |
Goldmark accepts multiple classes: {.wide .expand} and
{class="wide expand"} are equivalent. Enable
markup.goldmark.parser.attribute.block: true and put the attribute line
immediately after the last row, without a blank line.
.wide controls layout; .expand enables the reading action. Either works alone.
You can also combine .expand with .full-width, .matrix, captions, numbering,
or tabs. There is no automatic size threshold or site-wide switch. The existing
.td-table--wide spelling remains compatible with .wide.
Only pages with opted-in tables load the small reader script. Without JavaScript,
a loaded script, or native dialog support, the complete inline table remains
readable without a dead button. Print and RSS keep static tables; Markdown keeps
the author syntax. Browser printing restores an open table to the article first.
Tables whose headers, aria-labelledby, or aria-describedby reference nodes
outside the table stay inline; custom styles depending on article ancestors
should be reviewed in the reader.
Field lists
{.fields} converts a table to a definition list. The first column is the name, the last is the description, and middle columns are metadata.
Use it for configuration keys, command flags, and API fields. See Fields for the complete syntax.
offline_search, ,- Build the local search index
page_width, ,- Width of the reading column
Numbered tables
For books or long manuals, add num, with optional #id and caption.
The theme wraps the table in a <figure> with a localized “Table N.” label and registers it as a Book target.
xref can reference it, and it appears in the book-wide table list.
Authors provide numbers. The theme never counts. id defaults to tbl-<num>.
| Isolation level | Dirty read | Non-repeatable read | Phantom read |
|---|---|---|---|
| Read committed | no | yes | yes |
| Repeatable read | no | no | yes |
| Serializable | no | no | no |
See Table 9-1.
Tables as tabs
Adjacent tables with {tab="…"} form a tab set, using the same rules as adjacent fences.
group on the first table enables URL hashes, synchronization, and saved selections. Each later table needs value.
See Tabs for the complete rules.
| Directory | Contents |
|---|---|
content/ |
Pages |
data/ |
Landing and release data |
| Directory | Contents |
|---|---|
assets/ |
SCSS and image resources |
static/ |
Files copied verbatim |
Output
| Output | Shape |
|---|---|
| HTML | A focusable <div class="td-table-scroll"> around the <table>; matrix and full-width are modifier classes on that wrapper |
| Complete static content with a keyboard-scrollable region in the browser preview; print-media CSS expands the region for paper output | |
| Markdown | The source table and its attribute line, emitted as written |
| RSS | The complete static table |
Ordinary tables load no script; .expand loads its reader only in HTML, and tabbed tables load the tabs runtime.
Parameter reference
The attribute line on the row below the table:
.full-width, ,- Exceed the reading column and use the article canvas
.wide, ,- Sizes the inner table to max-content; suits technical tables with long identifiers
.expand, ,- Add an optional corner action for reading the table in a larger dialog
.matrix, ,- First column as row header, header and first column pinned, other cells centred
.fields, ,- Render as a definition list, see Fields
caption, ,- Visible table caption; on
.fieldsit labels the list meta, ,- Names the meaning of the middle
.fieldscolumns:typerequireddefault-; requires.fields #id, ,[A-Za-z][A-Za-z0-9_.:-]*; lands on the<table>, or on the<figure>for a numbered tablenum, ,[0-9A-Za-z.-]+; registers a Book table target and prefixes the caption with “Table N.”tab/group/value, ,- Adjacent tables become a tab set
class, ,- Left on the
<table>for site CSS data-*/aria-*, ,- Passed through
style, on*, and other keys warn and are ignored.
Limits
.fieldscannot be combined with.matrix,.full-width,.expand, ornum.numandtabare mutually exclusive.group/valuerequiretab, andmetarequires.fields.- The attribute line must immediately follow the table. A blank line makes the braces appear as text.
To prevent formatters moving the line, wrap it in
<!-- prettier-ignore-start -->/<!-- prettier-ignore-end -->. - GFM tables do not support merged cells, sorting, or filtering. Split complex tables with merged headers into two tables or use a matrix.
- Cells cannot contain block content. Use
fields/fieldshortcodes for multiple paragraphs, lists, or fences. .matrixcentering uses CSS. Explicit delimiter-row alignment takes precedence.
Related
- Fields — everything
{.fields}can do - Tabs — adjacent tables as a tab set
- Publishing books — numbered tables, cross references, the list of tables
- Code blocks — where attributes go on the info line instead of the next line
6 - Fields
{.fields} to a table to document configuration keys, command flags, and API fields. Entries adapt to narrow screens and have individual anchors.Fields display named values, metadata, and descriptions as a responsive definition list. Each name has its own line. Small chips beside it show type, required status, and default value. The description starts on the next line. Each entry has an anchor. Use fields for configuration keys, command flags, and API fields. Use a plain table to compare many rows across the same columns. Use steps for sequences of actions.
There are two forms. Use a plain table with {.fields} by default.
Use fields/field shortcodes for descriptions with multiple paragraphs, lists, or code blocks. Both forms display the same entries.
Shortest form
Write a pipe table with at least two columns, then put {.fields} on the next line.
The first column is the name. The last is the description. Middle columns are metadata labeled with their header text.
offline_search, ,- Build the local search index and enable the command palette
offline_search_max_results, ,- Maximum number of search results
page_width, ,- Reading column width:
normalwidefull
Metadata appears as “Header: value”. The theme does not infer meaning from headers. Type is only a label.
The next section explains standard chips. Cells accept inline Markdown, including code, emphasis, and links. Empty middle cells are omitted.
Semantic columns with meta=
meta assigns a role to each middle column, in order: type, required, default, or - for a plain header label.
With this attribute, tables display the same chips as shortcodes.
baseURL, , required- Site address, subpath included
title, , required- Site name, shown in the navbar and the tab
defaultContentLanguage, ,- Default language; decides which language unprefixed paths belong to
The rules:
metashould specify one role per middle column: the total column count minus two. Too many or too few roles warns and ignoresmeta. Review the warning and rendered fallback before publication.- Every nonempty
requiredcell means true. “yes”, “是”, and “✔” all display the untranslatedrequiredchip. Empty cells display nothing. Leave optional fields empty, becausenoand否also mean true. typeanddefaultcells without their own inline markup receive code formatting, as in the shortcode form.- Semantic chips always appear in this order:
type,required,default, regardless of column order.-columns follow in their original order.
Combine - with semantic roles to keep a custom label:
HUGO_MODULE_WORKSPACE, ,- Points at
go.workso the theme resolves from a local checkout HUGO_ENV, ,- Selects production mode; OINK fingerprints CSS/JS assets. Use
--minifyto minify HTML
Labels and container IDs
caption sets the list’s visible label and accessible name. id identifies the outer container for links or styles.
params.ui
image_zoom, ,- Turn image zoom on
featured_image, ,- Article image mode:
none,banner,washorhero
Every entry is linkable
Each entry has a field-<name> anchor. A self-link icon appears beside the name on hover.
For example, page_width in the first table has #field-page_width. Share this link to refer to that entry.
Duplicate names on a page receive -2 and -3 suffixes, as Goldmark does for duplicate headings.
Only HTML generates these anchors. Print and RSS combine pages into one document, where these anchors would collide.
The shortcode form
If a description needs multiple paragraphs, a list, or a code block, use fields/field. A table cell cannot contain these blocks.
Common pig flags
--config, , requiredPath to the configuration file. Relative paths resolve against the working directory.
When
PIG_CONFIGis also set, the command-line flag takes precedence.--log-level, ,Log level, from low to high:
debug: print every remote callinfo: the defaulterror: output only on failure
--dry-run, ,Print what would happen and change nothing:
required=true and default=false are booleans. Do not quote them.
default accepts any scalar. Both default=0 and default="" display their values; the empty string appears as "".
If you omit default, the chip is omitted. Every field needs a nonempty body and must be a direct child of fields.
Which form to use
| Situation | Use |
|---|---|
| One-sentence descriptions that fit in a table cell | table + {.fields} |
| Descriptions with paragraphs, lists or code blocks | the fields/field shortcode |
| Readers comparing many rows across the same columns | a plain table, not a field list |
| Content that is a sequence of actions | Steps |
The table form stays readable on GitHub and remains a table in OINK’s Markdown output. It is therefore the default.
Output
| Output | Shape |
|---|---|
| HTML | <div class="td-fields"> around a semantic <dl>; entries carry #field-<name> anchors and self-links |
| The complete definition list, without entry anchors | |
| Markdown | The table form keeps the source table; the shortcode form emits a bulleted list of “name — type; required; default: value” plus the indented description |
| RSS | The complete static <dl>, without entry anchors |
No script is loaded.
Parameter reference
The table attribute line, on the row below the table:
.fields, ,- Required; renders the table as a field list
meta, ,- Space-separated
typerequireddefault-; one per middle column; semantic roles cannot repeat caption, ,- Visible label and the list’s accessible name
id, ,- ID of the outer container
class, ,- Passed through for site CSS
data-*/aria-*, ,- Passed through
The fields shortcode:
label,- Visible label; the same thing the table’s
captiondoes id,- Container ID; no whitespace, quotes,
<,>or& class/data-*/aria-*,- The same policy as the table attribute line
The field shortcode:
name, , required- The field name
type,- Type label such as
boolean,string[],duration required,trueshows the untranslatedrequiredchip; defaults tofalsedefault,- String / boolean / integer / float;
false,0and""all display
Limits
- The first column must be nonempty and unique within each table. Empty or duplicate names warn and skip the row.
.fieldscannot be combined with.matrix,.full-width, ornum.metarequires a table with.fields.- Table cells cannot contain block content. Use shortcodes for paragraphs, lists, and fences.
requiredanddefaultremain untranslated English API terms in every language. They are contract terms, not interface text.- Fields do not support
kind,since,deprecated,location, per-field links, or nested structures. They do not parse TypeScript or OpenAPI schemas at build time.
Related
- Tables — the rest of the attribute line and the exclusion rules
- Configuration — the full site parameter table, itself a field list
- Front matter — the full front matter table
- Steps — ordered actions do not belong in a field list
7 - Steps
{.steps} to an ordered list for a numbered procedure. Use the steps shortcode when each step needs a table-of-contents heading.Steps display an ordered list with numbered dots and a connecting line. Add a {.steps} marker line to an ordered list.
CSS draws the dots and line. No script loads. Use steps for ordered procedures.
Use plain lists or cards for unordered items.
There are two forms. Use an ordered list with {.steps} by default.
Use {{% steps %}} when each step needs a heading in the table of contents.
Optional presentation
Use {.steps .td-steps-compact} for a short procedure, or steps variant="compact" for the heading form. OINK 1.4.0 supports these opt-in variants; compare the examples. Numbering, nesting, and heading anchors retain their existing meaning.
Shortest form
Write 1. for each item so Markdown counts automatically.
Then you can add, remove, or reorder steps without renumbering. Content always uses three spaces of indentation.
- Install Hugo Extended
- Clone OINK Starter
- Start the local preview
{.steps} must immediately follow the last list line. A blank line makes it display as text with braces.
What goes in a step
List items accept block content: paragraphs, fenced code, callouts, tables, nested lists, and images. Align content with the item’s content column, using three spaces.
-
Clone OINK Starter; it is the small project template for the theme.
-
Start the local server.
NoteThe first build fetches the theme through the Go module proxy, which needs Go on the machine.
-
Replace three things and it is your site.
Where Replace with titleinhugo.ymlyour site name baseURLinhugo.ymlyour domain content/your content
Shortcodes in {{< … >}} form, such as tabs, cards, and badges, also work inside list items.
The {{% … %}} form does not. See Limits.
Splitting one step per platform
If a step differs by platform, put adjacent {tab=} fences inside that list item. They still form a tab set.
-
Install Hugo Extended.
-
Install the dependencies:
EL / RHELDebian / Ubuntu -
Run
hugo serverto preview.
Continuing the numbering
If prose interrupts a procedure, start the next group with its actual step number.
Markdown emits start and continues numbering from that value, up to 40.
- Configure
baseURLand the deployment workflow. - Push to
mainand wait for GitHub Actions to finish.
Steps with headings
For long procedures with linked headings in the table of contents, use {{% steps %}}.
The body uses page-level Markdown without indentation. Each direct child heading is one step.
The three headings below appear in this page’s table of contents.
Install the toolchain
You need Hugo Extended ≥ 0.168.0 and Go.
Run the server
brew install hugo go
sudo apt install hugo golang-go
Publish
Push to main; the workflow the repository ships builds and publishes.
This is the theme’s only {{% … %}} shortcode. The percent form gives its body to Goldmark as page-level Markdown.
This allows headings in the table of contents and container shortcodes such as tabs, cards, and fields inside steps.
It cannot nest inside list items or other percent containers.
Use the same heading level for every step in a procedure. Never nest steps inside another steps container.
Which form to use
| Situation | Use |
|---|---|
| A step is a sentence or two plus a command | ordered list + {.steps} |
| Each step needs a heading, a link and a place in the TOC | {{% steps %}} |
A step must contain a tabs, cards or fields container |
{{% steps %}} |
| The procedure itself has to nest inside another list item | ordered list + {.steps} |
Output
| Output | Shape |
|---|---|
| HTML | The native form is <ol class="steps"> with numbers and rule drawn in CSS; the shortcode form is <div class="td-steps"> plus headings |
| Numbers and content unchanged, the rule stays | |
| Markdown | The source as written: an ordered list plus {.steps}, or headings plus bodies |
| RSS | A static list or titled sections |
Steps load no script. Disabling JavaScript does not change the result.
Parameter reference
OINK 1.4.0 supports the optional variant="compact" on the full form. Follow these conventions:
{.steps},- Required; has no effect on an unordered list
1.,- Let Markdown count; the content indent is always three spaces
,4.(first item)- Emits
<ol start="4">and continues from 4; supported for 2–40 {{% steps %}},- Direct child headings (
##–######) are the steps; the body is not indented
Limits
- Do not put
{{% … %}}inside list items. A percent shortcode’s multiline output truncates the list. To put a container in a step, use the shortcode form for the whole procedure. {{% steps %}}cannot be inside list items or other percent containers.- Put the marker immediately after the list, with no blank line before
{.steps}. With formatters such as Prettier, wrap it in<!-- prettier-ignore-start -->/<!-- prettier-ignore-end -->. {.steps}applies only to ordered lists. A-list has no numbers.- Steps do not collapse, expand, or track progress. There is no “done” state.
Related
- Tabs — commands split per platform
- Callouts — prerequisites and warnings inside a step
- Code blocks — the commands in a step
- Cards — “what next” once the procedure is done
8 - Cards
{.cards} to a link list to create navigation cards. Use the shortcode for icons, badges, or images.Cards provide related links. Each card has a linked title and a sentence. The grid adapts to the container width. Use cards for section landing pages, reading recommendations, or a few related entry points. Use paragraphs for prose and a gallery for image collections.
Optional presentation
Use {.cards .td-cards-list} for a single-column resource list with shared dividers, or cards variant="list" for the full form. OINK 1.4.0 supports these opt-in variants; compare the examples. The default remains a responsive grid.
Shortest form
Add {.cards} to a link list to make a card grid. The link becomes the title.
Text after — becomes the description.
- Get started — Start with OINK Starter, preview locally, then replace the site details with your own.
- Authoring — How pages are organized and which front matter keys exist.
- Customization — Navigation, search, branding, languages.
The whole card is clickable. There is no columns parameter.
The number of columns follows the container width and decreases to one on narrow screens.
Title-only cards
The description is optional. Put one link on each line and {.cards} after the list.
Loose lists and longer descriptions
If a sentence is insufficient, use a loose list. Put the link and description in separate paragraphs, with blank lines between items.
The title appears above the description. {.cards} must immediately follow the last paragraph, with no blank line between them.
-
Every page parameter is defined here exactly once: type, default, accepted values, and the page that explains it.
-
Site parameters grouped by feature, each row linking back to the guide that explains it.
Icons and badges
Link lists do not support icons, badges, images, or descriptions with multiple paragraphs. Use the cards / card shortcode for these features.
icon takes exactly one Font Awesome class pair. badge is plain text.
A release card from release_url and date, plus a checksums block for download assets.
Site-wide shortcuts and focus order.
An invalid Font Awesome class pair warns and is removed in ordinary previews. Review the warning and rendered fallback before publication.
Markdown bodies
A card body uses page-level Markdown, including inline code, emphasis, links, and lists.
Parameters such as title and badge are plain text. They are not parsed as Markdown.
hugo mod get github.com/pgsty/oink. The recommended way; upgrading is one
version line.
No Go installation needed:
git submodule add- the theme lands in
themes/oink
A card without link renders as a bold title and produces no link.
Cards with images
image uses the same resolution order as : page resource → current section resource → global resource in assets/ → static path /images/… → remote URL.
Local resources include their intrinsic size, which prevents layout changes during loading.
With image, provide exactly one alternative-text source. Use image_alt="…" for informative images or decorative=true for decorative images.
If you provide both, the theme warns and keeps the alt text. If you provide neither, it warns and makes the image decorative.
Review the warning and rendered fallback before publication.
Sidebar, article, table of contents — each can be turned off on its own.
A decorative cover: decorative=true emits an empty alt and screen readers skip it.
Card images do not take part in image zoom — the whole card is already a link.
Automatic cards on section pages
A section landing page (_index.md) needs no manual card list. The theme generates cards from each child page’s title, description, and icon.
This site enables section cards globally in hugo.yml:
A section can override this setting in its front matter. Use cascade to apply the setting to the whole subtree:
Automatic and manual cards share the td-content-card styles. Only their data source differs.
Do not manually list child pages on a section page. The list can become inconsistent with the sidebar.
Use manual cards for other sets, such as external links or recommendations from other sections.
Configuration defines these keys.
Which form to use
| What you want | Which form |
|---|---|
| A grid of links with one-sentence descriptions | {.cards} link list |
| Icons, badges, images | cards / card shortcode |
| Lists, code or several paragraphs in the description | cards / card shortcode |
| A card with no link | cards / card shortcode |
| This section’s child pages | nothing at all — section_index: cards |
The native form stays readable as a link list on GitHub. Shortcodes do not. Use the native form when it supports your content.
Output
| Output | Shape |
|---|---|
| HTML | Native form: <ul class="cards">. Shortcode form: <div class="td-content-cards"> with one <article class="td-content-card"> each. Both are pure CSS grids and load no script |
| The native form stacks; the shortcode form collapses to two columns; in both, a card avoids breaking across pages | |
| Markdown | The native form keeps the link list; the shortcode form emits - [Title](link) (badge) — description |
| RSS | The same markup as HTML — a readable list of links without site CSS |
Parameter reference
The native form:
{.cards}, ,- On the line after an unordered list; unordered lists only
First link in an item, ,- The card title and the whole card’s click target
Everything else, ,- The description: after
—in a tight list, its own paragraph in a loose one
card parameters (cards also accepts an optional variant="list"):
title, ,- Required, non-empty. The card title
link, ,- Site path, relative path,
http(s):,mailto:; external links getrel="noopener" icon, ,- For example
fa-solid fa-rocket; a malformed value warns and is dropped badge, ,- A small label beside the title
image, ,- Page resource / global resource / static path / remote URL
image_alt, ,- With
image, exactly one of this anddecorative decorative, ,truemarks a decorative image and emits an empty altBody, ,- The card description
There is no cols, columns, accent, desc, or color parameter.
Unknown parameters warn and are ignored.
Limits
{.cards}supports only unordered lists. It has no effect on ordered lists.{.cards}must immediately follow the list. A blank line or indentation inside a list item silently removes the marker. The build succeeds, but the result stays a list. Check this line first if no card grid appears.- A
cardmust be insidecards. Alone or inside another shortcode, it warns and is skipped. - The grid adapts to its container. Its column count cannot be configured.
Only automatic section cards accept a count, through
params.ui.section_index_columns. - If a description exceeds two lines, use a paragraph or a callout.
Related
- Fields — also has a native form and a shortcode form
- Galleries — a grid of images
- Badges — inline status labels
- Organizing content — sections, weights and landing pages
- Configuration —
section_indexand friends
9 - FileTree
filetree fence. Use indentation for depth, trailing slashes for directories, and aligned comments for explanations.A filetree fence contains a directory listing. Indentation sets depth, a trailing / marks a directory, and text after # is a comment.
Use it to explain the relevant directory structure, with one annotation per entry.
If readers need to copy the exact listing, use an ordinary code block.
Shortest form
- content/
- _index.md
- docs/
- blog/
- hugo.yml
- go.mod
Bullets (-, *, +) are optional and do not change the result.
Entries with children are directories. For entries without children, a trailing / marks a directory.
Adding comments
Text after the first whitespace-preceded # is a comment. Comments appear in an aligned column on the right.
They are plain text, so Markdown appears literally. Use \# for a literal hash.
- content/every page, both languages in one directory
- docs/the documentation tree you are reading
- blog/release notes and articles
- assets/scss/the site's own SCSS, overriding theme variables
- layouts/site-level template overrides, the fewer the better
- static/images/images that need no build-time processing
- hugo.ymlsite configuration: languages, menus, params.ui
At build time, the widest row determines the comment column’s starting position. Each # aligns even if the source does not.
The comment column occupies at least three tenths and at most half of the panel.
Drag the dashed splitter to change the width. Alternatively, focus it with Tab and move it with arrow keys.
Home / End move it to the limits.
By default (wrap=false), long names and comments are truncated with an ellipsis within their columns. Hover to see the full text in title.
Only trees with comments load JavaScript. This script controls the splitter.
truncation in both columns
- runbooks/
- a-deliberately-long-runbook-filename-for-a-failover-drill.mdan equally overlong comment, kept on one line so it has to be clipped inside the comment column
- restart.mdshort
Wrap long comments
Use wrap=true on the filetree fence to show complete comments in their
column. Rows grow as needed, including for unbroken identifiers. The default
wrap=false keeps compact rows with ellipsis. Names, folding, splitter controls,
mobile layout, and expanded Print output retain their existing behavior.
Complete storage comments
- storage/
- metadata/Schema definitions: property keys, vertex and edge labels, indexes, and counters.
- graph/Graph data: vertices, edges, index tables, and OLAP analysis data.
Invalid wrap values warn and fall back to false. Review the warning and fallback before publication.
Title bars
The fence attribute {title="…"} adds a title bar above the tree. Without it, no title bar appears.
the oink.pgsty.com repository root
- content/pages
- assets/resources that take part in the build
- data/data for the home page, landings and downloads
- layouts/template overrides
- static/files copied verbatim
- tests/Playwright and node --test
- hugo.yml
- go.modthe theme, imported as a Hugo Module
- Makefilemake d / make b / make c
Indentation and depth
Indentation sets depth. Two spaces, four spaces, and tabs, counted as four columns, are supported.
Indentation widths can vary within one tree, but every level that you return to must have been opened previously.
You can paste complete tree command output, including the root and summary lines. The summary is removed.
- content/docs
- about
- _index.md
- features.md
- components
- filetree.md
- image
- index.md
- _index.md
- about
Returning to an unopened indentation level warns and skips that line. The warning identifies the line inside the fence.
Folding and explicit types
Directories with children are open by default. {open=false} makes a directory initially closed.
Directories use native <details> and work with the keyboard without JavaScript. Only directories accept open.
An entry without children or a trailing / is a file. {type=dir} forces a directory, and {type=file} forces a file.
the content directory
- content/
- docs/the documentation tree
- components/22 component pages
- callout.md
- filetree.md
- image/page bundle: body + images
- customize/site-level configuration
- config.md
- components/22 component pages
- blog/
- release.md
- docs/the documentation tree
Icons and tones
The theme infers icons from names. Directory icons follow the open state.
Files are matched first by full filename (LICENSE, Makefile, go.mod, package.json, .gitignore …), then by extension (md yml toml json sh py go js sql css png svg pdf zip …). Other files use a generic file icon.
{icon=…} overrides the icon with exactly one Font Awesome class pair.
{tone=…} colors the icon. It uses the badges vocabulary: neutral info success warning danger.
deployment layout: permissions and what matters
- /etc/pigsty/0755 root:root · configuration root
- pigsty.yml0644 root:root · cluster inventory
- ca/0700 root:root · self-signed CA, never commit
- ca.key0600 root:root
- /var/lib/pgsql/18/data/0700 postgres:postgres · data directory
- postgresql.conf0600 postgres:postgres
- /usr/bin/pig0755 root:root · command-line tool
tone colors only the icon. It never colors the text. State the meaning in the name or comment; color supplements it.
Linked entries
Write [name](link) to make an entry name a link. Site paths, relative paths, and http(s): are supported.
Links use the same URL validation as other components.
this site's component pages
- content/docs/
- callout.mdcallouts
- filetree.mdthis page
- gallery.mdgalleries
- image/page bundle
- index.mdimages
- hugo.ymlfixture configuration on GitHub
One tree per platform
A fence carrying tab= (and group= / value=) becomes one panel of a
tab set and can sit alongside code fences.
- /etc/pigsty/configuration
- /var/lib/pgsql/data
- /usr/bin/pigexecutable
- ~/Library/Application Support/pigsty/configuration
- /opt/homebrew/bin/pigexecutable
Output
| Output | Shape |
|---|---|
| HTML | <div class="td-filetree">, an optional title bar, directories as native <details>; a tree with comments also gets the draggable splitter, its only runtime |
| The same tree, fully expanded, no splitter, comments wrapped instead of truncated | |
| Markdown | The filetree fence, emitted as written |
| RSS | The fence source inside a <pre> |
Below the sm breakpoint, the layout becomes one column. Comments move below names, display without truncation, and the splitter is hidden.
Trees without comments always use one column and load no script.
Parameter reference
Fence attributes, after ```filetree:
title, ,- Title bar above the tree; omitted when absent; must not be empty
wrap, ,- Wrap long comments and grow rows; filenames keep ellipsis
tab, ,- Makes this tree one panel of a tab set
group/value, ,- Tab group and sync value; must appear with
tab class, ,- Passed through for site CSS
Entry attributes, in the {…} at the end of a line:
icon, ,- For example
fa-solid fa-lock; a malformed value warns and uses the default icon tone, ,neutralinfosuccesswarningdanger; colours the icon onlyopen, ,- Directories only;
falsestarts it closed type, ,dirorfile, overriding the inference
The line syntax itself:
Indentation- Two spaces / four spaces / tabs / the
│ ├── └──drawing fromtree - name- The bullet is optional;
-,*and+are equivalent name/- A trailing slash marks a directory; the name renders as written, slash kept
[name](url)- A linked entry
# comment- Everything after the first whitespace-preceded
#;\#is a literal hash N directories, M files- The
treesummary line, dropped automatically
Unknown attributes or values, open on files, malformed {…}, and dedents to unopened levels warn.
The theme uses a safe fallback or skips the invalid line. The message identifies the line.
Limits
filetreefences are the only form. There is no{.filetree}list marker or shortcode.- Names and comments are plain text.
**bold**appears literally, so the source remains readable in other tools. - The tree reads nothing from disk. You write or paste static content, which does not track the repository.
- There is no search, multiple selection, or control to copy the whole tree. Use a code block when readers must copy the exact listing.
- Split positions are not saved. Reloading restores the width calculated at build time.
Related
- Code blocks — listings meant to be copied verbatim
- Tabs — one tree per platform, side by side
- Badges —
toneuses the same vocabulary - Organizing content — how a real content directory is laid out
10 - Math
KaTeX renders mathematics to HTML + MathML at build time. Pages with formulas load one local KaTeX stylesheet.
They load no JavaScript and contact no remote mathematics service.
Use \(…\) for inline formulas, $$…$$ or \[…\] for display formulas, or math and chem fences.
For TikZ or macro packages unsupported by KaTeX, use a pre-rendered image.
Validate generated formulas with Hugo Extended 0.168.0 and the bundled stylesheet. TeX and MathML remain unchanged. No browser mathematics runtime or extra site switch is needed.
Site prerequisites
math and chem fences need no configuration.
The $$, \[…\], and \(…\) delimiters need Goldmark’s passthrough extension.
Hugo does not merge theme markup configuration. Put this block in your site’s configuration file.
This site uses:
Configuration defines each key. Delimiters must not conflict with prose.
A single $ is deliberately not configured, so prices such as “$5” are never treated as mathematics.
Shortest form
Put inline formulas inside sentences. Keep surrounding spaces and punctuation outside the delimiters.
The shared buffer hit ratio is , where is blks_hit and is blks_read.
Display formulas
Put a formula in its own paragraph between $$ delimiters. It displays larger and centered.
\[…\] has the same effect.
A B-tree with fan-out over keys has height:
Long formulas scroll horizontally within the reading column instead of widening the layout. In print, they remain static.
The math fence
The math fence is another form for display formulas. It needs no site passthrough configuration.
GitHub displays its source as an ordinary code block.
This is Little’s law for a connection pool. In steady state, required concurrency equals arrival rate multiplied by mean response time. The pool is usually much smaller than the client count.
Chemistry and units
The chem fence uses KaTeX’s mhchem extension with a \ce{…} body. This extension also typesets physical units.
For the syntax see the mhchem manual.
Numbered equations
An attribute line below a display formula creates a numbered equation.
num is an author-provided string, such as 3-1 or 5.3. The theme never counts. #id defaults to eq-<num>.
The number appears to the right of the formula with a localized “Equation” prefix.
See Equation 3-1: multiply by the retention period for the floor on archive disk size.
caption is optional plain text. #id and caption require num.
Incomplete or duplicate targets warn and remove unusable parts or keep the first target.
On narrow screens, long captions wrap within the reading column without widening the page.
Cross references
Reference numbered equations with ordinary links, as above.
For cross-page references or automatic “Equation N” labels, use xref:
Capacity planning starts from Equation 3-1.
xref may appear before its target. Forward references are allowed.
For the book-wide equation list and book-equations index, see publishing books.
The eq shortcode
Use eq when your site cannot enable passthrough. It uses the same KaTeX renderer.
Without parameters, it displays an unnumbered formula. With num, it is equivalent to the attribute-line form.
This site enables passthrough, so ordinary authoring uses $$.
Use eq for migrated manuscripts or sites whose hugo.yml cannot be changed.
Output
| Output | Shape |
|---|---|
| HTML | KaTeX HTML + MathML rendered at build time; this page also loads a local katex.min.css, which pages without formulas never load |
| Same as HTML, static, long formulas do not scroll | |
| Markdown | The source as written: $$ blocks with their attribute line, math / chem fences, \(…\); the eq shortcode emits **Equation 3-2.** caption plus a $$ block |
| RSS | The same static text as Markdown |
No form loads JavaScript.
Parameter reference
Four spellings:
\(…\),- Governed by the site’s passthrough configuration; takes no attributes
$$…$$/\[…\],- As above; may be followed by an attribute line to become numbered
```math,- Independent of passthrough; takes no attributes
```chem,- As above, with
\ce{…}in the body
The attribute line {…} under a display formula:
num, ,[0-9A-Za-z.-]+; registers a numbered equation and shows “Equation N” at the right#id, ,[A-Za-z][A-Za-z0-9_.:-]*; the anchor and cross-reference targetcaption, ,- Caption after the number; requires
num
The eq shortcode:
num, ,- As above; without it the formula is an unnumbered display formula
id, ,- Requires
num caption, ,- Requires
num class, ,- Requires
num; passed through for site CSS Body, ,- Required, non-empty
Invalid TeX warns and preserves the expression in ordinary previews. The message includes KaTeX details and the source position. Review the warning and rendered fallback before publication.
Limits
- The site’s
markup.goldmarkpassthrough extension controls whether$$,\[…\], and\(…\)render. The theme does not read amath: truefront matter key. Without configuration,$$appears literally. Themathfence andeqwork without this configuration. - Only
$$blocks andeqsupport numbering. Themathfence accepts no attribute line. Use another form when you need numbers. - Authors provide numbers. The theme neither counts nor renumbers. If you reorder chapters, edit
num. - Inline formulas accept no attributes. Attribute lines apply only to display formulas.
captionis plain text. Markdown in captions is not parsed.
Related
- Code blocks — fence attributes and numbered examples
- Images — figures use the same
{#id num=}numbering - Publishing books — lists of equations and cross-page references
- Configuration — the
markup.goldmarkkeys
11 - Mermaid
mermaid fence for flowcharts, sequence diagrams, Gantt charts, class diagrams, and state diagrams. Bundled Mermaid follows the color scheme; source diffs show changes.A mermaid fence displays text as a flowchart, sequence diagram, Gantt chart, class diagram, ER diagram, or state diagram.
Git stores the diagram source, diffs show changes, and search can find it.
The reader’s browser renders it with bundled Mermaid. It contacts no external service.
If a diagram needs precise pixel control, use SVG as an image.
Shortest form
flowchart LR
content["content/"] --> Hugo
config["hugo.yml"] --> Hugo
theme["OINK theme"] --> Hugo
Hugo --> site["public/"]Use mermaid as the fence language. No other switch is needed.
Only pages with this fence load the Mermaid runtime. Even ten diagrams on one page load it only once.
Sequence diagrams
sequenceDiagram describes messages between participants over time. Use it for request paths and loading order.
sequenceDiagram
autonumber
participant Reader as Reader's browser
participant CDN as Static hosting
participant JS as Page script bundle
Reader->>CDN: GET /docs/components/mermaid/
CDN-->>Reader: HTML (a figure plus the fence source)
Reader->>CDN: GET this page's bundle
CDN-->>Reader: mermaid.min.js
JS->>JS: render the fence source into SVG
Note over JS: runtimes the page never used are not downloadedGantt charts
gantt displays intervals. This example shows each PostgreSQL major version’s five-year community support period, measured from release.
1825d means five years.
gantt
title Five-year community support per PostgreSQL major version
dateFormat YYYY-MM-DD
axisFormat %Y
section PG 15
released 2022-10-13 :2022-10-13, 1825d
section PG 16
released 2023-09-14 :2023-09-14, 1825d
section PG 17
released 2024-09-26 :2024-09-26, 1825d
section PG 18
released 2025-09-25 :active, 2025-09-25, 1825dClass and ER diagrams
classDiagram displays types and relationships. erDiagram displays entities and cardinality. Use either to explain a data model.
classDiagram
class Page {
+string Title
+string Description
+int Weight
+Content()
+OutputFormats()
}
class Resource {
+string Name
+string RelPermalink
+Resize(spec)
}
class OutputFormat {
+string Name
+string MediaType
}
Page "1" --> "0..*" Resource : page bundle resources
Page "1" --> "1..*" OutputFormat : html / print / markdown / rsserDiagram
pg_database ||--o{ pg_namespace : "contains schemas"
pg_namespace ||--o{ pg_class : "contains relations"
pg_class ||--o{ pg_attribute : "has columns"
pg_class ||--o{ pg_index : "is indexed by"
pg_class {
oid oid PK
name relname
char relkind
}
pg_attribute {
oid attrelid FK
name attname
smallint attnum
}State diagrams
stateDiagram-v2 displays states and transition conditions.
This example shows the five stages of a theme release.
stateDiagram-v2
[*] --> SourceComplete
SourceComplete --> Validated : theme checks + site suite green
Validated --> Published : an immutable signed vX.Y.Z tag is pushed
Published --> Documented : the site's go.mod pins that tag
Documented --> Deployed : the production build goes live
Deployed --> [*]
Published --> SourceComplete : a problem means a new patch version; tags never movePer-diagram title and configuration
A fence body can start with Mermaid’s YAML header. This is not Hugo front matter.
title sets the diagram title. config overrides Mermaid configuration for this diagram only.
If a diagram fixes config.theme, it no longer follows the site’s color scheme.
---
title: Only the runtimes a page used are bundled
config:
flowchart:
curve: linear
---
flowchart TD
Page --> Which{which components?}
Which -->|Mermaid fence| M[mermaid.min.js]
Which -->|ECharts fence| E[echarts.min.js]
Which -->|none| B[base bundle only]Light and dark
At initialization, the theme reads the current color scheme. Dark mode uses Mermaid’s dark theme.
Light mode uses the site’s configured theme. Changing the color scheme redraws diagrams in place without reloading the page.
Each diagram keeps its height during redrawing, so page content does not move.
Put site-wide defaults in hugo.yml with lowercase keys. The theme maps them to Mermaid’s key casing:
Configuration lists all keys. See the Mermaid configuration reference for accepted values.
Inside tabs and steps
A mermaid fence has no tab attribute. Adjacent-fence tabs apply only to ordinary code fences.
To compare two diagrams, use the tabs shortcode.
flowchart LR
Markdown --> Goldmark --> RenderHooks --> HTMLflowchart LR
Page --> HTML
Page --> Print
Page --> Markdown
Page --> RSSEach step in {{% steps %}} uses page-level Markdown and can contain a mermaid fence.
See Steps.
Output
| Output | Shape |
|---|---|
| HTML | A figure retaining readable source; the runtime draws SVG as it approaches the viewport |
The source inside <pre class="td-mermaid-source">, static — no runtime runs there |
|
| Markdown | The mermaid fence and its source, kept as written |
| RSS | The source inside <pre class="td-mermaid-source"> — subscribers see text |
Parameter reference
A mermaid fence reads no attribute line. {height=…} and {class=…} have no effect and produce no error.
The diagram and container width determine the size. The diagram is centered.
Site parameters (hugo.yml):
params.mermaid, ,- The whole map is passed to Mermaid’s
initialize(); write keys in lowercase and the theme matches them back to Mermaid’s casing params.mermaid.theme, ,- The light-mode theme; dark mode forces
dark
Put per-diagram configuration (title, config) in the YAML header at the start of the fence body.
These are Mermaid keys, not theme parameters.
Enlarging a diagram
This shared viewer and demand loading are part of OINK 1.4.0.
Mermaid and local PlantUML share the corner-button viewer. It reuses the rendered
result without running the engine again. Drag or use arrow keys to pan; use the
wheel, pinch, + or - to zoom. Choose Fit to window or press 0 to see the
whole diagram. Esc closes the viewer and restores focus to its opener. Very wide
pictures initially open at natural size for readable labels. Controls retain touch
size on phones. Theme changes retain your position; reduced motion adds no animation.
Choose Source to inspect the original text and Copy code to copy it. Arrows, quotes, ampersands and Chinese stay intact. Download SVG exports a styled, standalone image requiring no remote resources. Copy and export failures show feedback. An SVG with external image or style dependencies cannot be exported. The source disclosure below each figure also supports copying.
Demand loading and printing
A visible diagram within 320px of the viewport loads its engine and renders. Multiple diagrams share engines and both types render serially. Hidden tabs, closed disclosures and zero-width containers wait until visible. Browsers without IntersectionObserver use scroll and size checks. Rapid theme changes discard obsolete results. Diagram-free pages load neither the viewer nor these engines. No installation dependency or build step is added.
Disabled JavaScript, blocked engines and syntax errors retain readable source. In OINK 1.4.0, ordinary HTML printing scales completed light diagrams to the page. Dark diagrams and unrendered diagrams print black-on-white source with wrapping, without waiting for an asynchronous engine or requiring background printing. To print pictures throughout, switch to light mode, then visit and expand the diagrams you need before printing. Printing restores source disclosures afterward and does not change your appearance preference. Dedicated Print, Markdown and RSS continue to show source.
Limits
- Mermaid emits inline SVG instead of
<img>, so{#id num=}numbering does not apply. If you need numbering, export an image and use image numbering. - Fence attributes have no effect. Control width through diagram syntax, such as flowchart direction or class-diagram layout, or CSS. There is no alignment attribute. Diagrams are always centered.
- Syntax errors appear only in the browser because Hugo does not parse Mermaid. Invalid diagrams display an alert and keep readable source, but the build still passes. Check the browser before publishing.
- RSS, Markdown, and Print include source instead of pictures. State conclusions in prose as well as in diagrams.
Related
12 - Component presentation
Use the Appearance menu to compare Paper, Slate, Ink, and Terminal in light or dark mode. These examples use the same content and preserve the normal Markdown authoring model.
The optional variants on this page ship in OINK 1.4.0.
Related pages
-
Install the theme and preview a first page locally.
-
Set navigation, languages, appearance, and search.
For a compact resource directory, use {.cards .td-cards-list}. A divided list has one enclosing frame and grows naturally with its descriptions.
- Writing content — Organize articles, guides, and release notes; see also the configuration guide.
- Component reference with a longer title — Choose native Markdown or a compound shortcode.
The full form accepts cards variant="list" for icons, badges, or block descriptions:
Build a local preview before changing the site configuration.
Read the configuration guide or the writing guide. A card without a title link remains ordinary content.
Notes and disclosures
Review the page at a narrow width as well as on your desktop.
Confirm the destination before publishing a new version.
The disclosure is a native HTML details element. It remains usable with scripts disabled.
The title, chevron, and focus outline share one stable summary row.
Each disclosure opens independently. Other content stays in its current state.
Tabs and commands
A marked one-line fence uses {class="td-code-command"}. Its copy button occupies its own column so the command can scroll or wrap without being obscured.
wrap, copy, and accessible labels keep their existing meaning. Multiline, numbered, or collapsed input warns and falls back to an ordinary code block. Single-line fences without this modifier keep their usual presentation.
Short procedures
Add {.steps .td-steps-compact} to a short ordered list. The regular .steps layout remains available for longer tutorials.
- Review the configuration.
- Run the local preview.
- Check the generated output.
For a procedure with headings, use steps variant="compact" with percent delimiters:
Preview
Run the development server and open the changed page.
Review
Check the page in the language and appearance your readers use.
Tables and metadata
| View | Purpose | Input |
|---|---|---|
| Cards | Related resources | Link list |
| Steps | Ordered procedure | Ordered list |
| Tabs | Equivalent alternatives | Adjacent blocks |
title,- A concise title that may wrap naturally.
description,- Supporting information, separate from the main label.
Preview Validated Review needed
Open search with Ctrl with K and move between results with the arrow keys.
Compatibility
These variants load no additional runtime. Existing links, keyboard behavior, copy text, print content, and Markdown output retain their meaning. Unsupported cards or steps variants warn and use the regular presentation. The visual refinement does not change the default preset or font policy.
13 - PlantUML
Write PlantUML source in a plantuml fence. OINK renders it in the reader’s
browser with two bundled scripts. No Java, Graphviz executable, npm install,
CDN or rendering service is needed. Diagram source stays in the browser when
using local rendering.
Local rendering is available when PlantUML is enabled without an endpoint. An explicit rendering endpoint continues to select server mode.
Enable it in your site configuration:
plantuml: { enable: true } also works. The default remains disabled. Enabled
pages without PlantUML fences do not load either engine script.
Sequence diagram
Wrap the source in a plantuml fence. This live example renders entirely locally:
@startuml
actor Reader
participant Browser
Reader -> Browser : open the page
Browser -> Browser : render locally
Browser --> Reader : SVG diagram
@enduml
Class diagram
Declare classes, fields and relationship cardinalities.
@startuml
class Publication {
+ pubname : name
+ puballtables : bool
+ pubinsert / pubupdate / pubdelete : bool
}
class Subscription {
+ subname : name
+ subconninfo : text
+ subslotname : name
}
class ReplicationSlot {
+ slot_name : name
+ plugin : name
+ confirmed_flush_lsn : pg_lsn
}
Publication "1" -- "0..*" Subscription : subscribed by
Subscription "1" -- "1" ReplicationSlot : bound to
@enduml
Component diagram
Packages group components; arrows show their dependencies.
@startuml
package "Monitoring node" {
[Grafana] as grafana
[Prometheus] as prom
[Alertmanager] as alert
}
package "Database node" {
[node_exporter] as node
[pg_exporter] as pgexp
[PostgreSQL] as pg
}
pg --> pgexp : query the statistics views
node --> prom : /metrics
pgexp --> prom : /metrics
prom --> alert : rule fired
grafana --> prom : PromQL
@enduml
Activity diagram
Use decisions and branches to explain a workflow.
@startuml
start
:write content/docs/**/*.md;
:add the translated peer, copying the rendered heading IDs;
if (hugo passes?) then (yes)
:npm test;
else (no)
:fix using the file and line in the error;
stop
endif
if (tests green?) then (yes)
:open the PR;
stop
else (no)
:back to editing;
stop
endif
@enduml
Use-case diagram
Actors and use cases describe what each reader can do.
@startuml
left to right direction
actor Reader as reader
actor Author as author
actor Maintainer as maintainer
rectangle "Documentation site" {
reader --> (full-text search)
reader --> (switch language)
reader --> (export the print view)
author --> (add a page)
author --> (preview locally)
maintainer --> (upgrade the theme)
maintainer --> (publish)
}
@enduml
Dark mode
Local diagrams follow light/dark mode; authored skinparam settings still apply.
Obsolete render results are discarded when the mode changes. An open viewer
retains its zoom and pan position.
Enlarge, source and download
Local PlantUML uses the same viewer as Mermaid.
Use the corner button to open it, drag or arrow keys to pan, wheel/pinch/+/-
to zoom, Fit to window or 0 to fit, and Esc to close and restore focus.
The viewer reuses the Blob image without inserting PlantUML SVG markup or links
into the page DOM, and without rendering again.
Source and Copy code preserve arrows, quotes, ampersands and Chinese. Download SVG exports a styled standalone file; external resource dependencies prevent export. Failures show feedback in the toolbar. The source disclosure below each diagram also supports viewing and copying. Explicit server mode keeps its legacy behavior.
Demand loading and printing
The two local engines load once when a diagram comes within 320px of the viewport. Hidden tabs, disclosures and zero-width containers wait until shown. Browsers without IntersectionObserver use scroll and size checks. Mermaid and PlantUML render serially on the main thread. No installation or build step is added.
Ordinary browser printing retains rendered images and shows source for unrendered diagrams. It cannot wait for asynchronous engines; visit and expand the diagrams first when you need pictures throughout. Dedicated Print, Markdown and RSS keep source fallback.
Optional rendering service
Existing sites can keep an explicitly configured endpoint:
A nonempty svg_image_url selects server rendering. Removing it selects local
rendering. The server URL must end with the appropriate path separator and be
an HTTP(S) URL with a host or a same-site path. Invalid endpoints warn and disable
rendering; they do not silently switch modes. OINK supplies no public endpoint.
Server mode sends encoded diagram source to that endpoint and retains its
existing svg option. Local mode ignores svg: generated SVG is displayed as
an image, so authored links and markup do not enter the page DOM.
Outputs
| Output | Result |
|---|---|
| HTML | Local SVG image when enabled; readable source until rendering succeeds |
| Browser print of HTML | Rendered image scaled to fit, or readable source if not rendered |
| Dedicated Print output | Readable source, with no PlantUML runtime |
| Markdown and RSS | Original diagram source; no rendering request |
With JavaScript disabled, a failed engine download, unsupported input or a rendering error, the source remains readable. A failed diagram does not prevent other diagrams on the page from rendering.
Parameters
params.plantuml, ,trueenables local renderingparams.plantuml.enable, ,- Enables the map form
params.plantuml.svg_image_url, ,- Optional endpoint selecting legacy server rendering
params.plantuml.svg, ,- Server mode only: inline SVG instead of an image
Fences do not accept code-block title, copy, line-number, numbering or zoom
attributes. Source without @startuml / @enduml is wrapped for local rendering;
explicit diagram delimiters are preserved.
Limits
- The browser bundle includes the core engine and Graphviz layout only.
!include,!includeurl, external themes, C4, AWS and other optional sprite libraries are not downloaded. Unsupported resources leave the source visible. Use self-contained diagrams, pre-rendered images, or an explicit server for these. - The pinned engine is
@plantuml/core1.2026.9 with Viz.js 3.24.0. The two scripts total about 4.8 MB before compression, or 1.7 MB with gzip. They load only as enabled diagrams approach the viewport; normal HTTP caching applies. - Rendering uses the browser’s JavaScript and WebAssembly support. Sites with a
restrictive CSP need to allow their own scripts, WebAssembly compilation
(
wasm-unsafe-eval) andblob:images. Blocked resources retain source. - Large diagrams still cost browser CPU and memory. Rendering proceeds one diagram at a time; this is not a background-worker renderer. After an uncancellable engine timeout, remaining PlantUML figures keep source until the page is reloaded.
- Diagrams are images: SVG hyperlinks are inactive. Numbering is not part of this integration.
Related
- Mermaid — another bundled browser diagram engine
- Images — pre-rendered diagrams, numbering and zoom
- Configuration — site settings
14 - Markmap
markmap fence for an expandable mind map with zoom controls. Its source remains a readable Markdown outline.A markmap fence contains a Markdown outline. Headings and lists define the hierarchy.
The browser displays an expandable, collapsible tree. Use it to give an overview of a section.
For flows with direction or conditions, use Mermaid.
Shortest form
Enable Markmap in site configuration first. It is off by default. Without this setting, the fence stays a readable code block.
Then put the outline in a markmap fence:
# OINK
## Local-first
- every runtime ships with the theme
- no CDN involved
## Markdown-native
- components are fences and attribute lines
- usable without writing a shortcode
## Four output states
- HTML
- print
- Markdown
- RSS
The first-level heading is the root. Indentation places other headings and list items below it. Click a node’s dot to expand or collapse its branch. Scroll to zoom, and drag to pan. In OINK 1.4.0, Fit to window below the map restores the whole outline and resumes automatic fitting when the column changes width. Dragging or zooming suspends automatic fitting to preserve your reading position. The button also works with Tab and Enter.
Depth
Deeper levels use smaller text, and the canvas arranges itself. This example shows the theme documentation site’s six sections and their page counts.
# OINK documentation
## Introduction (4 pages)
### What it is
### Feature tour
### Showcase
### Licences
## Get started (4 pages)
### Choose a path
### OINK Starter
### Repository tour
### From scratch
## Authoring (8 pages)
### Organizing content
### Writing pages
### Front matter
### Blog
### Books
### Releases and downloads
### OpenAPI
## Components (22 pages)
### Callouts / tabs / steps / cards
### Images / galleries / tables / fields
### Diagrams: Mermaid / PlantUML / Markmap / ECharts
## Customization (15 pages)
### Branding / navigation / search / languages
### Landing / versions / taxonomies / print
## Operations (7 pages)
### Preview / deploy / upgrade
### Comments / analytics / troubleshooting
Links, code and emphasis
Nodes accept inline Markdown. Links are clickable, inline code is monospaced, and bold and italic text display normally.
# Everyday commands
## Preview
- `hugo server` — open [localhost:1313](http://localhost:1313/)
- `hugo server -D` — **including drafts**
## Build
- `hugo --printPathWarnings`
- `hugo --gc --minify` — for publishing
## Theme
- `hugo mod get -u github.com/pgsty/oink`
- [theme repository](https://github.com/pgsty/oink)
- [site source](https://github.com/pgsty/oink.pgsty.com)
Mathematics in nodes
The Markmap runtime includes local KaTeX. $…$ in nodes renders as a formula.
# PostgreSQL metrics worth watching
## Cache hit ratio
- $\frac{blks\_hit}{blks\_hit + blks\_read}$
- below 0.99, look at shared_buffers
## Replication lag
- $lsn_{primary} - lsn_{replica}$
## Transaction throughput
- $TPS = \frac{\Delta xact\_commit}{\Delta t}$
Controlling the initial depth
The fence body can start with Markmap’s YAML header. This is not Hugo front matter.
initialExpandLevel initially expands only the first levels. Readers can open the rest.
colorFreezeLevel sets the level from which a branch keeps one color.
---
markmap:
initialExpandLevel: 2
colorFreezeLevel: 2
---
# Check scripts in the theme repository
## Source-level contracts
### check-i18n.py
### check-taxonomy.py
### check-font-tokens.py
## Output-level checks
### check-output.py
### check-goldens.py
### check-code-blocks.py
### check-content-primitives.py
### check-media-primitives.py
## Browser runtimes
### node --test tests/js/**/*.test.js
Folded into a disclosure
Every map is 300 pixels tall. Three consecutive maps occupy considerable page space.
Put a large overview in > [!DETAILS] so readers can open it.
Start every disclosure line with >, including fence lines.
# pgsty/oink
## layouts/
- baseof.html and the per-type shells
- _partials/shell/
- _markup/ render hooks
- _shortcodes/
## assets/
- scss/ tokens and component styles
- js/ browser runtimes
- third_party/ libraries shipped with the theme
## i18n/
- 32 locale files with identical keys
## docs/
- maintainer contracts
Output
| Output | Shape |
|---|---|
| HTML | <pre><code class="language-markmap"> first; the runtime replaces it with <div class="markmap"> and draws the SVG |
| Same as HTML: the print view loads the runtime too | |
| Markdown | The markmap fence and its outline, kept as written |
| RSS | The outline source only — a readable outline for subscribers |
The outline supplies the content. Without JavaScript, the complete hierarchy remains readable.
Parameter reference
A markmap fence reads no attribute line. The theme fixes its height at 300px through .markmap > svg.
Its width fills the reading column.
Site parameters (hugo.yml):
params.markmap, ,- With it off, the fence stays a code block and no runtime loads
Configuration defines the site key.
Put per-map behavior in the markmap: YAML header at the start of the body, such as initialExpandLevel, colorFreezeLevel, or maxWidth.
This is Markmap syntax. See the Markmap documentation for accepted keys.
Limits
- Inline SVG output is fixed at 300px tall by one
.markmap > svgrule. Fences cannot change this height. For many levels, useinitialExpandLevelor split the map.{#id num=}numbering and image zoom do not apply to inline SVG. - Node text follows the site’s text color; connecting lines retain Markmap’s own palette. Check custom colors in both modes.
- Without
params.markmap, the fence remains a code block. Sites that do not use Markmap load no runtime. - OINK 1.4.0 provides a fit control below each map; it is hidden in print.
- Avoid
<,>,&, and"in outlines. The current theme double-escapes them, displaying literal>or". Use[text](URL)links instead of angle-bracket autolinks.
Related
- Mermaid — diagrams with direction and conditions
- File trees — more precise for directory structure
- Callouts — everything
[!DETAILS]can do - Configuration —
params.markmap
15 - Draw.io
.drawio.svg with an embedded editable copy as an ordinary image. Its edit button opens the Draw.io editor.Draw.io uses plain Markdown images. It has no fence or shortcode.
When exporting from Draw.io, select “Include a copy of my diagram”. The SVG or PNG then contains an mxfile copy.
The theme detects this copy and adds an edit button. Use this integration for diagrams that readers can download and change.
Use an ordinary image for diagrams that only need to be viewed.
Shortest form
To show the edit button, first set params.drawio.enable: true and configure
params.drawio.drawio_server as shown under The editor address.
Without this setup, the diagram remains an ordinary image without editing.
Use ordinary image syntax. The filename does not affect detection. .drawio.svg is only a naming convention.
An export with an mxfile copy is wrapped in a .drawio container.
A pencil button appears at the bottom right on hover or keyboard focus. It stays visible on touch devices and in forced-colors mode.
The button opens a full-screen iframe with the site’s configured editor.
When image zoom is enabled, Edit and Zoom are separate sibling buttons. Edit does not open the zoom dialog.
How the copy is detected
The runtime checks whether the file contains mxfile. It does not check the filename.
A hand-drawn SVG with the same block-image syntax and attribute line has no embedded copy, so it gets no edit button.
With a caption
Draw.io images use the ordinary image render hook. All image attributes apply.
Add caption to create a captioned figure. The edit button still appears on the image.
As a numbered figure
Add {#id num=…} to create a numbered figure. xref can reference it, and it appears in the list of figures.
The complete numbering and cross-reference rules are in publishing books.
SVG or PNG
Both SVG and PNG are recognized. A Draw.io PNG can store the editable copy in a text chunk. The runtime uses the same detection test.

Prefer SVG for documentation. It scales without quality loss, contains searchable text accessible to screen readers, and has readable diffs. Use PNG for very complex diagrams or platforms without SVG support. Only PNG supports Hugo image processing; processing an SVG warns and preserves the source.
What the button does
The button performs three actions in this order.
Lay an overlay over the page
In OINK 1.3.0, the runtime opens a full-screen
<dialog class="drawioframe"> containing an iframe.
The editor URL keeps the configured drawio_server query parameters and fragment,
and sets embed=1, ui=atlas, proto=json, saveAndEdit=1, and noSaveBtn=1.
The modal includes a localized Close button and contains keyboard focus. Close
it with that button or a background click. Escape closes it while focus is in
the host dialog; the embedded editor handles its own keys. Closing restores
focus to Edit unless another surface has already taken focus.
Hand the diagram to the editor
When the editor is ready, the runtime sends the image and its mxfile copy to the iframe as a data URL.
This transfer does not use your server.
Save and write back
When you save, the editor exports the original format, SVG or PNG. The browser downloads it with the same filename.
The runtime never writes to the repository. Replace the file in content/ with the download and commit it yourself.
The edit button lets readers download and change a diagram. It does not edit the site online.
The editor address
enable: truewithoutdrawio_serverwarns and disables editing. The theme does not select a public service.- The address must be an HTTP(S) URL or local path. Local paths honor the
baseURLdeployment subpath. Whitespace, control characters, raw backslashes, protocol-relative URLs (//host/), and other schemes warn and disable editing. - If editing must stay within your organization, deploy a self-hosted editor and configure its address.
- The public endpoint
https://embed.diagrams.net/works. With this endpoint, the reader’s diagram is sent to a third-party page.
Both keys are defined in Configuration.
Output
| Output | Shape |
|---|---|
| HTML | A plain <img> or <figure>; once enabled, the runtime wraps an image that carries a copy in <div class="drawio"> and adds the button |
| The image prints as usual; this output loads no Draw.io runtime and creates no edit button | |
| Markdown | Plain Markdown image syntax |
| RSS | A plain <img> with an absolute URL and no button |
All four outputs include the image. Only HTML adds the optional edit button.
Parameter reference
Draw.io has no fence or shortcode parameters. It uses the Images attribute line:
caption, width, height, link, #id, num, command, and options.
Site parameters (hugo.yml):
params.drawio.enable, ,- With it off no script loads and an image is just an image
params.drawio.drawio_server, ,- The editor address; required when
enable: true
Limits
- The runtime loads only if rendered page content has
.svgor.pngcandidates. It groups matching images by URL and reads each URL once to findmxfile. - Without “Include a copy of my diagram” on export, the image has no edit button.
- Editing needs the editor and never writes to the repository. Offline, images display normally, but the button has no effect. Saving downloads a file. You must replace and commit the file manually.
- Exported SVG colors are fixed and do not follow the site’s color scheme.
Use
nonefills and neutral gray lines and text so the image is readable in both modes.
Related
- Images — captions, numbering, sizing and zoom in full
- PlantUML — UML diagrams; see its rendering modes and version requirements
- Mermaid — diagrams from text with no server at all
- Configuration — the full definition of
params.drawio.*
16 - ECharts
echarts fence. Hugo validates them, and bundled ECharts draws charts that follow the color scheme.An echarts fence contains an ECharts option object in YAML or JSON. It contains data, not code.
Use it for quantitative charts with axes, series, and a legend.
Use Mermaid for relationships and flows. Use Infographic for order and hierarchy.
Hugo parses options at build time. Invalid input warns and preserves readable source.
The browser draws charts with the theme’s bundled ECharts. Only pages that use it load the runtime.
Shortest form
A bar chart needs xAxis, yAxis, and series. This chart shows page counts for the six documentation sections.
tooltip:
trigger: axis
xAxis:
type: category
data: [Introduction, Get started, Authoring, Components, Customization, Operations]
yAxis:
type: value
name: pages
series:
- name: pages
type: bar
data: [4, 4, 8, 22, 15, 7]Both formats are supported. YAML is shorter because it needs no quotes or commas. Incorrect indentation or an array instead of a map warns, identifies the source line, and shows the source instead of a blank chart.
Multiple line series
series is an array. Add an entry for each line. legend lets readers hide a series.
This chart shows PostgreSQL major release years and the end-of-support years from the community’s five-year policy.
tooltip:
trigger: axis
legend:
data: [Released, End of support]
grid:
left: 56
right: 24
top: 48
bottom: 40
xAxis:
type: category
name: major version
data: ["9.6", "10", "11", "12", "13", "14", "15", "16", "17", "18"]
yAxis:
type: value
min: 2015
max: 2031
name: year
series:
- name: Released
type: line
smooth: false
data: [2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025]
- name: End of support
type: line
lineStyle:
type: dashed
data: [2021, 2022, 2023, 2024, 2025, 2026, 2027, 2028, 2029, 2030]Quote version numbers. YAML reads unquoted 10 and 9.6 as numbers. Category-axis labels must be strings.
Pie and doughnut charts
Give radius two values to create a doughnut chart. This example groups OINK’s 29 shortcodes by purpose.
tooltip:
trigger: item
formatter: "{b}: {c} ({d}%)"
legend:
bottom: 0
series:
- type: pie
radius: [42%, 70%]
itemStyle:
borderRadius: 6
borderWidth: 2
label:
formatter: "{b} {c}"
data:
- { value: 14, name: Core components }
- { value: 10, name: Book numbering and indexes }
- { value: 3, name: Releases and downloads }
- { value: 2, name: OpenAPI }{b}, {c}, and {d} are ECharts placeholders for name, value, and percentage.
Use them in a string. No function is needed.
Height and full width
height defaults to 400px and accepts px rem em vh vw %.
full=true removes the reading-column limit and fills the content area. Use it for charts with many points or long labels.
tooltip:
trigger: axis
grid:
left: 40
right: 16
top: 24
bottom: 32
xAxis:
type: category
data: [i18n, taxonomy, font tokens, content contracts, navigation, runtime, sidebar icons, search, actions, palette, params, reading, release assets, download, landing, book, migrations, keyboard, shell, output, goldens]
yAxis:
type: value
name: scripts
series:
- type: bar
data: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]Invalid heights such as 360 and 36pt warn and use the default 400px.
Light and dark
Without theme, charts use the reader’s current color scheme. They redraw in place when the scheme changes, without reloading the page.
Charts resize when their containers resize. Switch this page to dark mode to change each chart’s background and text.
A fixed theme keeps the same colors in both modes:
xAxis:
type: category
data: [HTML, Print, Markdown, RSS]
yAxis:
type: value
series:
- type: bar
data: [1, 1, 1, 1]dark is the only built-in runtime theme. Register other ECharts themes with echarts.registerTheme() before naming them here.
Unless branding requires a fixed theme, omit theme so charts follow the site.
Callbacks with $fn:
A fence contains data and cannot contain JavaScript.
If an option needs a function, such as a tooltip formatter or data-dependent color, use "$fn:name" in the options.
Register the name on window.OinkEchartsFunctions:
tooltip:
trigger: axis
formatter: "$fn:pageShare"
xAxis:
type: category
data: [Introduction, Get started, Authoring, Components, Customization, Operations]
yAxis:
type: value
series:
- type: bar
data: [4, 4, 8, 22, 15, 7]Hover over a bar to see the tooltip sentence from the function.
Unregistered names resolve to undefined. The chart draws as if the option were absent, without build or runtime warnings.
Keep the script beside the fence so they change together.
The script is site code and needs code review. If string templates ({b}, {c}, {d}) can express the formatting, no function is needed.
Where the data lives
Fence bodies are literal text. Hugo does not expand shortcodes, front matter variables, or data/ files inside them.
Write the numbers in the fence. Data cannot be shared this way, but Git stores the chart with its data and shows changed numbers.
Do not chart data that changes frequently, such as version matrices or asset lists.
Use a table or a data/-driven component on a release page.
Output
| Output | Shape |
|---|---|
| HTML | A canvas container inside <div class="td-echarts"> plus an application/json options block; the local ECharts draws it |
No chart; the fence source inside <pre class="td-echarts-source"> |
|
| Markdown | The echarts fence and its option source, kept as written |
| RSS | Same as print — source only |
Explain the chart’s information in prose. Print and RSS do not include the chart.
Parameter reference
The fence attribute line (```echarts {…}):
height, ,- A non-negative number plus
pxrememvhvw%; anything else warns and uses the default theme, ,- Pin an ECharts theme and stop following the site’s colour scheme; only
darkis built in full, ,truedrops the reading-column limit and fills the content areaclass, ,- Passed through to the container for site CSS
style, on*, and unknown attributes warn and are ignored.
If a fence body does not parse to a YAML/JSON map, it warns and displays the source.
ECharts defines the option keys in its official option manual.
ECharts has no site-level parameter. It needs no switch in hugo.yml and loads only on pages that use it.
Limits
- Fences cannot contain JavaScript. Use
$fn:for functions. Unregistered names resolve toundefinedwithout an error. - Fences cannot read external data. They cannot access
data/, front matter, or shortcodes. Write the numbers in the fence. - Print and RSS include only the source. State the conclusion in prose.
- Quote category-axis values such as
10,9.6,on, andyes. YAML can convert them to numbers or booleans. - Use line styles or marker shapes as well as color to distinguish series. Check legend contrast in both color schemes.
Related
- Infographic — structure and order, not statistics
- Tables — for few values that must be read exactly
- Mermaid — relationship and flow diagrams
- Code blocks — the general rules for fence attribute lines
17 - Infographic
infographic fence and AntV template to display a title and items as a flow, timeline, funnel, grid, or hierarchy.An infographic fence selects an AntV template to display a title and item list.
Use it for order, hierarchy, or comparison. Use ECharts for axes and precise numbers.
Use Mermaid for flows with conditional branches.
The fence contains data and stays readable as text on GitHub.
Shortest form
Start with infographic <template>, then add a data block. title sets the title.
Every entry under items needs at least a label.
infographic list-row-simple-horizontal-arrow
data
title Three steps in one documentation change
items
- label Write
desc Start with the source language
- label Check
desc Zero build warnings, every example really rendered
- label Ship
desc Add the translated peer, open the PRUse two spaces per indentation level to define structure. Keep labels short and put explanations in desc.
Timelines
The sequence-timeline-* family arranges items on a time axis. label gives the point in time, and desc gives the event.
infographic sequence-timeline-simple
data
title The last five PostgreSQL major versions
items
- label 2021
desc 14: another round of parallel query and logical replication work
- label 2022
desc 15: the MERGE statement
- label 2023
desc 16: logical replication from a standby
- label 2024
desc 17: incremental backup and JSON_TABLE
- label 2025
desc 18: the asynchronous IO subsystemFunnels
sequence-funnel-simple displays narrowing stages.
This example shows the five stages of a theme release.
infographic sequence-funnel-simple
data
title The five states a theme release passes through
items
- label Source complete
desc The code is written, and that is all
- label Validated
desc Theme checks and the site suite are green
- label Published
desc An immutable signed tag, resolvable through the Go proxy
- label Documented
desc The documentation site pins that tag
- label Deployed
desc Production runs this versionGrid cards
For unordered items, list-grid-* uses a grid instead of a sequence.
infographic list-grid-compact-card
data
title One page, four outputs
desc Every content component has to produce something usable in all four
items
- label HTML
desc Interactive, runtimes loaded on demand
- label Print
desc Disclosures expanded, zoom and copy removed
- label Markdown
desc Plain text, compared byte for byte against goldens
- label RSS
desc Static, from the same source as printItems with values
Add value to an item for templates that show proportions, such as pies, doughnuts, or progress displays.
infographic chart-pie-donut-plain-text
data
title How the 29 shortcodes break down
items
- label Core components
value 14
- label Book numbering and indexes
value 10
- label Releases and downloads
value 3
- label OpenAPI
value 2Hierarchy and hand-drawn style
Nest items with children. hierarchy-mindmap-* displays two levels of structure.
A top-level theme block sets the appearance. type accepts light, dark, or hand-drawn.
infographic hierarchy-mindmap-level-gradient-compact-card
theme
type hand-drawn
data
root
label Theme repository
children
- label layouts
desc templates
children
- label _markup
desc render hooks
- label _partials
desc shell and helpers
- label assets
desc resources
children
- label scss
desc tokens and component styles
- label js
desc browser runtimes
- label third_party
desc libraries shipped with the themetheme belongs to the DSL. In OINK 1.4.0, each diagram has its own
canvas: transparent default and hand-drawn diagrams use white, and an authored
background takes priority. A type dark diagram keeps its dark background even
on a light page. Site mode changes preserve the palette, text colors, and drawing
style without rerendering. Explicit transparency or custom text colors still
require checking contrast in both modes.
Picking a template
Template names use structure-variant. Each structure has several visual variants. Common families are listed below:
| Structure prefix | What it expresses | Example |
|---|---|---|
list-row-* list-column-* |
Items in a row or a column | list-row-simple-horizontal-arrow |
list-grid-* |
A grid, no order between items | list-grid-compact-card list-grid-badge-card |
list-pyramid-* sequence-funnel-* |
Narrowing stages | sequence-funnel-simple |
sequence-timeline-* sequence-roadmap-vertical-* |
Timelines and roadmaps | sequence-timeline-simple |
sequence-steps-* sequence-snake-steps-* |
Ordered steps | sequence-steps-simple |
compare-binary-horizontal-* compare-quadrant-* |
Binary comparison and quadrants | compare-binary-horizontal-simple-vs |
hierarchy-mindmap-* hierarchy-structure-* |
Hierarchy, with children |
hierarchy-mindmap-level-gradient-compact-card |
chart-pie-* chart-bar-* chart-column-* |
Illustrative charts, with value |
chart-pie-donut-plain-text |
relation-network-* relation-dagre-flow |
Networks and flows, with relations |
relation-dagre-flow |
Choose the simplest form that explains the relationship. See the full AntV Infographic gallery. Template names match the version bundled with the theme.
Output
| Output | Shape |
|---|---|
| HTML | A canvas container inside <div class="td-infographic"> plus the DSL; the local AntV runtime draws the SVG |
No diagram; the DSL source inside <pre class="td-infographic-source"> |
|
| Markdown | The infographic fence and its DSL, kept as written |
| RSS | Same as print — source only |
Explain the diagram’s information in prose. Print and RSS include only the DSL source.
Parameter reference
The fence attribute line (```infographic {…}):
height, ,- A non-negative number plus
pxrememvhvw%; anything else warns and usesauto full, ,truedrops the reading-column limitclass, ,- Passed through to the container
style, on*, and unknown attributes warn and are ignored. Empty DSL bodies warn and render nothing.
AntV defines these top-level DSL keys:
infographic/template- The template name, on the first line
datatitle,desc,items(orsequences,compares,nodes,values,relations,root, depending on the structure),orderthemetype(light/dark/hand-drawn),palette,colorPrimary,stylize…width/height- Canvas size at the DSL level; usually left to the fence’s
height design- Per-part tuning; rarely needed
Each entry under items accepts label, desc, value, icon, children,
group and id. The DSL is defined by the
AntV Infographic documentation; the
version shipped with the theme and its checksum are recorded in the theme’s
VENDOR.json.
Limits
- Incorrect template names do not fail the build. Hugo checks only fence attributes; the browser runtime parses the DSL. Missing templates display error text in the container. Check the page after changing template names.
themeis part of the DSL and does not follow the site’s color scheme. Check contrast in both modes.- Print and RSS include only the DSL. State conclusions in prose.
- SVG does not provide semantic structure. Screen reader order can differ from visual order. Prefer headings, lists, or tables when they can express the information.
- Keep labels short. Narrow screens can truncate or compress long text. Check at phone width after editing.
Related
18 - Gallery
gallery fence for a responsive image grid with optional descriptions and links. Images share the page zoom dialog.A gallery displays related images in a responsive grid. Put one image per line inside the fence. Use it for multiple views of the same subject, such as screenshots, states, or color schemes. Use an image for a single picture. Gallery images should have an order or support a comparison.
Shortest form
Write one image per line with Markdown’s  syntax.
Alternative text is mandatory. It sets the item’s title, supplies its only screen reader text, and determines zoom eligibility. There is no column parameter. The grid follows the container width and reduces columns on narrow screens.
Descriptions
Add # after the image to start a description below it.
Descriptions are plain text. Markdown appears literally. Use \# for a literal hash.

The default shell: sidebar, article, table of contents

Docsy upstream — the content model is the same lineage

Release cards use release_url and date; checksums blocks list download assets
Descriptions can have different lengths. The grid aligns to the tallest item, and wrapped descriptions do not affect neighboring items.
The image is parsed first. A # in alternative text or a path needs no escaping.
A link per item
Put {link=…} at the end of a line to make that item a link. Site paths, relative paths, and http(s): are supported.
Linked items do not zoom because clicking opens their link. A gallery can contain both linked and unlinked items. Linked items open pages. Unlinked items open full images.
Where images come from
Sources use the plain-image resolution order: page resource in the page bundle → global resource in assets/ → static path /images/… → remote URL.
Local resources include intrinsic dimensions to prevent layout changes while loading.
Remote images are not downloaded or measured at build time.

Under assets/images/…, eligible for build-time processing

Under static/images/…, published as is
Unresolved page or global resources are kept as static paths. The theme does not check whether static or remote images exist.
Decorative images and zoom
Empty alternative text marks decorative images. They have no title, are skipped by screen readers, and never qualify for zoom.
Image zoom is a site-level switch and is off by default. This page enables it in front matter. Images above with alternative text and no link open at full size. Esc closes the dialog and restores the previous focus.

Decorative, never zooms

Has alt text, so it opens
Galleries share the page’s image zoom dialog and have no separate zoom runtime. If no image on the page qualifies for zoom, this runtime does not load. See Images · Zoom.
Classes and tabs
Put class on the fence after the language, or on an item at the end of its line.
The theme passes it through for site CSS without interpreting it.
A fence with tab= and group= / value= becomes a tab set panel.

Sidebar, article, table of contents

The same content-model lineage
Output
| Output | Shape |
|---|---|
| HTML | <ul class="td-gallery"> with one <li> per item; eligible images carry data-td-image-zoom; everything is lazy-loaded |
| The same images stacked, without zoom markers | |
| Markdown | The gallery fence, emitted as written |
| RSS | The same static stack as print |
Galleries load no JavaScript of their own.
Parameter reference
The line syntax  [# description] [{key=value …}]:
,- Must start the line.
altis the item’s title; empty means decorative src,- Page resource / global resource / static path / remote URL
# description,- Plain text under the image;
\#is a literal hash; must not be empty {link=…},- Makes the item a link, and therefore not zoomable
{class=…},- Adds a site CSS class to that item
Fence attributes:
tab, ,- Makes this gallery one panel of a tab set
group/value, ,- Tab group and sync value; must appear with
tab class, ,- Passed through for site CSS
There is no columns, caption, or title attribute.
Malformed lines or attributes warn and remove only the invalid part or line. The warning identifies the line inside the fence.
Limits
- Fences are the only form. There is no
{.gallery}list marker or shortcode. GitHub does not display the source as images. The theme guarantees behavior across four outputs and applies zoom eligibility rules. - Column counts cannot be set. The grid follows the viewport, and images keep their proportions without aspect-ratio cropping.
- There is no slideshow, carousel, or previous / next control. The zoom dialog displays one image at a time.
- Remote images are not downloaded at build time. Their dimensions remain unknown until the browser loads them, so layout can change.
- Descriptions do not support Markdown. Put rich text in a paragraph below the gallery.
For album navigation, image sequencing, and drag-to-pan viewing, use the
Expo layout introduced in OINK 1.3.0. The gallery fence
is for image groups inside text pages.
Related
- Images — single images, captions, numbering, the zoom switch
- Cards — a grid of links with images
- Tabs — one gallery per platform or theme
- File trees — the same line syntax family
19 - Badge
A badge is an inline status label after a name, such as Beta, deprecated, v0.5, or needs a server. Use it for a status of one or two words. Choose a semantic tone. The theme selects colors with contrast in light and dark modes. If the status needs an explanation, procedure, or deadline, use prose or a callout.
Shortest form
text is the only required parameter and must be a non-empty string.
Five tones
Use one of these five values. Custom colors are not supported.
Default Info Supported Experimental Deprecated
If you omit tone, the badge uses neutral. Other values warn and use neutral in ordinary previews.
The warning identifies the source location and should be reviewed with the rendered fallback before publication.
Inside a sentence
A badge is an inline element after a name. It never occupies a separate line.
With params.ui.image_zoom off by default enabled,
block images that have alt text open full size. PlantUML opt-in
uses its own site switch. Draw.io needs a server
warns and remains off when no endpoint is configured.
Next to a heading
Never put a shortcode in a heading. Hugo builds the table of contents before it expands shortcodes. The badge displays in the heading, but an internal Hugo placeholder remains in the table of contents. Put the status in the first paragraph below the heading:
OpenAPI pages
new in 0.5 The badge appears below the heading. The table of contents stays readable. The shared anchor link does not include the badge text.
In table cells
Badges make a comparison table easier to scan than a column of “yes” and “no”.
| Component | Form | Status |
|---|---|---|
| Callouts | > [!NOTE] |
stable |
| Galleries | ```gallery fence |
stable |
| PlantUML | ```plantuml fence |
opt-in |
The image shortcode |
— | removed |
In lists and steps
- Install Hugo Extended ≥ 0.168.0
- Create a site from OINK Starter and change
baseURLinhugo.yaml hugo serverto preview port 1313
On cards
A card has its own badge parameter. This plain text appears to the right of the title.
The card body can also contain badge shortcodes.
One hugo mod get and you are done needs Go
Builds on a machine with no network manual upgrades
Clickable badges
With link, the badge becomes an <a> element. Site paths, relative paths, http(s):, and mailto: are supported.
Current version v0.5; for the upgrade steps see Upgrading.
An invalid link warns and is removed, rendering a plain badge.
Output
| Output | Shape |
|---|---|
| HTML | <span class="td-badge td-badge--<tone>">, or <a class="td-badge …"> when linked |
| Same as HTML, a static inline element | |
| Markdown | **Beta**, or [**Beta**](/…) when linked |
| RSS | Same as print |
Badges load no JavaScript. A badge is not a live region, so adding one does not produce a screen reader announcement.
Parameter reference
text, ,- Required, non-empty. What the reader sees
tone, ,neutralinfosuccesswarningdangerlink, ,- Turns the badge into a link
Use named parameters only. There is no icon, class, color, outline, or size parameter.
Invalid input warns and uses a safe fallback: unknown parameters are ignored, empty text renders nothing,
invalid tone uses neutral, and unsafe links are removed.
Limits
- Tone supplements the text. The text must state the status.
{{< badge text="🔴" >}}gives a screen reader no meaning. - There is no icon parameter. If you need an icon, use cards or a callout.
- Keep text short. Badges follow names without wrapping. Put text longer than a few words in the prose.
- Use no more than three badges in one place. More badges make the associated name difficult to find.
- Badges use only shortcodes. There is no native Markdown form. Plain Markdown readers show them as bold text.
Related
- Cards —
cardhas abadgeparameter of its own - File trees —
toneuses the same vocabulary - Keys — the other inline shortcode
- Callouts — when the status needs explaining
20 - Kbd
kbd with one key name per parameter to display a semantic key sequence. Instructions remain readable in print and Markdown.Use keys to show shortcuts and chords separately from prose. Supply one positional parameter per key. The theme draws keycaps, adds separators, and gives screen readers a readable sequence. Use inline code for command names, flags, and text to type. They are not physical keys.
Shortest form
Press Ctrl with K to open the command palette.
Quote each positional parameter and use one parameter per key. Missing, empty, or named parameters warn. Ordinary previews do not render invalid keys. Review the warning and rendered fallback before publication.
A single key
Each parameter represents one key. Write symbol keys as displayed on the keyboard.
Escape closes a dialog; / jumps to search; t toggles light and dark; l cycles through languages.
Chords
Multiple parameters display in order, separated by +.
Assistive technology receives a localized connector instead of the visible plus sign.
⌘ with Shift with P and Ctrl with Shift with P are the same action. For a literal plus, treat it as a key of its own: Ctrl with + zooms the page in.
Platform differences
Use the reader’s keyboard labels: ⌘ on macOS and Ctrl on Windows and Linux.
Never combine platform labels in one sequence. Labels such as Ctrl/⌘ cannot be read aloud correctly.
Name the platform in the sentence or use tabs.
On macOS press ⌘ with K; on Windows and Linux, Ctrl with K.
Shortcut tables
Keys are common in cheatsheets. This table shows some global keys that the site supports:
| Key | Action |
|---|---|
| Ctrl with K | Open the command palette (⌘ with K on macOS) |
| / | The palette’s full search state |
| t | Toggle light and dark |
| q / e | Previous / next page |
| w s a d | Move, collapse and expand in the sidebar tree |
| Escape | Leave the sidebar tree for the article |
The complete list of site-wide shortcuts is in keyboard navigation.
In steps
- Press Ctrl with K to open the command palette
- Type
>for the command-only state, or type a keyword to search - Select with ↑ ↓ and press Enter to go
- Escape closes it and focus returns where it was
Raw <kbd> tags
Raw <kbd> tags get the same styles, and GitHub also displays them.
With raw tags, you maintain separators and accessible sequences yourself. Either form works for single keys. Use the shortcode for chords.
Press F5 to reload. In an editor, Ctrl+S saves.
Output
| Output | Shape |
|---|---|
| HTML | <span class="td-kbd-sequence"> around one <kbd> per key; the visible + is hidden from screen readers, which get a localized connector |
| Same as HTML, static | |
| Markdown | Plain text: Ctrl + K, ⌘ + Shift + P |
| RSS | Same as print |
The instruction remains readable without CSS or JavaScript.
Parameter reference
Positional 1..n, ,- At least one; each must be non-empty and quoted; order is display order
Only positional parameters are supported. There is no separator, label, platform, class, or size parameter.
Hugo cannot combine positional and named parameters in one shortcode call.
Limits
- Each sequence represents keys pressed together. For consecutive keys, use two
kbdcalls and describe the order: press Escape, then Enter. - There is no platform detection. The page never replaces
Ctrlwith⌘based on the visitor’s operating system. - There is no key mapping or recording. Menu paths, gestures, and gamepads are outside the scope.
- Missing quotes fail the build.
Ctrlin{{< kbd Ctrl K >}}is not a string parameter. - Do not use keys for commands.
hugo serveris inline code;Ctrlis a key.
Related
- Keyboard navigation — the full shortcut list and its switches
- Command palette — what Ctrl with K opens
- Badges — the other inline shortcode
- Steps — the container for instructions
21 - Includes
include inserts another file’s content into the page. param prints a page or site parameter. comment removes a passage.
Use them for fragments or constants shared by multiple pages.
For example, use include for installation steps on three pages and param for a version number on dozens of pages.
You then edit one source. Keep content used by only one page on that page.
Shortest form
include takes one required parameter, file:
The included file contains ordinary Markdown under assets/:
The result is the same as writing the content here. The code block has a copy button, and the callout displays normally.
Installing OINK into an existing Hugo site takes three commands:
hugo mod get needs Go on the machine; an offline archive or a submodule does not.
The current release is v1.5.1.
An included file is not a separate page. It has no sidebar entry, translation pairing, or URL.
Where the file comes from
file resolves in this order. The first match takes precedence:
| Order | Looked up as | Written as |
|---|---|---|
| 1 | A page resource — a file in this page’s bundle | file="config.yaml" |
| 2 | A global resource under assets/ |
file="snippets/dsn.txt" |
| 3 | A file under content/: a leading / is the content root, otherwise relative to the page’s directory |
file="notes/caveat.md", file="/shared/notice.md" |
If no source matches, or the path contains .., the include warns and emits nothing. Review the warning and rendered fallback before publication.
Include reads only from content/ and assets/.
Markdown fragments are read as source. Use the file’s actual disk name.
Page resources in step 1 have one exception. Hugo attaches language-suffixed resources such as notice.zh.md under a name without the language suffix.
Requesting notice.md from a bundle therefore gives include rendered HTML instead of source.
The Markdown output can then contain <div class="td-code">.
Under assets/ and content/, the written name identifies the exact file. Non-Markdown files (.yaml, .sh, .txt) have no such distinction.
Each language of this page includes its own fragment.
English uses assets/parts/install-oink.md; Chinese uses assets/parts/install-oink.zh.md.
Storing fragments under assets/ instead of the page bundle lets both languages retrieve source with the written filename.
Including code files
code=true displays the file as a code block. lang= sets its highlighting language.
Use a real repository file to keep the documentation consistent with that file.
Included code and fences share the same pipeline for highlighting, line numbers, and copying.
You cannot pass fence attributes such as title=, collapse, or hl_lines= through include.
If you need them, write an ordinary code block.
What a fragment can contain
Fragments use page-level Markdown in the current page’s context. They support callouts, tables, lists, images, steps, and shortcodes.
The example fragment’s last line, “The current release is v0.8.1”, comes from {{< param version >}} expanded on this page.
If two pages include the same fragment, each renders it separately. Each generates its own heading anchors and code-block IDs without collisions.
Use fragments for installation commands, connection strings, support matrices, and legal notices that must change on all pages together. Keep content used by only one page on that page.
Printing a site parameter
param prints one parameter. It checks page front matter first, then site configuration, following Hugo’s .Param rule.
This site publishes v1.5.1, copyright from 2026,
and this page’s front matter says pigsty_pg_major: 18, which reads back as 18.
Join nested keys with .. For example, copyright.from_year reads params.copyright.from_year.
Missing parameters and values that are maps or lists warn and print nothing. Review the warning and rendered fallback before publication.
Parameters inside commands, tables and links
param emits escaped plain text. It can appear in code fences, table cells, or link targets.
For example, use it for a version number in an installation command:
| Item | Value |
|---|---|
| Current version | v1.5.1 |
| Hugo floor | 0.168.0 |
Configuration defines site parameters. Front matter defines page parameters.
Notes deleted at build time
A comment body appears in none of the four outputs: HTML, print, Markdown, or RSS.
HTML comments remain in page source and reach llms.txt.
Since PostgreSQL 18, pg_stat_io breaks out WAL statistics.
Verify the dashboards on a test database before upgrading.
A comment exists between those paragraphs, but it does not appear in the page source.
Output
| Output | include (Markdown) |
include code=true |
param |
comment |
|---|---|---|---|---|
| HTML | The fragment renders as normal content | Highlighted code block + copy button | Escaped plain text | nothing |
| As HTML | As HTML, without the copy button | As HTML | nothing | |
| Markdown | The fragment’s source, as written | A source fence | The value itself | nothing |
| RSS | As HTML | As HTML | As HTML | nothing |
Markdown output preserves fragment source instead of rendered HTML. Its shortcodes remain as {{< param version >}}.
This is the intended source-preserving behavior. None of these three shortcodes loads a script.
Parameter reference
include (named parameters only):
file, ,- Resolution order in Where the file comes from; a
.., missing file, or empty value warns and emits nothing code, ,truerenders as a code block; quotedcode="true"warns and includes ordinary contentlang, ,- Code language; without
code=trueit warns and is ignored
Other parameter names warn and are ignored. The message identifies the file and line.
param (one positional parameter):
parameter name, ,- Nested keys join with
.; page front matter first, then siteparams; missing or non-scalar values warn and print nothing
comment takes no parameters. Use opening and closing shortcodes.
All content between {{< comment >}} and {{< /comment >}} is discarded.
Limits
includeis not a template. You cannot pass variables, include conditionally, or supply code-block fence attributes such astitle=orcollapse. For platform variants, create two fragments and use tabs.- You maintain fragment languages.
includehas no language fallback and uses the exact written path. You can share a fragment across languages, as this page’s Chinese translation includes the same English file. Alternatively, write one fragment per language and use its path on the corresponding page. paramprints only scalars. Put structured data, such as version matrices or download lists, indata/and use the matching component.commentdiscards content on every build. To temporarily unpublish a whole page, usedraft: true.- Do not use
includeto create an index page. If a page needs ten fragments, give readers ten links instead.
Related
- Code blocks — every fence attribute, and the pipeline
include code=truereuses - Tabs — per-platform or per-language fragments
- Configuration — the site parameters
paramcan reach - Front matter — page parameters, which win over site configuration
22 - Asciinema
asciinema displays a .cast recording in a terminal player. Use it for command-line procedures.
Readers can select and copy the terminal text. The six-minute installation recording on this page is about 196 KB.
This component plays only terminal recordings. Use screenshots or video for graphical interfaces.
The theme includes the player and styles. It downloads nothing at build time and contacts no CDN at runtime.
The runtime loads only in HTML output on pages that use the component.
Shortest form
file is the only required parameter:
images/install.cast — /images/install.cast
The recording shows a single-node Pigsty installation on Debian in a 120×36 terminal. It lasts about 6 minutes and 42 seconds.
Download the sample recording to static/images/install.cast in your site. Write its path from the site root.
For a file under assets/, use a relative path. The theme checks resources first, then treats the value as a site-root path.
If you omit title, the window title shows the value of file.
Window title and theme
title sets the window title. theme sets the colors:
Pigsty single-node install — /images/install.cast
theme defaults to auto and follows the site’s color scheme. It uses td-light in light mode and td-dark in dark mode.
When the reader changes modes, the player remounts in place. To fix the terminal palette, use a player theme:
asciinema, dracula, gruvbox-dark, monokai, nord, seti, solarized-dark, solarized-light, or tango.
You can also use the theme’s td-light / td-dark. A fixed theme does not follow the site’s color scheme.
solarized-light does not provide usable contrast on a dark site. The player uses the same code font as the site’s code blocks.
Speed, start point and poster
Three parameters control the initial playback state. speed sets the rate, startAt skips the opening, and poster sets the frame before playback.
From 60 seconds in, at double speed — /images/install.cast
speed and startAt take numbers (seconds). poster uses the player’s npt: time notation.
For example, npt:1:30 means one minute and thirty seconds. The player above shows the frame at 90 seconds and starts playback at 60 seconds.
idleTimeLimit limits silent intervals to N seconds. This recording already limits idle time through idle_time_limit: 0.5 in its .cast header.
It needs no additional limit. Only recordings made without an idle limit need this setting.
Size and fit
By default, the player scales to the container width (fit="width"). It reads the terminal dimensions from the .cast header.
Use cols / rows to override those dimensions:
Only 16 rows tall — /images/install.cast
Dimensions smaller than the recording clip its content. The example above shows 16 of the 36 rows.
Use cols / rows to correct incorrect header dimensions. Do not use them to control layout.
To make the player shorter, record again in a smaller terminal.
fit accepts four values: width, the default, scales to width; height scales to height; both fits both axes.
none disables scaling, so a wide terminal overflows.
Looping and preloading
loop restarts playback at the end. preload fetches the .cast when the page loads, so playback starts without waiting:
Looping: the first minute after login — /images/install.cast
autoplay="true" starts playback when the page opens. This is not recommended.
The “reduce motion” preference disables only player control transitions. It does not stop autoplay.
If autoplay is necessary, use loop, keep the clip very short, and use only one clip per page.
Inside steps
Put the recording beside its step. The text gives the action. The recording shows the result.
-
Install the dependencies and fetch the installer:
-
Run the install; the recording plays the process at four times speed:
pig install — /images/install.cast
-
Open
http://<node address>:3000and sign in to Grafana withadmin / pigsty.
A page can hold several players, and the script and styles load once.
Recording a cast file
The theme plays recordings but does not create them. Record with asciinema.
Use asciinema rec --idle-time-limit=2 --cols=100 --rows=28 install.cast, then check locally with asciinema play install.cast.
- Keep the terminal under 100 columns so it stays readable on narrow screens. Run
clearbefore you start. - Remove secrets before recording. A
.castis plain text, so every recorded character can be searched. Check the file before committing. - Put the file at
static/images/install.castand usefile="images/install.cast".assets/images/install.castworks with the same value. Page-bundle resources are not resolved. Commit the recording instead of using a.castURL from another site.
Output
| Output | Shape |
|---|---|
| HTML | A <div class="td-asciinema"> window frame plus the player; the player CSS/JS and the runtime load on demand, once per page, and only in this output |
| A labelled static link showing the recording’s address; no player, no runtime | |
| Markdown | A plain Markdown link, [title](/images/install.cast) — no component markup, no configuration block |
| RSS | The same plain link |
A recording must never be the only source of information. Write the key commands and output beside it as text or code.
Offline readers, consumers of llms.txt, and readers of printed pages receive the link and prose. They do not receive the terminal session.
Parameter reference
file, ,- Named, or the first positional parameter; looked up as a global resource first, then as a site-root path; a full URL with a scheme is passed through unchanged
title, ,- The window title
theme, ,autofollows the site’s colour scheme; ortd-lighttd-darkasciinemadraculagruvbox-darkmonokainordsetisolarized-darksolarized-lighttangofit, ,widthheightbothnone; anything else warns and useswidthcols/rows, ,- Override the terminal size; smaller than the recording clips it
speed, ,- Playback rate
startAt, ,- Where playback starts
idleTimeLimit, ,- Longest a silent stretch plays for
poster, ,- The frame shown before playback,
npt:mm:ss autoplay, ,- Play as the page opens; not recommended
loop, ,- Replay at the end
preload, ,- Fetch the
.castwhen the page loads pauseOnMarkers, ,- Pause at chapter markers
markers, ,- Chapter markers; see the limits — the labels do not reach the player today
Boolean-like parameters compare their value with the text true. Both loop="true" and loop=true enable the option. Other values disable it.
Other invalid values warn and use a fallback: invalid fit uses width, nonnumeric speed uses 1, nonnumeric startAt uses 0,
and nonnumeric cols, rows, idleTimeLimit, and marker times are ignored.
Limits
markerslabels are lost. The theme converts thetime:labellist to a one-dimensional array, but the player accepts only pairs. The timeline therefore has unlabeled markers. A nonnumeric marker time warns and is skipped. If you need chapters, write a list beside the recording.- The player needs JavaScript. With browser scripts disabled, only the window frame remains. Print, Markdown, and RSS provide a link instead. See Output.
- Recordings are not searchable. The site index covers page text, so it cannot find commands that appear only in recordings.
- Do not use a remote
.cast. Althoughhttpandhttpsaddresses are accepted, they make the page depend on another site. Other schemes, protocol-relative//hostaddresses, and empty values warn and render nothing. - Keep clips short. Few readers finish recordings longer than five or six minutes. Split long procedures into short recordings, each with its own text.
Related
- Code blocks — the key commands and output, copyable
- Steps — the recording beside the step it belongs to
- Images — static screenshots: recordings for terminals, screenshots for graphical interfaces
- Include — when the same commands appear on several pages