Category: Components

asciinema renders a .cast recording as a terminal player on the page. It suits command-line walkthroughs: the text in the terminal is still text, it can be selected and copied, and the near-two-minute install excerpt on this page is about 110 KB. …

Three shortcodes, one job each: include puts another file’s contents into this page, param prints a page or site parameter, and comment discards a passage. They are for fragments reused across pages and constants scattered over many: one set of …

Keys separate what the reader has to press from the prose. Use it for shortcuts and chords: one positional parameter per key, and the theme draws the caps, adds the separators, and gives screen readers a readable sequence. Command names, flags and …

A badge is an inline status label that sits right after a name: Beta, deprecated, v0.5, needs a server. It suits a status of one or two words. The author picks a semantic tone and the theme picks the colour, with contrast guaranteed in light and …

A gallery arranges related images in a responsive grid, one image per line inside the fence. It suits several views of one thing: a few screenshots, a few states, a few colour schemes. A single image is an image, and images with no order or …

An infographic fence picks an AntV template and renders “a title plus a list of items” as an infographic. Use it for structure: order, hierarchy, comparison. When you need axes and numeric precision use ECharts; when you need a flow with conditional …

The body of an echarts fence is an ECharts option object in YAML or JSON — not code. Use it for quantitative charts that need axes, series and a legend. For relationships and flows use Mermaid; for order and hierarchy use Infographic. Hugo parses the …

The Draw.io integration has neither a fence nor a shortcode — it uses plain Markdown images. Tick “Include a copy of my diagram” when exporting from Draw.io and the SVG or PNG carries an mxfile copy inside it; the theme’s runtime spots that copy and …

The body of a markmap fence is a plain Markdown outline: headings and lists give the hierarchy, and the browser draws it as a tree you can expand and collapse. It suits showing “what this section covers” at one glance. For flows with direction and …

A plantuml fence holds PlantUML source. The browser compresses and encodes it, appends it to the URL of a PlantUML server, and gets an SVG back. It suits sequence, class, component, activity and use-case diagrams that need the full expressiveness of …

A mermaid fence renders text as a flowchart, sequence diagram, Gantt chart, class diagram, ER diagram or state diagram. The diagram exists as source: it goes into Git, it reviews as a diff, and search finds it. Rendering happens in the reader’s …

Mathematics is rendered by KaTeX at build time into HTML + MathML. A page with formulas gains one local KaTeX stylesheet and nothing else — no JavaScript, no request to a remote maths service. Inline formulas are \(…\), display formulas are $$…$$ or …

A file tree is a filetree fence whose body is the listing itself: indentation is depth, a trailing / marks a directory, and everything after # is a comment. Use it to explain the part of a directory structure that concerns the reader, one annotation …

Cards are a set of parallel links: each card is a linked title plus a sentence, and the grid adapts to the container width. They suit section landing pages, “what to read next”, and a handful of parallel entry points. They do not suit running prose …

Steps are an ordered list with numbered dots and a rule running through them: a plain ordered list plus a {.steps} marker line. The dots and the rule are drawn in CSS and no script is loaded. Use it for procedures that have an order. Parallel items …

Fields render “a list of named values with metadata and a description” as a responsive definition list: the name gets its own line, type / required / default sit beside it as small chips, the description starts on the next line, and every entry …

A table is an ordinary GFM pipe table. The theme’s table render hook wraps every one in a horizontally scrollable region, and the {…} attribute line underneath decides which kind of table it is: captioned, a compatibility matrix, a field list, a …

Tabs put equivalent alternatives side by side: package managers, distributions, YAML / TOML / JSON, an environment variable versus a configuration key. Ordered steps and unrelated content do not belong in tabs — the reader sees only one panel at a …

This section answers one question: how do I write this component in Markdown? Every page has the same shape — the shortest example, progressively richer examples, the output matrix, the parameter table, the limits. For syntax at a glance, use the …

A code block is an ordinary Markdown fence. Highlighting is done at build time by Chroma, which Hugo embeds; there is no highlighter in the browser. Use it for commands, configuration snippets and source. The {…} attributes on the fence’s info line …

There is one way to write an image: Markdown’s . An image standing alone as its own paragraph can be followed by a {…} attribute line, making it a captioned figure, a zoom candidate, a numbered figure, or a derivative …

A callout is a GitHub / Obsidian style blockquote: > [!TYPE] on the first line, the body underneath. Use it to lift a prerequisite, a warning or an aside out of the running text; if a sentence in the prose says it, a callout is not needed. Shortest …