Shortcode usage patterns

This page demonstrates the three canonical usage patterns for any named shortcode in the family: basic, full-coverage, and the below-footer pattern. These are the patterns every author needs; the inner-primitive escape hatch covered in docs/shortcodes/infobox-primitives.md builds on them.

The patterns are illustrated against {{< person >}}, but they apply identically to every other named shortcode — only the parameter names differ.

Basic — title and a row or two

The shortest version that renders correctly: title plus the most important rows. Use this shape for short articles where the full schema would be overkill.

Absent rows are suppressed — passing occupation = "" (or omitting the param entirely) leaves no empty row in the rendered output.

Full — image, caption, alt, and below footer

When the article has a portrait or other image and additional context worth highlighting, use the full-coverage version. The image block uses the image, caption, and alt params. The below param renders a freeform footer inside the box for footnotes or see-also links.

The below text renders through markdownify, so inline emphasis and links work inside it. The block sits at the bottom of the box, full-width.

Compose with other infoboxes

A long article can carry more than one infobox. Each renders independently through the same base partial. At desktop widths they float to the right of the prose, stacking vertically; at mobile widths they stack above the body content.

Country infobox

City infobox

Each wrapper emits its own <aside class="infobox" data-infobox-type="…"> so per-type SCSS rules from your own stylesheet can target them individually.

Citations — using cite-ref and references

The cite-ref / references pair reproduces Wikipedia’s footnote pattern from Markdown’s native footnote syntax.

Ada Lovelace is widely credited as the first computer programmer for her work on Charles Babbage’s proposed Analytical Engine ^[1] . Her notes on the engine include what is recognised as the first algorithm intended to be processed by a machine ^[2] .

[^lovelace1843]: A. Lovelace, “Notes on the Analytical Engine”, Scientific Memoirs, 1843. [^esa1990]: E. A. Weiss, A Computer Science Reader. Springer, 1990.

Each [3] marker renders as a small bracketed superscript. The key must match a [^key]: text Markdown footnote definition somewhere later in the article body. Numbering follows first-citation document order.

When you need fields the wrapper doesn’t cover

When the named wrapper’s fixed schema does not cover a field, the inner-primitive escape hatch is the answer. Switch the wrapper to its paired form and drop primitives (rows, sections, image blocks, the footer block) directly inside .Inner. See docs/shortcodes/infobox-primitives.md for the five generic primitives and seven special-case pair primitives, and docs/shortcodes/person.md for the {{< person >}} parameter reference.

Adding a new shortcode

When you find yourself composing the same primitive combination across multiple articles, that’s the signal to add a new named shortcode. The full workflow — folder structure, dual-license header, the CSS hook contract — is in docs/shortcodes/customizing.md.