Skip to content

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.

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.

Table reader