Components

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

Two forms

A component’s first form is Markdown itself: blockquotes, lists, tables, images, fences — plus a single {…} attribute line right after them. The native form stays readable on GitHub and in any Markdown editor, and the Markdown output keeps the source rather than the rendered HTML.

Whatever the native form cannot express is a shortcode: tabs in running text, parameter tables with block-level descriptions, cards with icons and badges, terminal recordings. Five rules cover them:

• Every shortcode is written {{< name >}}. Only {{% steps %}} uses the % delimiter, because its body is page-level Markdown.
• Nested names (tab, card, field) are valid only inside their parent.
• A bad parameter never degrades silently. The build fails, and the error names the file and the line.
• Public string parameters (captions, labels, titles) are plain text and are not parsed as Markdown. Only bodies are Markdown: tab, card and field bodies, files pulled in by include, and the Book fig / tbl / eg bodies.
• A component the page never used ships no runtime. The scripts are concatenated from what this page actually used; print, Markdown and RSS output load nothing at all.

Site prerequisites

Components depend on three Goldmark settings. Cloning this site gives you them already configured; copy the snippet when starting from scratch:

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 — Goldmark drops raw HTML in content by default; with it off, HTML nested inside component bodies disappears.
• parser.attribute.block: true — the master switch for attribute lines. With it off, {.steps} and {caption="…"} are just a line of text.
• parser.wrapStandAloneImageWithinParagraph: false — a standalone image is no longer wrapped in <p>, so it can become a captioned figure and an attribute line can follow it.

A few components have their own prerequisites: mathematics needs Goldmark passthrough, PlantUML and Draw.io need a rendering server you run yourself. Each page says so. The complete set of configuration keys is in Configuration.

Cheatsheet

Values in the Form column: native = Markdown syntax plus an attribute line; fence = a fenced block with a language tag; shortcode = {{< … >}}. The Runtime column says whether the component ships JavaScript to the page.

Four notes on the Runtime column:

• A code block loads code-block.js only when a block on the page has a copy or fold control; a file tree loads filetree.js only when the tree has a comment column, which is the runtime that drags the split.
• Images and galleries share one zoom dialog runtime. It needs ui.image_zoom on for the site and at least one eligible image on the page.
• Mathematics is rendered to HTML and MathML by KaTeX at build time. The page gains a KaTeX stylesheet and its fonts, and no script.
• Draw.io loads only on pages whose rendered content contains PNG or SVG candidates, then inspects each distinct image URL once.

Every component has a defined shape in all four outputs — HTML, print, Markdown and RSS. See the Output section on each page.