Components
Use this section to write components in Markdown. Each page starts with the shortest example, then gives more detailed examples. The page also gives the output matrix, parameter table, and limits. Use the cheatsheet below for a quick syntax reference.
Two forms
The native form uses Markdown blockquotes, lists, tables, images, or fences, followed by one {…} attribute line.
This form stays readable on GitHub and in Markdown editors. Markdown output preserves the source instead of rendered HTML.
Use a shortcode for features that the native form cannot express. Examples include tabs in prose and parameter tables with block descriptions. Cards with icons and badges, and terminal recordings, also need shortcodes. Follow these five rules:
- Write every shortcode as
{{< name >}}. Only{{% steps %}}uses the%delimiter because its body is page-level Markdown. - Use nested names (
tab,card,field) only inside their parent. - Invalid author parameters never fail silently. Ordinary previews warn, identify the source position, and use the documented fallback or omit unsafe content. Review the warning and rendered fallback before publication.
- Public string parameters, such as captions, labels, and titles, are plain text. They are not parsed as Markdown.
Only bodies are Markdown:
tab,cardandfieldbodies, files loaded byinclude, and Bookfig/tbl/egbodies. - Components that a page does not use load no runtime. HTML references only the stable capability chunks that the page needs. Print, Markdown, and RSS load no interactive runtime.
Site prerequisites
Components need three Goldmark settings. OINK Starter configures these settings. If you start from scratch, copy this snippet:
renderer.unsafe: truekeeps raw HTML in content. Goldmark drops it by default. Without this setting, HTML inside component bodies disappears.parser.attribute.block: trueenables attribute lines. Without it,{.steps}and{caption="…"}appear as text.parser.wrapStandAloneImageWithinParagraph: falseprevents<p>wrappers around standalone images. This permits captioned figures and attribute lines after images.
Some components need other settings. Mathematics needs Goldmark passthrough. Draw.io needs an explicitly configured editor service. Each component page explains its requirements. Configuration lists all configuration keys.
OINK 1.4.0 renders PlantUML locally when enabled without an endpoint, using two bundled scripts. An explicit endpoint keeps server mode; see the PlantUML guide for both modes.
Cheatsheet
The Form column uses three labels. Native means Markdown syntax plus an attribute line.
Fence means a fenced block with a language tag. Shortcode means {{< … >}}.
The Runtime column shows whether the component loads JavaScript on the page.
| Component | In one line | Shortest form | Form | Runtime |
|---|---|---|---|---|
| Callouts | Separate prerequisites, warnings and asides from the prose | > [!NOTE] |
native | none |
| Images | Captions, sizing, zoom, numbering and build-time processing |  |
native | site switch |
| Code Blocks | Highlighting, titles, copy, folding, linkable lines | ```sh |
fence | per page |
| Tabs | One thing, several platforms or languages | attribute {tab="Linux"} |
native + shortcode | per page |
| Tables | Plain tables plus full-width, matrix, caption and numbering | {.full-width} |
native | tabs or .expand only |
| Fields | Parameter lists with type / required / default chips | {.fields meta="type default"} |
native + shortcode | none |
| Steps | A procedure with an order | {.steps} |
native + shortcode | none |
| Cards | A set of parallel destinations | {.cards} |
native + shortcode | none |
| FileTree | Directory structure with an aligned comment column | ```filetree |
fence | per page |
| Math | KaTeX inline and display formulas | $$ … $$ |
native | none |
| Mermaid | Flowcharts, sequence diagrams, Gantt charts | ```mermaid |
fence | per page |
| PlantUML | UML diagrams; local rendering in OINK 1.4.0 | ```plantuml |
fence | site switch |
| Markmap | A Markdown outline becomes a mind map | ```markmap |
fence | site switch |
| Draw.io | Diagrams that stay editable; needs a server |  |
native | site switch |
| ECharts | Declarative statistical charts | ```echarts |
fence | per page |
| Infographic | AntV infographics | ```infographic |
fence | per page |
| Gallery | A set of images sharing one zoom dialog | ```gallery |
fence | site switch |
| Badge | Inline status markers | {{< badge text="Beta" >}} |
shortcode | none |
| Kbd | Key names and chords | {{< kbd "Ctrl" "K" >}} |
shortcode | none |
| Includes | Pull in files, print site parameters, drop build-time notes | {{< include file="parts/x.md" >}} |
shortcode | none |
| Asciinema | Terminal recordings | {{< asciinema file="images/x.cast" >}} |
shortcode | per page |
Four notes on the Runtime column:
- A code block loads
code-block.jsonly if a block on the page has a copy or fold control. A file tree loadsfiletree.jsonly if it has a comment column. This runtime lets readers drag the splitter. - Images and galleries share one zoom dialog runtime. It needs site-level
ui.image_zoomand at least one eligible image on the page. - KaTeX renders mathematics to HTML and MathML at build time. The page loads a KaTeX stylesheet and fonts, but no script.
- Draw.io loads only on pages whose rendered content has PNG or SVG candidates. It inspects each distinct image URL once.
Every component defines its behavior in four outputs: HTML, print, Markdown, and RSS. See Output on each component page.
Write notes, warnings, and collapsible asides with colors, icons, and titles. Use > [!NOTE] blockquotes without shortcodes.
Use Markdown image syntax and attributes for captions, sizing, zoom, links, numbering, and Hugo image processing.
Use a Markdown fence and attributes for titles, exact copying, line numbers, highlighting, wrapping, folding, and line links.
Add {tab=} to adjacent fences or tables to create tabs. Add a group to enable links, synchronization, and saved selections.
Add attributes to a GFM table for captions, compatibility matrices, field lists, numbering, or tabs. Wide tables scroll within their own regions.
Add {.fields} to a table to document configuration keys, command flags, and API fields. Entries adapt to narrow screens and have individual anchors.
Add {.steps} to an ordered list for a numbered procedure. Use the steps shortcode when each step needs a table-of-contents heading.
Add {.cards} to a link list to create navigation cards. Use the shortcode for icons, badges, or images.
Write directory listings in a filetree fence. Use indentation for depth, trailing slashes for directories, and aligned comments for explanations.
Use KaTeX for inline and display mathematics at build time. Readers download no script.
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.
Cards, disclosures, tabs, and compact procedures across OINK’s four visual presets.
Render sequence, class, component, activity and use-case diagrams in the browser with bundled assets and no rendering service.
Use a markmap fence for an expandable mind map with zoom controls. Its source remains a readable Markdown outline.
Display a .drawio.svg with an embedded editable copy as an ordinary image. Its edit button opens the Draw.io editor.
Write ECharts options as YAML or JSON in an echarts fence. Hugo validates them, and bundled ECharts draws charts that follow the color scheme.
Use an infographic fence and AntV template to display a title and items as a flow, timeline, funnel, grid, or hierarchy.
Use a gallery fence for a responsive image grid with optional descriptions and links. Images share the page zoom dialog.
Add a semantic status label beside a feature name, version, or table cell. Choose from five tones; custom colors are not supported.
Use kbd with one key name per parameter to display a semantic key sequence. Instructions remain readable in print and Markdown.
Use include to insert a file, param to print a site parameter, and comment to remove a note from every output.
Display a .cast terminal recording with selectable text. The theme includes the player and does not use a CDN.