Skip to content

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

Return to the regular view of this page.

Components

Find each writing component, from simple examples to detailed examples, with its output matrix, parameters, and limits.

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, card and field bodies, files loaded by include, and Book fig / tbl / eg bodies.
  • 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:

hugo.yml
markup:
  goldmark:
    renderer:
      unsafe: true # keep HTML that content emits
    parser:
      attribute:
        block: true # enable {…} attribute lines
      wrapStandAloneImageWithinParagraph: false # standalone images are not wrapped in <p>
  • renderer.unsafe: true keeps raw HTML in content. Goldmark drops it by default. Without this setting, HTML inside component bodies disappears.
  • parser.attribute.block: true enables attribute lines. Without it, {.steps} and {caption="…"} appear as text.
  • parser.wrapStandAloneImageWithinParagraph: false prevents <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 ![alt](oink.webp) 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 ![alt](arch.drawio.svg) 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.js only if a block on the page has a copy or fold control. A file tree loads filetree.js only 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_zoom and 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

Write notes, warnings, and collapsible asides with colors, icons, and titles. Use > [!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

Source
> [!NOTE]
> Hugo Modules need Go on the machine; an offline archive does not.
Note

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.

Source
> [!TIP]
> `hugo server -D` previews drafts.

> [!IMPORTANT]
> The floor is Hugo Extended 0.168.0; anything older fails the build outright.

> [!WARNING]
> `hugo --cleanDestinationDir` empties `public/`.

> [!CAUTION]
> The first build after deleting `resources/_gen` is much slower.

> [!SUCCESS]
> Build passed with reviewed warnings — ship it.

> [!DANGER]
> Never commit `go.work`.

> [!QUESTION]
> Should the site have comments? See [enabling comments](/docs/admin/comments/).

> [!EXAMPLE]
> `pgsty.com` is a documentation site built from callouts and tables alone.

> [!QUOTE]
> Documentation is a love letter that you write to your future self.
Tip

hugo server -D previews drafts.

Important

The floor is Hugo Extended 0.168.0; anything older fails the build outright.

Warning

hugo --cleanDestinationDir empties public/.

Caution

The first build after deleting resources/_gen is much slower.

Success

Build passed with reviewed warnings — ship it.

Danger

Never commit go.work.

Question

Should the site have comments? See enabling comments.

Example

pgsty.com is a documentation site built from callouts and tables alone.

Quote

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.

Source
> [!WARNING] Rewrites `public/`
> Check that `baseURL` points at the production domain before a production
> build, or every absolute link will be wrong.
Rewrites 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.

Source
> [!TIP] Three commands to a live preview
>
> 1. Clone: `git clone https://github.com/pgsty/oink-starter my-docs`
> 2. Enter the directory and preview:
>    ```bash
>    cd my-docs && hugo server
>    ```
> 3. Open <http://localhost:1313/>
>
> | Port | Purpose |
> | --- | --- |
> | 1313 | Hugo development server |
Three commands to a live preview
  1. Clone: git clone https://github.com/pgsty/oink-starter my-docs
  2. Enter the directory and preview:
    cd my-docs && hugo server
  3. 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.

Source
> [!NOTE]- Why is Go needed?
> Hugo downloads themes through Go's module system (`hugo mod get`). A submodule
> or an offline archive works without Go installed.

> [!TIP]+ Open by default, but the reader can close it
> The closed state is not remembered; a reload returns to the default.
Why is Go needed?

Hugo downloads themes through Go’s module system (hugo mod get). A submodule or an offline archive works without Go installed.

Open by default, but the reader can close it

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.

Source
> [!DETAILS] Full `hugo version` output
> ```text
> hugo v0.168.0+extended+withdeploy darwin/arm64
> ```
Full hugo version output
hugo v0.168.0+extended+withdeploy darwin/arm64

Custom 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.

Source
> [!TIP] PostgreSQL 18 is supported
> Pigsty v4 installs PostgreSQL 18 by default.
{icon="fa-solid fa-database"}
PostgreSQL 18 is supported

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.

Source
> [!WARNING] Back up before upgrading
> A theme version bump can change how a page renders.
>
> > [!TIP]- How to back up
> > `git tag pre-upgrade` is enough — rolling back is `git checkout pre-upgrade`.
Back up before upgrading

A theme version bump can change how a page renders.

How to back up

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.

Source
> [!NOTICE] Not a valid type
> The marker stays on the page to tell you so.

[!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 only icon and class. See the table below.

Output

Output Shape
HTML Static types are <div class="td-callout" role="note">; collapsible types are a native <details> + <summary>
Print 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 , enum , default—
NOTE TIP IMPORTANT WARNING CAUTION SUCCESS DANGER QUESTION EXAMPLE QUOTE DETAILS; case-insensitive; an unknown value renders as a plain blockquote
± , - / + / none , defaultnone
- collapses closed, + collapses open; bare DETAILS is closed
Title , inline Markdown , defaultthe localized type name
On the same line as the marker

The attribute line {…}, immediately after the blockquote:

icon , Font Awesome class pair , defaultthe type’s icon
For example fa-solid fa-database; DETAILS has no default icon
class , space-separated classes , default—
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.
  • 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

Use Markdown image syntax and attributes for captions, sizing, zoom, links, numbering, and Hugo image processing.

Write images with Markdown’s ![alt text](source "title") 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

Source
![The OINK documentation shell: sidebar, article and table of contents](oink-shell.webp)
The OINK documentation shell: sidebar, article and table of contents

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) ![…](oink-shell.webp) A screenshot only this page uses; it travels with the page and is shared by translations
Current section bundle (_index.md and its resources) ![…](post/image.png) Images belonging to a section; use the resource path relative to that section
Global resource assets/images/… ![…](images/logo/oink.webp) Images several pages share, especially ones needing processing (resize / crop)
Static directory static/images/… ![…](/images/hero-light.webp) Large images and downloads that need no processing; supply width/height where the theme cannot measure them
Remote URL ![…](https://example.com/a.png) 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.

Source
This little one ![shell thumbnail](oink-mini.webp) sits inside a sentence — an inline image.

![shell thumbnail](oink-mini.webp)
{width="100" height="64"}

This image shell thumbnail is inside a sentence, so it is inline.

shell thumbnail

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.

Note

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.

Source
![Release card: version, publication date and asset buttons](release-note.webp)
{caption="The release card uses the page's release_url and date"}
Release card: version, publication date and asset buttons
The release card uses the page's release_url and date

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.

Source
![The OINK home page illustration (light)](/images/hero-light.webp)
{width="450" height="300" caption="A 900×600 illustration from static/images/ shown at half size"}
The OINK home page illustration (light)
A 900×600 illustration from static/images/ shown at half size

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.

Source
![shell thumbnail](oink-shell.webp)
{command="Fit" options="300x150" caption="Fit 300x150: scaled to fit inside a 300×150 box"}

![the left half of the shell](oink-shell.webp)
{command="Fill" options="300x150 Left" caption="Fill 300x150 Left: fills the box, cropped from the left"}
shell thumbnail
Fit 300x150: scaled to fit inside a 300×150 box
the left half of the shell
Fill 300x150 Left: fills the box, cropped from the left

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.

Two forms, for different purposes:

  • No caption, and the image itself is the link: wrap it in a Markdown link, [![alt](src)](href).
  • A captioned figure that is clickable as a whole: add link="…" to the attribute line (which requires caption or num).
Source
[![Go to the highlights page](oink-shell.webp)](/docs/about/features/)

![Release card](release-note.webp)
{caption="Click the image for the releases and downloads guide" link="/docs/write/releases/"}

Go to the highlights page

Release card
Click the image for the releases and downloads guide

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.

Source
![Release card](release-note.webp)
{#fig-release num="2-1" caption="The release card: version, date and assets"}

See [Figure 2-1](#fig-release).
Release card
Figure 2-1 The release card: version, date and assets

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.

hugo.yml
params:
  ui:
    image_zoom: true
One page's front matter: off for this page only
image_zoom: false

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.

Source: a decorative image does not zoom
![](oink-shell.webp)
{width="150" height="75"}

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:

Source
![Sidebar (light)](sidebar-light.webp)
{class="only-light"}

![Sidebar (dark)](sidebar-dark.webp)
{class="only-dark"}
assets/scss/_styles_project.scss
html[data-bs-theme="dark"] .only-light,
html:not([data-bs-theme="dark"]) .only-dark { display: none; }

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
Print As HTML, with the zoom controls removed
Markdown ![alt](src) 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 , plain text , default—
Its presence makes a figure; not parsed as Markdown
#id , identifier , defaultfig-<num> when num is set
[A-Za-z][A-Za-z0-9_.:-]*; the anchor and the Book target ID
num , string , default—
[0-9A-Za-z.-]+; registers a Book figure target and prefixes the caption with “Figure N.”
width / height , positive integer , defaultthe resource’s intrinsic size
Overrides the size; static and remote images use it to avoid layout shift
command , enum , default—
Fit, Resize, Fill, Crop; must accompany options; page and global resources only
options , string , default—
Hugo image processing options such as 600x300, 300x150 Left, 800x webp q80
link , URL , default—
Wraps the figure in a link; requires caption or num; a linked image does not zoom
class , class list , default—
Passed through for the site’s CSS
data-* / aria-* , string , default—
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.
  • title is not a caption. The c in ![a](b "c") is a hover tooltip.
  • Only resources support processing. Move images that need processing from static/ to the page bundle or assets/.
  • Remote images are never downloaded at build time.
  • Zoom has no drag, pan, or previous / next controls. Use a gallery for related images.
  • Gallery — a set of images sharing one zoom dialog
  • Books — the list of figures and xref cross-references
  • Brand and appearance — where the site logo and favicon go
  • Cards — images on cards

3 - Code Blocks

Use a Markdown fence and attributes for titles, exact copying, line numbers, highlighting, wrapping, folding, and line links.

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

Source
```sql
SELECT datname, numbackends FROM pg_stat_database ORDER BY numbackends DESC;
```
SELECT datname, numbackends FROM pg_stat_database ORDER BY numbackends DESC;

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:

Source
```diff {title="a change to hugo.yml"}
 params:
   ui:
-    sidebar_menu_compact: true
+    sidebar_menu_compact: false
     sidebar_menu_foldable: true
```
a change to hugo.yml
 params:
   ui:
-    sidebar_menu_compact: true
+    sidebar_menu_compact: false
     sidebar_menu_foldable: true

Filename titles

title adds a visible title bar, usually containing a filename or path. It also sets the block’s accessible name.

Source
```yaml {title="hugo.yml"}
markup:
  goldmark:
    parser:
      attribute:
        block: true
    renderer:
      unsafe: true
```
hugo.yml
markup:
  goldmark:
    parser:
      attribute:
        block: true
    renderer:
      unsafe: true

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.

Source
```ini {title="postgresql.conf" lineNos="inline" lineNoStart=120 hl_lines="2 4-5"}
shared_buffers = 8GB
max_connections = 200
work_mem = 64MB
wal_level = replica
max_wal_senders = 10
```
postgresql.conf
120shared_buffers = 8GB
121max_connections = 200
122work_mem = 64MB
123wal_level = replica
124max_wal_senders = 10

lineNos="table" puts numbers in a separate column. The copy button removes line numbers in both modes:

Source
```bash {title="deployment in three commands" lineNos="table"}
./configure -c rich
./install.yml
pig ext install pg_duckdb
```
deployment in three commands
1
2
3
./configure -c rich
./install.yml
pig ext install pg_duckdb

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.

Source
```text {title="config/artifacts.env" wrap=true}
ARTIFACT_URL=https://repo.pigsty.io/pkg/infra/v3.6.0/infra-pkg-v3.6.0.el9.x86_64.tgz
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2
```
config/artifacts.env
ARTIFACT_URL=https://repo.pigsty.io/pkg/infra/v3.6.0/infra-pkg-v3.6.0.el9.x86_64.tgz
CHECKSUM=sha256:6d3dce4f7acb18f586469adcb80ab35f3e859f9837786e151cfbc2b3c0f587b2

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.

Source
```yaml {title="hugo.yml" collapse=8}
baseURL: https://oink.pgsty.com/
title: OINK
defaultContentLanguage: en
languages:
  en:
    languageName: English
    weight: 1
  zh:
    languageName: 简体中文
    weight: 2
params:
  offline_search: true
  ui:
    sidebar_menu_foldable: true
```
hugo.yml
baseURL: https://oink.pgsty.com/
title: OINK
defaultContentLanguage: en
languages:
  en:
    languageName: English
    weight: 1
  zh:
    languageName: 简体中文
    weight: 2
params:
  offline_search: true
  ui:
    sidebar_menu_foldable: true

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.

Source
```console
$ pig ext list duckdb
name       version  category
pg_duckdb  1.0.0    OLAP
$ pig ext install pg_duckdb
INFO installing pg_duckdb
```
$ pig ext list duckdb
name       version  category
pg_duckdb  1.0.0    OLAP
$ pig ext install pg_duckdb
INFO installing pg_duckdb

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:

Source
```yaml {title="counter-example: an invalid boolean" copy=false}
params:
  ui:
    image_zoom: sometimes   # wrong: use true or false
```
counter-example: an invalid boolean
params:
  ui:
    image_zoom: sometimes   # wrong: use true or false

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.

To link “see line 3”, give the fence an explicit id, then enable anchorLineNos=true. Line numbers become links of the form #<id>-<line>.

Source
```sql {id="ex-explain" title="explain.sql" lineNos="table" anchorLineNos=true}
EXPLAIN (ANALYZE, BUFFERS)
SELECT relname, n_live_tup
FROM pg_stat_user_tables
WHERE n_live_tup > 1000
ORDER BY n_live_tup DESC;
```

Jump to [line 4](#ex-explain-4).
explain.sql
1
2
3
4
5
EXPLAIN (ANALYZE, BUFFERS)
SELECT relname, n_live_tup
FROM pg_stat_user_tables
WHERE n_live_tup > 1000
ORDER BY n_live_tup DESC;

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

Source
```sql {num="4-1" caption="Bloat ratio per table" #eg-bloat}
SELECT schemaname, relname, n_dead_tup, n_live_tup
FROM pg_stat_user_tables
WHERE n_dead_tup > n_live_tup * 0.2;
```

See {{< xref eg="4-1" anchor="eg-bloat" >}}.
Example 4-1 Bloat ratio per table
SELECT schemaname, relname, n_dead_tup, n_live_tup
FROM pg_stat_user_tables
WHERE n_dead_tup > n_live_tup * 0.2;

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.

Source
```bash {tab="Homebrew" group="oink-install" value="brew"}
brew install hugo
```
```bash {tab="APT" value="apt"}
sudo apt install hugo
```
Homebrew
brew install hugo
APT
sudo apt install hugo

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
Print 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 , non-empty string , defaultnone
The visible title bar (usually a filename) and the accessible name
filename , non-empty string , defaultnone
Historical alias of title; both together warn and use filename
copy , all command true false , defaultcommand for session lexers, all otherwise
true is all; command is allowed only on console/shell-session
wrap , boolean , defaultfalse
Visual wrapping, source unchanged; mutually exclusive with table line numbers
collapse , positive integer , defaultnone
Lines shown initially; ignored when the block is shorter
label , non-empty string , defaultderived from the title
Accessible name, not displayed; mutually exclusive with aria-label
id , non-empty token , defaultgenerated
Stable block ID and line-anchor prefix; no whitespace
tab , non-empty string , defaultnone
Tab label, see Tabs; mutually exclusive with num
group , ^[a-z][a-z0-9_-]*$ , defaultnone
On the first fence of a set; enables hash / sync / persistence; requires tab
value , ^[a-z0-9][a-z0-9_-]*$ , defaultnone
Required on every fence of a group, forbidden without one; requires tab
num , [0-9A-Za-z.-]+ , defaultnone
Numbered example (Book eg); must appear with caption
caption , plain text , defaultnone
The numbered example’s caption; must appear with num
class , class list , defaultnone
Appended to the .td-code root element
data-* / aria-* / role , string , defaultnone
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 , false inline table , defaultfalse
Line-number style; table is mutually exclusive with wrap=true
lineNoStart , positive integer , default1
First displayed number; does not affect how hl_lines counts
hl_lines , lines and ranges , defaultnone
For example "2 4-5", counted over the source lines in the fence
anchorLineNos , boolean , defaultfalse
Line numbers become anchor links prefixed with the block’s id
tabWidth , positive integer , defaultHugo’s default
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 diff fence. Chroma’s .gi/.gd style added and removed lines.
  • copy="command" supports only session lexers. Other languages warn and copy everything.
  • Generated IDs are not permanent links. Write id for a link that you plan to share.
  • mermaid, math, chem, markmap, plantuml, echarts, infographic, checksums, filetree, and gallery are not code blocks. Each has its own render hook, without a code shell or copy button.
  • 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

Add {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.

Source
```bash {tab="Homebrew"}
brew install hugo
```
```bash {tab="Debian / Ubuntu"}
sudo apt install hugo
```
Homebrew
brew install hugo
Debian / Ubuntu
sudo apt install hugo

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.

Source
```bash {tab="npm" group="pkgmgr" value="npm"}
npm create hugo-site@latest
```
```bash {tab="pnpm" value="pnpm"}
pnpm create hugo-site
```
```bash {tab="Yarn" value="yarn"}
yarn create hugo-site
```
npm
npm create hugo-site@latest
pnpm
pnpm create hugo-site
Yarn
yarn create hugo-site

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.

Source
```bash {tab="npm" group="pkgmgr" value="npm"}
npm run build
```
```bash {tab="pnpm" value="pnpm"}
pnpm build
```
npm
npm run build
pnpm
pnpm build

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.

Source
| Parameter | Default |
| --- | --- |
| `shared_buffers` | 25% RAM |
| `max_connections` | 100 |
{tab="PostgreSQL 18" group="pgver" value="pg18"}

| Parameter | Default |
| --- | --- |
| `shared_buffers` | 128MB |
| `max_connections` | 100 |
{tab="PostgreSQL 13" value="pg13"}
PostgreSQL 18
Parameter Default
shared_buffers 25% RAM
max_connections 100
PostgreSQL 13
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.

Source
```yaml {tab="YAML" title="hugo.yml" group="conffmt" value="yaml"}
params:
  ui:
    sidebar_menu_foldable: true
```
```toml {tab="TOML" title="hugo.toml" value="toml"}
[params.ui]
sidebar_menu_foldable = true
```
YAML
hugo.yml
params:
  ui:
    sidebar_menu_foldable: true
TOML
hugo.toml
[params.ui]
sidebar_menu_foldable = true

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.

Source
```ini {tab="on its own"}
listen_addresses = '*'
```
on its own
listen_addresses = '*'

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.

Source
{{< tabs group="deploy" default="pages" label="Deployment target" >}}
{{< tab label="GitHub Pages" value="pages" >}}
The repository ships `.github/workflows/`; a push to `main` builds and publishes.

> [!NOTE]
> `baseURL` has to be the repository's Pages address.
{{< /tab >}}
{{< tab label="Cloudflare Pages" value="cloudflare" >}}
Connect the repository in the Cloudflare dashboard; the build command is:

```bash
hugo --gc --minify
```
{{< /tab >}}
{{< /tabs >}}

The repository ships .github/workflows/; a push to main builds and publishes.

Note

baseURL has to be the repository’s Pages address.

Connect the repository in the Cloudflare dashboard; the build command is:

hugo --gc --minify

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
Print 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 , non-empty string , defaultnone
The visible label; on a lone block it is simply that block’s title
group , ^[a-z][a-z0-9_-]*$ , defaultnone
On the first block of a set; enables hash, in-page sync and persistence; requires tab
value , ^[a-z0-9][a-z0-9_-]*$ , defaultnone
Required on every block of a group, forbidden without one; requires tab

The tabs shortcode:

group , ^[a-z][a-z0-9_-]*$ , defaultnone
As above: hash, sync and persistence
default , a child’s value , defaultthe first child
The initially selected panel; requires group
label , plain text , defaultlocalized “Tabs”
Accessible name for the tab bar; not displayed

The tab shortcode:

label , plain text , required
The visible label
value , ^[a-z0-9][a-z0-9_-]*$ , 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 value loses 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.
  • group names are shared site-wide. Selecting pnpm on page A also selects pnpm in the same group on page B. Choose meaningful group names instead of tabs1.
  • 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

Add attributes to a GFM table for captions, compatibility matrices, field lists, numbering, or tabs. Wide tables scroll within their own regions.

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".

Source
| Component | Port | Purpose |
| --- | :---: | --- |
| PostgreSQL | 5432 | Database |
| Pgbouncer | 6432 | Connection pool |
| Patroni | 8008 | High-availability orchestration |
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”.

Source
| 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 |
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.

Source
| Item | Value |
| --- | --- |
| Theme version | v0.8.1 |
| Hugo floor | 0.168.0 Extended |
| Licence | Apache-2.0 |
{caption="Theme facts this site currently builds against"}
Theme facts this site currently builds against
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.

Source
| OS / PG | PG18 | PG17 | PG16 | PG15 | PG14 |
| --- | :---: | :---: | :---: | :---: | :---: |
| EL 9 | ✅ | ✅ | ✅ | ✅ | ✅ |
| EL 8 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Debian 13 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Ubuntu 24.04 | ✅ | ✅ | ✅ | ✅ | ❌ |
{.matrix}
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.

Source
| Language | Code | Sidebar | Search | TOC | Print | Status |
| --- | --- | --- | --- | --- | --- | --- |
| 简体中文 | `zh` | ✅ | ✅ | ✅ | ✅ | Reviewed |
| English | `en` | ✅ | ✅ | ✅ | ✅ | Reviewed |
{.full-width}
Language Code Sidebar Search TOC Print Status
简体中文 zh ✅ ✅ ✅ ✅ Reviewed
English en ✅ ✅ ✅ ✅ Reviewed

Technical wide tables

.wide in OINK 1.4.0

The 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.

Source
| 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. |
{.wide .expand}
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-width controls 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.
  • .wide controls 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 .wide use overflow-wrap: break-word, word-break: normal, and a soft max-width: 40ch body-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 .fields definition lists.

Expand selected tables

.expand in OINK 1.4.0

The 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.

Source
| Package | Version | Role |
| --- | --- | --- |
| `pgvector` | `0.8.1` | Vector similarity search |
| `pg_stat_statements` | `1.11` | Statement statistics |
{.wide .expand}
Example extension packages
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.

Source
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `offline_search` | boolean | `false` | Build the local search index |
| `page_width` | string | `normal` | Width of the reading column |
{.fields meta="type default"}
offline_search , boolean , defaultfalse
Build the local search index
page_width , string , defaultnormal
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>.

Source
| Isolation level | Dirty read | Non-repeatable read | Phantom read |
| --- | --- | --- | --- |
| Read committed | no | yes | yes |
| Repeatable read | no | no | yes |
| Serializable | no | no | no |
{#tbl-iso num="9-1" caption="Anomalies each PostgreSQL isolation level permits"}

See {{< xref tbl="9-1" anchor="tbl-iso" >}}.
Isolation level Dirty read Non-repeatable read Phantom read
Read committed no yes yes
Repeatable read no no yes
Serializable no no no
Table 9-1 Anomalies each PostgreSQL isolation level permits

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.

Source
| Directory | Contents |
| --- | --- |
| `content/` | Pages |
| `data/` | Landing and release data |
{tab="Content" group="repo-layout" value="content"}

| Directory | Contents |
| --- | --- |
| `assets/` | SCSS and image resources |
| `static/` | Files copied verbatim |
{tab="Assets" value="assets"}
Content
Directory Contents
content/ Pages
data/ Landing and release data
Assets
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
Print 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 , marker , defaultnone
Exceed the reading column and use the article canvas
.wide , marker , defaultnone
Sizes the inner table to max-content; suits technical tables with long identifiers
.expand , marker , defaultnone
Add an optional corner action for reading the table in a larger dialog
.matrix , marker , defaultnone
First column as row header, header and first column pinned, other cells centred
.fields , marker , defaultnone
Render as a definition list, see Fields
caption , plain text , defaultnone
Visible table caption; on .fields it labels the list
meta , role list , defaultnone
Names the meaning of the middle .fields columns: type required default -; requires .fields
#id , identifier , defaulttbl-<num> when num is set
[A-Za-z][A-Za-z0-9_.:-]*; lands on the <table>, or on the <figure> for a numbered table
num , string , defaultnone
[0-9A-Za-z.-]+; registers a Book table target and prefixes the caption with “Table N.”
tab / group / value , see Tabs , defaultnone
Adjacent tables become a tab set
class , class list , defaultnone
Left on the <table> for site CSS
data-* / aria-* , string , defaultnone
Passed through

style, on*, and other keys warn and are ignored.

Limits

  • .fields cannot be combined with .matrix, .full-width, .expand, or num. num and tab are mutually exclusive. group/value require tab, and meta requires .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/field shortcodes for multiple paragraphs, lists, or fences.
  • .matrix centering uses CSS. Explicit delimiter-row alignment takes precedence.
  • 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

Add {.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.

Source
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `offline_search` | boolean | `false` | Build the local search index and enable the command palette |
| `offline_search_max_results` | integer | `10` | Maximum number of search results |
| `page_width` | string | `normal` | Reading column width: `normal` `wide` `full` |
{.fields}
offline_search , Typeboolean , Defaultfalse
Build the local search index and enable the command palette
offline_search_max_results , Typeinteger , Default10
Maximum number of search results
page_width , Typestring , Defaultnormal
Reading column width: normal wide full

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.

Source
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `baseURL` | string | yes | | Site address, subpath included |
| `title` | string | yes | | Site name, shown in the navbar and the tab |
| `defaultContentLanguage` | string | | `en` | Default language; decides which language unprefixed paths belong to |
{.fields meta="type required default"}
baseURL , string , required
Site address, subpath included
title , string , required
Site name, shown in the navbar and the tab
defaultContentLanguage , string , defaulten
Default language; decides which language unprefixed paths belong to

The rules:

  • meta should specify one role per middle column: the total column count minus two. Too many or too few roles warns and ignores meta. Review the warning and rendered fallback before publication.
  • Every nonempty required cell means true. “yes”, “是”, and “✔” all display the untranslated required chip. Empty cells display nothing. Leave optional fields empty, because no and 否 also mean true.
  • type and default cells 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:

Source
| Environment variable | Type | Scope | Description |
| --- | --- | --- | --- |
| `HUGO_MODULE_WORKSPACE` | string | build | Points at `go.work` so the theme resolves from a local checkout |
| `HUGO_ENV` | string | build | Selects production mode; OINK fingerprints CSS/JS assets. Use `--minify` to minify HTML |
{.fields meta="type -"}
HUGO_MODULE_WORKSPACE , string , Scopebuild
Points at go.work so the theme resolves from a local checkout
HUGO_ENV , string , Scopebuild
Selects production mode; OINK fingerprints CSS/JS assets. Use --minify to 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.

Source
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `image_zoom` | boolean | `false` | Turn image zoom on |
| `featured_image` | string | `none` | Article image mode: `none`, `banner`, `wash` or `hero` |
{.fields caption="params.ui" id="zoom-params" meta="type default"}

params.ui

image_zoom , boolean , defaultfalse
Turn image zoom on
featured_image , string , defaultnone
Article image mode: none, banner, wash or hero

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.

Source
{{< fields label="Common pig flags" >}}
{{< field name="--config" type="path" required=true >}}
Path to the configuration file. Relative paths resolve against the working
directory.

When `PIG_CONFIG` is also set, the command-line flag wins.
{{< /field >}}
{{< field name="--log-level" type="string" default="info" >}}
Log level, from low to high:

- `debug`: print every remote call
- `info`: the default
- `error`: output only on failure
{{< /field >}}
{{< field name="--dry-run" type="boolean" default=false >}}
Print what would happen and change nothing:

```bash
pig ext install pg_duckdb --dry-run
```
{{< /field >}}
{{< /fields >}}

Common pig flags

--config , path , required

Path to the configuration file. Relative paths resolve against the working directory.

When PIG_CONFIG is also set, the command-line flag takes precedence.

--log-level , string , defaultinfo

Log level, from low to high:

  • debug: print every remote call
  • info: the default
  • error: output only on failure
--dry-run , boolean , defaultfalse

Print what would happen and change nothing:

pig ext install pg_duckdb --dry-run

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
Print 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 , marker , defaultnone
Required; renders the table as a field list
meta , role list , defaultnone
Space-separated type required default -; one per middle column; semantic roles cannot repeat
caption , plain text , defaultnone
Visible label and the list’s accessible name
id , identifier , defaultnone
ID of the outer container
class , class list , defaultnone
Passed through for site CSS
data-* / aria-* , string , defaultnone
Passed through

The fields shortcode:

label , non-empty string
Visible label; the same thing the table’s caption does
id , identifier
Container ID; no whitespace, quotes, <, > or &
class / data-* / aria-* , string
The same policy as the table attribute line

The field shortcode:

name , non-empty string , required
The field name
type , non-empty string
Type label such as boolean, string[], duration
required , boolean
true shows the untranslated required chip; defaults to false
default , scalar
String / boolean / integer / float; false, 0 and "" all display

Limits

  • The first column must be nonempty and unique within each table. Empty or duplicate names warn and skip the row.
  • .fields cannot be combined with .matrix, .full-width, or num. meta requires a table with .fields.
  • Table cells cannot contain block content. Use shortcodes for paragraphs, lists, and fences.
  • required and default remain 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.
  • 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

Add {.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.

Source
1. Install Hugo Extended
1. Clone OINK Starter
1. Start the local preview
{.steps}
  1. Install Hugo Extended
  2. Clone OINK Starter
  3. 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.

Source
1. Clone OINK Starter; it is the small project template for the theme.

   ```bash
   git clone https://github.com/pgsty/oink-starter my-docs
   cd my-docs
   ```

1. Start the local server.

   ```bash
   hugo server
   ```

   > [!NOTE]
   > The first build fetches the theme through the Go module proxy, which needs
   > Go on the machine.

1. Replace three things and it is your site.

   | Where | Replace with |
   | --- | --- |
   | `title` in `hugo.yml` | your site name |
   | `baseURL` in `hugo.yml` | your domain |
   | `content/` | your content |
{.steps}
  1. Clone OINK Starter; it is the small project template for the theme.

    git clone https://github.com/pgsty/oink-starter my-docs
    cd my-docs
  2. Start the local server.

    hugo server
    Note

    The first build fetches the theme through the Go module proxy, which needs Go on the machine.

  3. Replace three things and it is your site.

    Where Replace with
    title in hugo.yml your site name
    baseURL in hugo.yml your 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.

Source
1. Install Hugo Extended.

1. Install the dependencies:

   ```bash {tab="EL / RHEL" group="stepdemo" value="rpm"}
   sudo dnf install golang git
   ```
   ```bash {tab="Debian / Ubuntu" value="deb"}
   sudo apt install golang-go git
   ```

1. Run `hugo server` to preview.
{.steps}
  1. Install Hugo Extended.

  2. Install the dependencies:

    EL / RHEL
    sudo dnf install golang git
    Debian / Ubuntu
    sudo apt install golang-go git
  3. Run hugo server to 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.

Source
4. Configure `baseURL` and the deployment workflow.
1. Push to `main` and wait for GitHub Actions to finish.
{.steps}
  1. Configure baseURL and the deployment workflow.
  2. Push to main and 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.

Source
{{% steps %}}

### Install the toolchain {#install-toolchain}

You need Hugo Extended ≥ 0.168.0 and Go.

### Run the server {#run-server}

{{< tabs group="oink-os" default="macos" >}}
{{< tab label="macOS" value="macos" >}}
`brew install hugo go`
{{< /tab >}}
{{< tab label="Debian" value="debian" >}}
`sudo apt install hugo golang-go`
{{< /tab >}}
{{< /tabs >}}

### Publish {#publish}

Push to `main`; the workflow the repository ships builds and publishes.

{{% /steps %}}

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
Print 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} , Whereline below the ordered list
Required; has no effect on an unordered list
1. , Whereevery item
Let Markdown count; the content indent is always three spaces
4. (first item) , Wherefirst item
Emits <ol start="4"> and continues from 4; supported for 2–40
{{% steps %}} , Wherearound a set of headings
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.
  • 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

Add {.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.

Source
- [Get started](/docs/start/) — Start with OINK Starter, preview locally, then replace the site details with your own.
- [Authoring](/docs/write/) — How pages are organized and which front matter keys exist.
- [Customization](/docs/customize/) — Navigation, search, branding, languages.
{.cards}
  • 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.

Source
- [Callouts](/docs/components/callout/)
- [Tabs](/docs/components/tabs/)
- [Steps](/docs/components/steps/)
- [Fields](/docs/components/fields/)
{.cards}

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.

Source
- [Front matter](/docs/write/frontmatter/)

  Every page parameter is defined here exactly once: type, default, accepted
  values, and the page that explains it.

- [Configuration](/docs/customize/config/)

  Site parameters grouped by feature, each row linking back to the guide that
  explains it.
{.cards}
  • Front matter

    Every page parameter is defined here exactly once: type, default, accepted values, and the page that explains it.

  • Configuration

    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.

Source
{{< cards >}}
{{< card title="Get started" link="/docs/start/" icon="fa-solid fa-rocket" badge="start here" >}}
Use OINK Starter and establish a local preview before customizing.
{{< /card >}}
{{< card title="Release and download pages" link="/docs/write/releases/" icon="fa-solid fa-box-open" badge="v0.5" >}}
A release card from `release_url` and `date`, plus a `checksums` block for download assets.
{{< /card >}}
{{< card title="Keyboard navigation" link="/docs/customize/keyboard/" icon="fa-solid fa-keyboard" >}}
Site-wide shortcuts and focus order.
{{< /card >}}
{{< /cards >}}
Get startedstart here

Use OINK Starter and establish a local preview before customizing.

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.

Source
{{< cards >}}
{{< card title="Hugo Module" icon="fa-brands fa-golang" >}}
`hugo mod get github.com/pgsty/oink`. The recommended way; upgrading is one
version line.
{{< /card >}}
{{< card title="Git submodule" icon="fa-solid fa-code-branch" >}}
No Go installation needed:

- `git submodule add`
- the theme lands in `themes/oink`
{{< /card >}}
{{< /cards >}}
Hugo Module

hugo mod get github.com/pgsty/oink. The recommended way; upgrading is one version line.

Git submodule

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 ![alt](src): 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.

Source
{{< cards >}}
{{< card title="The OINK shell" link="/docs/about/features/" image="/images/oink.webp" image_alt="An OINK documentation page: sidebar, article and table of contents" >}}
Sidebar, article, table of contents — each can be turned off on its own.
{{< /card >}}
{{< card title="Release notes" link="/docs/write/releases/" image="/images/releasenote.webp" decorative=true >}}
A decorative cover: `decorative=true` emits an empty alt and screen readers skip it.
{{< /card >}}
{{< /cards >}}
An OINK documentation page: sidebar, article and table of contents

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:

hugo.yml
params:
  ui:
    section_index: cards # list | cards

A section can override this setting in its front matter. Use cascade to apply the setting to the whole subtree:

content/docs/customize/_index.md
section_index: list

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
Print 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} , list attribute line , default—
On the line after an unordered list; unordered lists only
First link in an item , Markdown link , default—
The card title and the whole card’s click target
Everything else , Markdown , default—
The description: after — in a tight list, its own paragraph in a loose one

card parameters (cards also accepts an optional variant="list"):

title , plain text , default—
Required, non-empty. The card title
link , URL , default—
Site path, relative path, http(s):, mailto:; external links get rel="noopener"
icon , Font Awesome class pair , default—
For example fa-solid fa-rocket; a malformed value warns and is dropped
badge , plain text , default—
A small label beside the title
image , image source , default—
Page resource / global resource / static path / remote URL
image_alt , plain text , default—
With image, exactly one of this and decorative
decorative , boolean , defaultfalse
true marks a decorative image and emits an empty alt
Body , Markdown , default—
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 card must be inside cards. 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.

9 - FileTree

Write directory listings in a 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

Source
```filetree
- content/
  - _index.md
  - docs/
  - blog/
- hugo.yml
- go.mod
```
  • 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.

Source
```filetree
- 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.yml         # site configuration: languages, menus, params.ui
```
  • 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.

Source
```filetree {title="truncation in both columns"}
- runbooks/
  - a-deliberately-long-runbook-filename-for-a-failover-drill.md  # an equally overlong comment, kept on one line so it has to be clipped inside the comment column
  - restart.md                                                    # short
```

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.

Source
```filetree {title="Complete storage comments" wrap=true}
- storage/
  - metadata/ # Schema definitions: property keys, vertex and edge labels, indexes, and counters.
  - graph/    # Graph data: vertices, edges, index tables, and OLAP analysis data.
```

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.

Source
```filetree {title="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.mod            # the theme, imported as a Hugo Module
- Makefile          # make d / make b / make c
```

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.

Source
```filetree
content/docs
├── about
│   ├── _index.md
│   └── features.md
├── components
│   ├── filetree.md
│   └── image
│       └── index.md
└── _index.md

3 directories, 5 files
```
  • content/docs
    • about
      • _index.md
      • features.md
    • components
      • filetree.md
      • image
        • index.md
    • _index.md

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.

Source
```filetree {title="the content directory"}
- content/
  - docs/                # the documentation tree
    - components/         # 22 component pages    {open=false}
      - callout.md
      - filetree.md
      - image/            # page bundle: body + images  {type=dir}
    - customize/          # site-level configuration    {open=false}
      - config.md
  - blog/
    - release.md
```

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
    • blog/
      • release.md

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.

Source
```filetree {title="deployment layout: permissions and what matters"}
- /etc/pigsty/                 # 0755 root:root · configuration root        {icon="fa-solid fa-server" tone=info}
  - pigsty.yml                 # 0644 root:root · cluster inventory
  - ca/                        # 0700 root:root · self-signed CA, never commit  {icon="fa-solid fa-lock" tone=danger open=false}
    - ca.key                   # 0600 root:root
- /var/lib/pgsql/18/data/      # 0700 postgres:postgres · data directory    {tone=warning}
  - postgresql.conf            # 0600 postgres:postgres
- /usr/bin/pig                 # 0755 root:root · command-line tool         {icon="fa-solid fa-terminal" tone=success}
```

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.

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.

Source
```filetree {title="this site's component pages"}
- content/docs/
  - [callout.md](/docs/components/callout/)     # callouts
  - [filetree.md](/docs/components/filetree/)   # this page
  - [gallery.md](/docs/components/gallery/)     # galleries
  - image/                                      # page bundle
    - [index.md](/docs/components/image/)       # images
- [hugo.yml](https://github.com/pgsty/oink/blob/main/tests/site/hugo.yaml)   # fixture configuration on GitHub
```

this site's component pages

One tree per platform

A fence carrying tab= (and group= / value=) becomes one panel of a tab set and can sit alongside code fences.

Source
```filetree {tab="Linux" group="platform" value="linux"}
- /etc/pigsty/          # configuration
- /var/lib/pgsql/       # data
- /usr/bin/pig          # executable
```
```filetree {tab="macOS" value="macos"}
- ~/Library/Application Support/pigsty/   # configuration
- /opt/homebrew/bin/pig                   # executable
```
Linux
  • /etc/pigsty/configuration
  • /var/lib/pgsql/data
  • /usr/bin/pigexecutable
macOS
  • ~/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
Print 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 , plain text , default—
Title bar above the tree; omitted when absent; must not be empty
wrap , boolean , defaultfalse
Wrap long comments and grow rows; filenames keep ellipsis
tab , plain text , default—
Makes this tree one panel of a tab set
group / value , string , default—
Tab group and sync value; must appear with tab
class , class list , default—
Passed through for site CSS

Entry attributes, in the {…} at the end of a line:

icon , Font Awesome class pair , defaultmatched by name / extension
For example fa-solid fa-lock; a malformed value warns and uses the default icon
tone , enum , defaultneutral
neutral info success warning danger; colours the icon only
open , boolean , defaulttrue
Directories only; false starts it closed
type , enum , defaultinferred
dir or file, overriding the inference

The line syntax itself:

Indentation
Two spaces / four spaces / tabs / the │ ├── └── drawing from tree
- 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 tree summary 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

  • filetree fences 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.
  • Code blocks — listings meant to be copied verbatim
  • Tabs — one tree per platform, side by side
  • Badges — tone uses the same vocabulary
  • Organizing content — how a real content directory is laid out

10 - Math

Use KaTeX for inline and display mathematics at build time. Readers download no script.

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:

hugo.yml
markup:
  goldmark:
    parser:
      attribute:
        block: true # numbered equations need the attribute line
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]

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.

Source
The shared buffer hit ratio is \(\mathrm{hit} = \frac{H}{H + R}\), where \(H\) is `blks_hit` and \(R\) is `blks_read`.

The shared buffer hit ratio is hit=HH+R\mathrm{hit} = \frac{H}{H + R}, where HH is blks_hit and RR is blks_read.

Display formulas

Put a formula in its own paragraph between $$ delimiters. It displays larger and centered. \[…\] has the same effect.

Source
A B-tree with fan-out \(f\) over \(N\) keys has height:

$$
h = \left\lceil \log_{f} N \right\rceil
$$

A B-tree with fan-out ff over NN keys has height:

h=⌈log⁡fN⌉ h = \left\lceil \log_{f} N \right\rceil

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.

Source
```math
N_{\text{conn}} = \lambda \cdot \bar{t}_{\text{resp}}
```
Nconn=λ⋅tˉrespN_{\text{conn}} = \lambda \cdot \bar{t}_{\text{resp}}

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.

Source
```chem
\ce{CO2 + H2O <=> H2CO3 <=> H+ + HCO3^-}
```
COX2+HX2O⇌HX2COX3⇌HX++HCOX3X−\ce{CO2 + H2O <=> H2CO3 <=> H+ + HCO3^-}

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.

Source
$$
\text{WAL}_{\text{day}} \approx \text{TPS} \times \bar{s}_{\text{record}} \times 86400
$$
{#eq-wal num="3-1" caption="Estimating daily WAL volume"}

See [Equation 3-1](#eq-wal): multiply by the retention period for the floor on archive disk size.
WALday≈TPS×sˉrecord×86400 \text{WAL}_{\text{day}} \approx \text{TPS} \times \bar{s}_{\text{record}} \times 86400
Equation 3-1 Estimating daily WAL volume

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:

Source
Capacity planning starts from {{< xref eq="3-1" anchor="eq-wal" />}}.

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.

Source
{{< eq >}}\sigma_{\text{idx}} = \frac{\text{rows}_{\text{matched}}}{\text{rows}_{\text{total}}}{{< /eq >}}

{{< eq num="3-2" caption="Where a sequential scan and an index scan cost the same" >}}
c_{\text{seq}} \cdot P = c_{\text{rand}} \cdot \sigma \cdot T
{{< /eq >}}
σidx=rowsmatchedrowstotal\sigma_{\text{idx}} = \frac{\text{rows}_{\text{matched}}}{\text{rows}_{\text{total}}}
cseq⋅P=crand⋅σ⋅Tc_{\text{seq}} \cdot P = c_{\text{rand}} \cdot \sigma \cdot T
Equation 3-2 Where a sequential scan and an index scan cost the same

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
Print 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:

\(…\) , Placementinline
Governed by the site’s passthrough configuration; takes no attributes
$$…$$ / \[…\] , Placementdisplay
As above; may be followed by an attribute line to become numbered
```math , Placementdisplay fence
Independent of passthrough; takes no attributes
```chem , Placementdisplay fence
As above, with \ce{…} in the body

The attribute line {…} under a display formula:

num , string , default—
[0-9A-Za-z.-]+; registers a numbered equation and shows “Equation N” at the right
#id , identifier , defaulteq-<num>
[A-Za-z][A-Za-z0-9_.:-]*; the anchor and cross-reference target
caption , plain text , default—
Caption after the number; requires num

The eq shortcode:

num , string , default—
As above; without it the formula is an unnumbered display formula
id , identifier , defaulteq-<num>
Requires num
caption , plain text , default—
Requires num
class , class list , default—
Requires num; passed through for site CSS
Body , TeX , default—
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.goldmark passthrough extension controls whether $$, \[…\], and \(…\) render. The theme does not read a math: true front matter key. Without configuration, $$ appears literally. The math fence and eq work without this configuration.
  • Only $$ blocks and eq support numbering. The math fence 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.
  • caption is plain text. Markdown in captions is not parsed.

11 - Mermaid

Use a 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

Source
```mermaid
flowchart LR
  content["content/"] --> Hugo
  config["hugo.yml"] --> Hugo
  theme["OINK theme"] --> Hugo
  Hugo --> site["public/"]
```
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.

Source
```mermaid
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 downloaded
```
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 downloaded

Gantt charts

gantt displays intervals. This example shows each PostgreSQL major version’s five-year community support period, measured from release. 1825d means five years.

Source
```mermaid
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, 1825d
```
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, 1825d

Class and ER diagrams

classDiagram displays types and relationships. erDiagram displays entities and cardinality. Use either to explain a data model.

Source
```mermaid
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 / rss
```
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 / rss
Source
```mermaid
erDiagram
  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
  }
```
erDiagram
  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.

Source
```mermaid
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 move
```
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 move

Per-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.

Source
```mermaid
---
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]
```
---
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:

hugo.yml
params:
  mermaid:
    theme: neutral
    flowchart:
      diagrampadding: 6

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.

Source
{{< tabs >}}
{{< tab label="By data flow" >}}
```mermaid
flowchart LR
  Markdown --> Goldmark --> RenderHooks --> HTML
```
{{< /tab >}}
{{< tab label="By output format" >}}
```mermaid
flowchart LR
  Page --> HTML
  Page --> Print
  Page --> Markdown
  Page --> RSS
```
{{< /tab >}}
{{< /tabs >}}
flowchart LR
  Markdown --> Goldmark --> RenderHooks --> HTML
flowchart LR
  Page --> HTML
  Page --> Print
  Page --> Markdown
  Page --> RSS

Each 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
Print 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 , map , defaultunset
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 , string , defaultMermaid’s default
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

OINK 1.4.0 reading experience

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.
  • PlantUML — UML diagrams; see its rendering modes and version requirements
  • Markmap — outline-shaped hierarchies
  • ECharts — charts with numbers in them
  • Images — hand-drawn SVG and numbering

12 - Component presentation

Cards, disclosures, tabs, and compact procedures across OINK’s four visual presets.

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.

Available in OINK 1.4.0

The optional variants on this page ship in OINK 1.4.0.

Related pages

For a compact resource directory, use {.cards .td-cards-list}. A divided list has one enclosing frame and grows naturally with its descriptions.

The full form accepts cards variant="list" for icons, badges, or block descriptions:

InstallationStart here

Build a local preview before changing the site configuration.

Notes and disclosures

Keep a local preview

Review the page at a narrow width as well as on your desktop.

Check the destination

Confirm the destination before publishing a new version.

How does this work without JavaScript?

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.

Longer titles can wrap without displacing the chevron or reducing the interactive area

Each disclosure opens independently. Other content stays in its current state.

Tabs and commands

macOS / Homebrew
brew install hugo
Debian / Ubuntu
sudo apt install hugo

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.

hugo server --bind 127.0.0.1 --port 1313
hugo --environment production --baseURL https://example.com/documentation/ --destination public

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.

  1. Review the configuration.
  2. Run the local preview.
  3. 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 , Typestring
A concise title that may wrap naturally.
description , Typestring
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

Render sequence, class, component, activity and use-case diagrams in the browser with bundled assets and no rendering service.

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 in OINK 1.4.0

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:

hugo.yml
params:
  plantuml: true

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:

```plantuml
@startuml
actor Reader
participant Browser
Reader -> Browser : open the page
Browser -> Browser : render locally
Browser --> Reader : SVG diagram
@enduml
```
@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:

hugo.yml
params:
  plantuml:
    enable: true
    svg_image_url: https://plantuml.internal.example/plantuml/svg/
    svg: false

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 , boolean or map , defaultdisabled
true enables local rendering
params.plantuml.enable , boolean , defaultfalse
Enables the map form
params.plantuml.svg_image_url , string , defaultabsent
Optional endpoint selecting legacy server rendering
params.plantuml.svg , boolean , defaultfalse
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/core 1.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) and blob: 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.
  • Mermaid — another bundled browser diagram engine
  • Images — pre-rendered diagrams, numbering and zoom
  • Configuration — site settings

14 - Markmap

Use a 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.

hugo.yml
params:
  markmap: true

Then put the outline in a markmap fence:

Source
```markmap
# 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
```
# 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.

Source
```markmap
# 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
```
# 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.

Source
```markmap
# 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)
```
# 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.

Source
```markmap
# 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}$
```
# 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.

Source
```markmap
---
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
```
---
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.

Source
> [!DETAILS] What the theme repository looks like
> ```markmap
> # 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
> ```
What the theme repository looks like
# 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
Print 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 , bool , defaultfalse
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 > svg rule. Fences cannot change this height. For many levels, use initialExpandLevel or 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 &gt; or &#34;. Use [text](URL) links instead of angle-bracket autolinks.

15 - Draw.io

Display a .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.

Source
![The Hugo build pipeline: content goes through Hugo and out as public](pipeline.drawio.svg)
{width="620" height="140"}
The Hugo build pipeline: content goes through Hugo and out as public

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.

Source
![The three columns of the documentation shell: sidebar, article, table of contents](plain-shell.svg)
{width="620" height="140"}
The three columns of the documentation shell: sidebar, article, table of contents

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.

Source
![The Hugo build pipeline](pipeline.drawio.svg)
{caption="Content, configuration and theme templates flow into Hugo and out as public/" width="620" height="140"}
The Hugo build pipeline
Content, configuration and theme templates flow into Hugo and out as public/

As a numbered figure

Add {#id num=…} to create a numbered figure. xref can reference it, and it appears in the list of figures.

Source
![The Hugo build pipeline](pipeline.drawio.svg)
{#fig_pipeline num="1-1" caption="From content to a static site" width="620" height="140"}
The Hugo build pipeline
Figure 1-1 From content to a static site

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.

Source
![The Hugo build pipeline (PNG export)](pipeline.drawio.png)
{width="620" height="140"}
The Hugo build pipeline (PNG export)

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

hugo.yml
params:
  drawio:
    enable: true
    drawio_server: https://drawio.internal.example/
  • enable: true without drawio_server warns 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 baseURL deployment 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
Print 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 , bool , defaultfalse
With it off no script loads and an image is just an image
params.drawio.drawio_server , string , defaultnone
The editor address; required when enable: true

Limits

  • The runtime loads only if rendered page content has .svg or .png candidates. It groups matching images by URL and reads each URL once to find mxfile.
  • 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 none fills and neutral gray lines and text so the image is readable in both modes.
  • 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

Write ECharts options as YAML or JSON in an 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.

Source
```echarts {height="320px"}
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]
```
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.

Source
```echarts {height="360px"}
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]
```
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.

Source
```echarts {height="340px"}
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 }
```
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.

Source
```echarts {height="260px" full=true}
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]
```
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:

Source
```echarts {height="240px" theme="dark"}
xAxis:
  type: category
  data: [HTML, Print, Markdown, RSS]
yAxis:
  type: value
series:
  - type: bar
    data: [1, 1, 1, 1]
```
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:

Source
<script>
  window.OinkEchartsFunctions = window.OinkEchartsFunctions || {};
  window.OinkEchartsFunctions.pageShare = function (params) {
    var p = params[0];
    return p.name + ': ' + p.value + ' pages, ' + Math.round((p.value / 60) * 100) + '% of the site';
  };
</script>

```echarts {height="300px"}
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]
```
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
Print 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 , CSS length , default400px
A non-negative number plus px rem em vh vw %; anything else warns and uses the default
theme , string , defaultunset
Pin an ECharts theme and stop following the site’s colour scheme; only dark is built in
full , bool , defaultfalse
true drops the reading-column limit and fills the content area
class , space-separated classes , default—
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 to undefined without 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, and yes. 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.
  • 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

Use an 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.

Source
```infographic
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 PR
```
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 PR

Use 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.

Source
```infographic {height="420px"}
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 subsystem
```
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 subsystem

Funnels

sequence-funnel-simple displays narrowing stages. This example shows the five stages of a theme release.

Source
```infographic {height="420px"}
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 version
```
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 version

Grid cards

For unordered items, list-grid-* uses a grid instead of a sequence.

Source
```infographic {height="380px"}
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 print
```
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 print

Items with values

Add value to an item for templates that show proportions, such as pies, doughnuts, or progress displays.

Source
```infographic {height="400px"}
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 2
```
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 2

Hierarchy 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.

Source
```infographic {height="320px"}
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 theme
```
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 theme

theme 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
Print 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 , auto or a CSS length , defaultauto
A non-negative number plus px rem em vh vw %; anything else warns and uses auto
full , bool , defaultfalse
true drops the reading-column limit
class , space-separated classes , default—
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
data
title, desc, items (or sequences, compares, nodes, values, relations, root, depending on the structure), order
theme
type (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.
  • theme is 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.
  • ECharts — when you need axes and exact numbers
  • Steps — when the reader has to follow the procedure
  • Cards — a grid of clickable entry points
  • Mermaid — flows with branches and conditions

18 - Gallery

Use a 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 ![alt](src) syntax.

Source
```gallery
![OINK's default documentation shell](/images/oink.webp)
![The classic Docsy layout upstream](/images/docsy.webp)
```

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.

Source
```gallery
![The three-column layout of an OINK page](/images/oink.webp) # The default shell: sidebar, article, table of contents
![The classic Docsy documentation layout](/images/docsy.webp) # Docsy upstream — the content model is the same lineage
![A release notes page](/images/releasenote.webp) # 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.

Put {link=…} at the end of a line to make that item a link. Site paths, relative paths, and http(s): are supported.

Source
```gallery
![OINK's default documentation shell](/images/oink.webp) # Opens the Images component page {link=/docs/components/image/}
![A release notes page](/images/releasenote.webp) # Opens "Releases and downloads" {link=/docs/write/releases/}
```

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.

Source
```gallery
![OINK documentation overview (global resource)](images/content-primitives/oink.webp) # Under assets/images/…, eligible for build-time processing
![The light home page (static path)](/images/hero-light.webp) # 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.

this page's front matter
image_zoom: true
Source: one decorative image, one ordinary one
```gallery
![](/images/docsy.webp) # Decorative, never zooms
![The Pigsty release notes page](/images/releasenote.webp) # 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.

Source
```gallery {tab="OINK" group="shell" value="oink"}
![OINK's default documentation shell](/images/oink.webp) # Sidebar, article, table of contents
```
```gallery {tab="Docsy" value="docsy"}
![The classic Docsy layout upstream](/images/docsy.webp) # The same content-model lineage
```
OINK
Docsy

Output

Output Shape
HTML <ul class="td-gallery"> with one <li> per item; eligible images carry data-td-image-zoom; everything is lazy-loaded
Print 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 ![alt](src) [# description] [{key=value …}]:

![alt](src) , Requiredyes
Must start the line. alt is the item’s title; empty means decorative
src , Requiredyes
Page resource / global resource / static path / remote URL
# description , Requiredno
Plain text under the image; \# is a literal hash; must not be empty
{link=…} , Requiredno
Makes the item a link, and therefore not zoomable
{class=…} , Requiredno
Adds a site CSS class to that item

Fence attributes:

tab , plain text , default—
Makes this gallery one panel of a tab set
group / value , string , default—
Tab group and sync value; must appear with tab
class , class list , default—
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.

  • 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

Add a semantic status label beside a feature name, version, or table cell. Choose from five tones; custom colors are not supported.

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

Source
{{< badge text="Beta" tone="warning" >}}
Beta

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.

Source
{{< badge text="Default" >}}
{{< badge text="Info" tone="info" >}}
{{< badge text="Supported" tone="success" >}}
{{< badge text="Experimental" tone="warning" >}}
{{< badge text="Deprecated" tone="danger" >}}

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.

Source
With `params.ui.image_zoom` {{< badge text="off by default" tone="neutral" >}} enabled,
block images that have alt text open full size. PlantUML {{< badge text="opt-in" tone="info" >}}
uses its own site switch. Draw.io {{< badge text="needs a server" tone="warning" >}}
warns and remains off when no endpoint is configured.

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:

Source
### OpenAPI pages {#openapi-example}

{{< badge text="new in 0.5" tone="success" >}} This section covers…

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”.

Source
| Component | Form | Status |
| --- | --- | --- |
| Callouts | `> [!NOTE]` | {{< badge text="stable" tone="success" >}} |
| Galleries | ` ```gallery ` fence | {{< badge text="stable" tone="success" >}} |
| PlantUML | ` ```plantuml ` fence | {{< badge text="opt-in" tone="info" >}} |
| The `image` shortcode | — | {{< badge text="removed" tone="danger" >}} |
Component Form Status
Callouts > [!NOTE] stable
Galleries ```gallery fence stable
PlantUML ```plantuml fence opt-in
The image shortcode — removed

In lists and steps

Source
1. Install Hugo Extended {{< badge text="≥ 0.168.0" tone="info" >}}
1. Create a site from OINK Starter and change `baseURL` in `hugo.yaml`
1. `hugo server` to preview {{< badge text="port 1313" tone="neutral" >}}
{.steps}
  1. Install Hugo Extended ≥ 0.168.0
  2. Create a site from OINK Starter and change baseURL in hugo.yaml
  3. hugo server to 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.

Source
{{< cards >}}
{{< card title="Hugo Module" icon="fa-brands fa-golang" badge="recommended" >}}
One `hugo mod get` and you are done {{< badge text="needs Go" tone="info" >}}
{{< /card >}}
{{< card title="Offline archive" icon="fa-solid fa-box-archive" >}}
Builds on a machine with no network {{< badge text="manual upgrades" tone="warning" >}}
{{< /card >}}
{{< /cards >}}
Hugo Modulerecommended

One hugo mod get and you are done needs Go

Offline archive

Builds on a machine with no network manual upgrades

With link, the badge becomes an <a> element. Site paths, relative paths, http(s):, and mailto: are supported.

Source
Current version {{< badge text="v0.5" tone="info" link="/blog/" >}};
for the upgrade steps see {{< badge text="Upgrading" tone="neutral" link="/docs/admin/upgrade/" >}}.

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
Print 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 , plain text , default—
Required, non-empty. What the reader sees
tone , enum , defaultneutral
neutral info success warning danger
link , URL , default—
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.
  • Cards — card has a badge parameter of its own
  • File trees — tone uses the same vocabulary
  • Keys — the other inline shortcode
  • Callouts — when the status needs explaining

20 - Kbd

Use 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

Source
Press {{< kbd "Ctrl" "K" >}} to open the command palette.

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.

Source
{{< kbd "Escape" >}} closes a dialog;
{{< kbd "/" >}} jumps to search;
{{< kbd "t" >}} toggles light and dark;
{{< kbd "l" >}} cycles through languages.

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.

Source
{{< kbd "⌘" "Shift" "P" >}} and {{< kbd "Ctrl" "Shift" "P" >}} are the same action.
For a literal plus, treat it as a key of its own: {{< kbd "Ctrl" "+" >}} zooms the page in.

⌘ 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.

Source
On macOS press {{< kbd "⌘" "K" >}}; on Windows and Linux, {{< kbd "Ctrl" "K" >}}.

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:

Source
| Key | Action |
| --- | --- |
| {{< kbd "Ctrl" "K" >}} | Open the command palette ({{< kbd "⌘" "K" >}} on macOS) |
| {{< kbd "/" >}} | The palette's full search state |
| {{< kbd "t" >}} | Toggle light and dark |
| {{< kbd "q" >}} / {{< kbd "e" >}} | Previous / next page |
| {{< kbd "w" >}} {{< kbd "s" >}} {{< kbd "a" >}} {{< kbd "d" >}} | Move, collapse and expand in the sidebar tree |
| {{< kbd "Escape" >}} | Leave the sidebar tree for the article |
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

Source
1. Press {{< kbd "Ctrl" "K" >}} to open the command palette
1. Type `>` for the command-only state, or type a keyword to search
1. Select with {{< kbd "↑" >}} {{< kbd "↓" >}} and press {{< kbd "Enter" >}} to go
1. {{< kbd "Escape" >}} closes it and focus returns where it was
{.steps}
  1. Press Ctrl with K to open the command palette
  2. Type > for the command-only state, or type a keyword to search
  3. Select with ↑ ↓ and press Enter to go
  4. 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.

Source
Press <kbd>F5</kbd> to reload; in an editor, <kbd>Ctrl</kbd>+<kbd>S</kbd> saves.

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
Print 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 , string , default—
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 kbd calls and describe the order: press Escape, then Enter.
  • There is no platform detection. The page never replaces Ctrl with ⌘ 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. Ctrl in {{< kbd Ctrl K >}} is not a string parameter.
  • Do not use keys for commands. hugo server is inline code; Ctrl is a key.

21 - Includes

Use include to insert a file, param to print a site parameter, and comment to remove a note from every output.

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:

Source
{{< include file="parts/install-oink.md" >}}

The included file contains ordinary Markdown under assets/:

assets/parts/install-oink.md
Installing OINK into an existing Hugo site takes three commands:

```sh
hugo mod init github.com/you/your-site
hugo mod get github.com/pgsty/oink
hugo server
```

> [!NOTE]
> `hugo mod get` needs Go on the machine; an offline archive or a submodule does not.

The current release is {{< param version >}}.

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 init github.com/you/your-site
hugo mod get github.com/pgsty/oink
hugo server
Note

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.

Source
{{< include file="parts/module.yml" code=true lang="yaml" >}}
module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.168.0

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.

What makes a good fragment

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.

Source
This site publishes {{< param version >}}, copyright from {{< param copyright.from_year >}},
and this page's front matter says `pigsty_pg_major: 18`, which reads back as {{< param pigsty_pg_major >}}.

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:

Source
```sh
hugo mod get github.com/pgsty/oink@{{< param tdVersion.latest >}}
```

| Item | Value |
| --- | --- |
| Current version | {{< param version >}} |
| Hugo floor | {{< param hugoMinVersion >}} |

[Release notes](https://github.com/pgsty/oink/releases/tag/{{< param tdVersion.latest >}})
hugo mod get github.com/pgsty/[email protected]
Item Value
Current version v1.5.1
Hugo floor 0.168.0

Release notes

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.

Source
Since PostgreSQL 18, `pg_stat_io` breaks out WAL statistics.

{{< comment >}}
TODO: after v0.5 ships, bump the version above to 19 and add a pg_stat_io screenshot.
This text reaches no output at all, llms.txt included.
{{< /comment >}}

Verify the dashboards on a test database before upgrading.

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
Print 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 , path (required) , default—
Resolution order in Where the file comes from; a .., missing file, or empty value warns and emits nothing
code , boolean , defaultfalse
true renders as a code block; quoted code="true" warns and includes ordinary content
lang , string , default—
Code language; without code=true it warns and is ignored

Other parameter names warn and are ignored. The message identifies the file and line.

param (one positional parameter):

parameter name , string (required) , default—
Nested keys join with .; page front matter first, then site params; 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

  • include is not a template. You cannot pass variables, include conditionally, or supply code-block fence attributes such as title= or collapse. For platform variants, create two fragments and use tabs.
  • You maintain fragment languages. include has 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.
  • param prints only scalars. Put structured data, such as version matrices or download lists, in data/ and use the matching component.
  • comment discards content on every build. To temporarily unpublish a whole page, use draft: true.
  • Do not use include to create an index page. If a page needs ten fragments, give readers ten links instead.
  • Code blocks — every fence attribute, and the pipeline include code=true reuses
  • Tabs — per-platform or per-language fragments
  • Configuration — the site parameters param can reach
  • Front matter — page parameters, which win over site configuration

22 - Asciinema

Display a .cast terminal recording with selectable text. The theme includes the player and does not use a CDN.

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:

Source
{{< asciinema file="images/install.cast" >}}

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:

Source
{{< asciinema file="images/install.cast" title="Pigsty single-node install" theme="dracula" >}}

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.

Source
{{< asciinema file="images/install.cast" title="From 60 seconds in, at double speed"
  speed="2" startAt="60" poster="npt:1:30" >}}

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:

Source
{{< asciinema file="images/install.cast" title="Only 16 rows tall" rows="16" >}}

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:

Source
{{< asciinema file="images/install.cast" title="Looping: the first minute after login"
  startAt="0" speed="3" loop="true" preload="true" >}}

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.

Source
1. Install the dependencies and fetch the installer:

   ```sh
   curl -fsSL https://repo.pigsty.io/get | bash
   ```

2. Run the install; the recording plays the process at four times speed:

   {{< asciinema file="images/install.cast" title="pig install" speed="4" >}}

3. Open `http://<node address>:3000` and sign in to Grafana with `admin / pigsty`.
{.steps}
  1. Install the dependencies and fetch the installer:

    curl -fsSL https://repo.pigsty.io/get | bash
  2. Run the install; the recording plays the process at four times speed:

    pig install — /images/install.cast

  3. Open http://<node address>:3000 and sign in to Grafana with admin / 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 clear before you start.
  • Remove secrets before recording. A .cast is plain text, so every recorded character can be searched. Check the file before committing.
  • Put the file at static/images/install.cast and use file="images/install.cast". assets/images/install.cast works with the same value. Page-bundle resources are not resolved. Commit the recording instead of using a .cast URL 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
Print 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 , path (required) , default—
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 , plain text , defaultthe value of file
The window title
theme , enum , defaultauto
auto follows the site’s colour scheme; or td-light td-dark asciinema dracula gruvbox-dark monokai nord seti solarized-dark solarized-light tango
fit , enum , defaultwidth
width height both none; anything else warns and uses width
cols / rows , integer , defaultfrom the .cast header
Override the terminal size; smaller than the recording clips it
speed , number , default1
Playback rate
startAt , number (seconds) , default0
Where playback starts
idleTimeLimit , number (seconds) , defaultfrom the .cast header
Longest a silent stretch plays for
poster , string , default—
The frame shown before playback, npt:mm:ss
autoplay , "true" / omitted , defaultoff
Play as the page opens; not recommended
loop , "true" / omitted , defaultoff
Replay at the end
preload , "true" / omitted , defaultoff
Fetch the .cast when the page loads
pauseOnMarkers , "true" / omitted , defaultoff
Pause at chapter markers
markers , time:label,time:label , default—
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

  • markers labels are lost. The theme converts the time:label list 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. Although http and https addresses are accepted, they make the page depend on another site. Other schemes, protocol-relative //host addresses, 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.
  • 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