Components on OINK

Code blocks and Code Groups

Mon, 01 Jan 0001 00:00:00 +0000

OINK enhances Hugo’s ordinary fenced code blocks without replacing Chroma or requiring a browser highlighter. The server emits the complete code and shell; small page-scoped scripts only enable Copy, visual collapse, and tab state.

Enhanced fences

Add metadata in Hugo’s fence attribute list. A fence without attributes still receives the same responsive shell and its normal Copy default. filename adds a visible header; title is its compatible alias, and setting both is a build error. With neither, OINK uses a compact overlay instead of an empty title row.

Badge

Mon, 01 Jan 0001 00:00:00 +0000

Use Badge to place a short status beside a feature, option, or release name. The author chooses a semantic tone; Oink maps it to theme tokens that retain contrast in light and dark modes.

When to use

Badge works well for lifecycle states such as Beta, New, Experimental, and Deprecated. Keep the text explicit: color supplements the label and never replaces it. Use ordinary prose or an alert when the status needs explanation, instructions, or a deadline.

Kbd

Mon, 01 Jan 0001 00:00:00 +0000

Use Kbd to distinguish literal keys and shortcuts from surrounding prose. It renders semantic HTML, remains readable in Markdown and print, and needs no JavaScript.

When to use

Use Kbd for keys the reader should press, including multi-key shortcuts. Use inline code for commands, option names, or text the reader should type; those are not physical or virtual keys.

Quick start

Source

GO-HTML-TEMPLATE

Press {{< kbd "Ctrl" "K" >}} to open search.
Use {{< kbd "⌘" "Shift" "P" >}} to open the command palette.

Rendered result

Press Ctrl+ with K to open search. Use ⌘+ with Shift+ with P to open the command palette, or press Alt+ with Enter to apply an action.

Fields and Field

Mon, 01 Jan 0001 00:00:00 +0000

Use fields with field children to document named values and their metadata. The component favors a responsive definition list over a wide fixed table, so long names and descriptions remain usable on narrow screens.

When to use

Fields works for configuration keys, command or API parameters, object properties, and response members. Use a regular Markdown table when readers must compare many rows across the same columns. Use prose when the entries are steps rather than definitions.

FileTree

Mon, 01 Jan 0001 00:00:00 +0000

Use FileTree to explain the part of a repository or directory layout that matters to the reader. Folders use native disclosure controls in interactive HTML; every output retains the complete nested structure.

When to use

FileTree works best for curated structures in setup guides, architecture overviews, and contribution instructions. Use a code block for literal command output that should be copied verbatim. Describe generated or highly dynamic trees in prose instead of committing a large snapshot that will quickly drift.

Gallery

Mon, 01 Jan 0001 00:00:00 +0000

Gallery groups related images in a responsive grid. It is static-first: images, alternative text, and captions remain available without JavaScript. When Image Zoom is enabled, Gallery reuses the same dialog instead of loading another lightbox.

When to use

Use Gallery to compare a small set of screenshots, states, or related visual examples. Use a single image when sequence and comparison do not matter. Use Carousel when the content intentionally needs slide navigation and hiding noncurrent items is acceptable.

Image Zoom

Mon, 01 Jan 0001 00:00:00 +0000

Image Zoom progressively enhances eligible content images with one native dialog. It is useful for screenshots and architecture diagrams whose details may be hard to read at the document width. The original image remains complete when JavaScript or dialog support is unavailable.

When to use

Enable zoom when a reader benefits from seeing the source image at a larger size. Prefer a purpose-built crop or a clearer diagram when enlargement does not solve the readability problem. Decorative icons, logos embedded in prose, and linked thumbnails should retain their existing behavior.

Shortcodes

Mon, 01 Jan 0001 00:00:00 +0000

Shortcodes add behavior that ordinary Markdown cannot express. OINK retains the core Docsy components and adds locally served charts, terminal recordings, infographics, carousels, cards, and disclosure widgets. Browser runtimes load only on pages that use them.

Prefer Markdown for headings, prose, lists, links, tables, and images. A shortcode becomes part of the content API: changing its name or parameters can break every page that calls it.

Shortcode delimiters

Hugo supports two forms:

Diagrams and formulae

Mon, 01 Jan 0001 00:00:00 +0000

OINK supports KaTeX, Mermaid, Markmap, PlantUML, and Diagrams.net. KaTeX, Mermaid, and Markmap use build-time or same-origin resources shipped with the theme. PlantUML and the Diagrams.net editor require an explicitly configured service endpoint; they do not silently default to a public service.

LaTeX support with KaTeX

KaTeX renders TeX mathematics for the web. Hugo’s embedded KaTeX support can render formulae at build time, so readers do not need a remote math service.

Apache ECharts

Mon, 01 Jan 0001 00:00:00 +0000

The echarts shortcode renders an Apache ECharts options object with the versioned runtime bundled by Oink. Hugo parses JSON or YAML at build time, serializes the result into the page, and loads ECharts only on pages that use the component.

Use ECharts for quantitative charts whose axes, encodings, tooltips, or series need more control than a diagram or table provides. Keep a nearby textual summary so the conclusion does not depend on color, pointer interaction, or JavaScript.

Infographics with AntV

Mon, 01 Jan 0001 00:00:00 +0000

The infographic shortcode renders the AntV Infographic DSL with the versioned runtime bundled by Oink. Use it for processes, timelines, cycles, funnels, roadmaps, and compact visual summaries where a statistical chart would be too literal.

The DSL is serialized as data, not inserted as arbitrary HTML or executable code. The browser runtime turns it into SVG and loads only on pages that use the shortcode.

Quick start

GO-HTML-TEMPLATE

{{< infographic >}}
infographic list-row-simple-horizontal-arrow
data
  title Documentation workflow
  items
    - label Draft
      desc Write the first version
    - label Review
      desc Check facts and language
    - label Publish
      desc Build and verify the site
{{< /infographic >}}

The same three steps appear below. Drafting creates the first version, review checks facts and language, and publication builds and verifies the site.