Human Markdown Kitchen Sink with Guardrails

This document is a practical authoring guide and stress-test for the site’s human-facing Markdown. It is written for future writers, editors, and collaborators who should not need to understand the Eleventy implementation.

The rule of thumb is simple: write normal Markdown first. Use a custom block only when the content has a clear semantic role, such as a figure, aside, video, panorama, exchange, or credits.

The guardrails

Use ordinary Markdown for prose, headings, links, lists, quotes, tables, code, and footnotes.
drop_cap: true is the only project typography switch. It enables the editorial heading/navigation treatment and automatically gives the first top-level body paragraph a drop cap.
On a drop_cap: true page, ||opening words|| is optional: it turns the remainder of the marked opening phrase into a small-caps lead-in. The drop cap itself does not depend on this marker.
There is no longform frontmatter flag; do not add one.
Use explicit inline spans for small caps and non-opening lead-ins, such as NATO, BFA, IX, and opening words.
Use a plain Markdown image for one image with a short, plain caption.
Use ::: figure for every richer media case: rich captions, multiple images, motion clips, comparisons, sequences, or wider layouts.
Add optional figure modifiers only when needed, such as compare, wide, full, sequence, or compact.
Keep media captions to one paragraph. If the explanation needs more room, write it as normal prose after the figure.
Figure captions may contain inline Markdown: links, emphasis, code spans, small caps, quote marks, and footnote references.
Figure captions may not contain headings, lists, blockquotes, tables, code blocks, or nested containers.
For asides, put the label as the first line inside the block, not after the block name.
Quote social material as an ordinary Markdown blockquote with an attribution link.
For social sources, prefer a web.archive.org URL. Include an original link only when useful.
Keep footnote definitions at document level, not inside figures, asides, exchanges, or captions.
Use tilde fences for code blocks, such as ~~~html. Avoid triple backticks in writer-facing files that may be copied through chat tools or LLMs.
When nesting containers, use a longer fence outside: :::: exchange may contain ::: figure.

A plain section

This paragraph demonstrates common inline marks: NATO, BFA, highlighted text, ~~deleted text~~, and inserted text. Use these sparingly. Inline marks are editorial signals, not decoration.

A normal hyperlink should be written as descriptive linked text. Avoid vague links like “click here.” The linked words should describe the destination.

Lists

Use bullets for unordered material:

A short point.
Another short point with a link.
A third point with an inline note.^[1]

Use numbered lists when sequence matters:

Gather the source material.
Write the paragraph in plain language.
Add semantic blocks only where they clarify the article structure.

A standard quote

The best time to plant a tree was twenty years ago. The second best time is now.
A Wise Person, Proverb

A normal blockquote is enough for most quotations. For a social post, use the same pattern but make the attribution a link to the source.

A social quote

The project changed once the archival material became visible.
OriginalPoster on Reddit, March 12, 2024

The link text carries the human-readable source information: author, platform, and date. The link target carries the citation. Prefer archived URLs.

A social quote with an original link

This is a quoted post where preserving both the archived and live locations is useful.
@example on Twitter/X, April 1, 2024, original

Use the original link only when it adds value. The archived link should usually come first.

A simple table

Feature	Status	Notes
Prose	Preferred	Write normally.
Tables	Simple only	Keep cells inline.
Captions	One paragraph	Longer explanation belongs in body text.
Social links	Archival first	Prefer Wayback links.

Do not use tables for complex layout. If a table cell needs a list, image, blockquote, or multiple paragraphs, it probably should not be a table.

Definitions

Drop cap: An oversized initial letter that opens a chapter, essay, or section.
Run-in lead: A few opening words set apart typographically to bridge the drop cap into the body text.
Asterism: A typographic mark used to indicate a minor section break or shift in subject.

Figures

Use one media block: figure.

A figure block contains one or more media items, followed by zero or one shared caption paragraph. The site decides the default layout from the number of media items:

Media count	Default treatment
1	Single figure
2	Paired figure
3+	Gallery-style figure

Optional figure modifiers can be added after figure when the default needs a hint:

Modifier	Use when
`compare`	The media should be read as a comparison, such as before/after, source/reconstruction, or obverse/reverse.
`wide`	The figure should break wider than the normal text measure.
`full`	The figure may use the full page or content width.
`sequence`	The media should be read as ordered steps.
`compact`	The media should use a denser layout, usually for many small images.

Plain image with a plain caption

Use this form for one image with a short, plain caption. Do not put links, footnotes, or complicated quote punctuation inside image-title captions.

A standalone image. — A short, plain caption.

Rich single figure

Use ::: figure when the caption needs Markdown, punctuation, footnotes, or links.

A reconstruction study shown as a single figure. — This caption can contain a source link, emphasis, small caps, quote marks like “this,” and a footnote reference.^[2]

The paragraph after a figure is normal body text. Put longer interpretation here instead of turning the caption into a miniature essay.

Two media items

Use the same figure block for two related media items. The renderer can lay them out as a pair by default.

Side A of a comparison. — Two related images with one shared caption.

Side B of a comparison. — Two related images with one shared caption.

Explicit comparison

Add the compare modifier when the relationship matters editorially, not merely visually.

Original source image. — Original source and reconstruction.

Reconstruction image. — Original source and reconstruction.

Motion figure

Writers may use the same Markdown image syntax for looping motion clips. The renderer can decide whether a source is an image or a video based on the file extension.

The process involves dripping paint onto a water bath, then dipping the material to transfer the pattern.

Three or more media items

Use the same figure block for three or more related media items. The renderer can treat this as a gallery-style layout by default.

First gallery image. — A compact shared caption describing the group, not every individual image.

Second gallery image. — A compact shared caption describing the group, not every individual image.

Figure sequence

Use the sequence modifier when order matters.

Step one: sketch. — A three-step process shown in order.

Step two: block-in. — A three-step process shown in order.

Wide figure

Use width modifiers only when the figure needs more room than the text measure.

A wide production still. — A wide figure can support a broader image without making the writer choose a visual layout class.

Asides and external references

Use an aside for a related link that is useful but not part of the main argument.

The first line inside the aside is the label. The linked title and deck stay as ordinary Markdown content. Do not use an aside for an ordinary inline citation; most references should remain normal links in body prose.

Embedded media

Panorama

Use pano for an interactive 360° viewer. Put the source after the block name. The caption remains one paragraph.

Video

Use video for an embedded or linked video. Put the public video URL after the block name. Include poster images only if the implementation later needs them; do not burden the writer by default.

Code

Use code blocks only when code is the subject of the article. For ordinary prose, prefer inline code such as figure, compare, or url.

Use tilde fences as the house style for code blocks. They are standard Markdown, support language labels, and are less likely than triple backticks to break when copied through chat tools or LLMs.

<!doctype html>
<html lang="en">
  <head>
    <title>Example</title>
  </head>
  <body>
    <p>This is a fenced code block using tildes.</p>
  </body>
</html>

Use md for Markdown examples:

::: figure
![Alt text](/m/image.avif)
Caption.
:::

If a code example itself contains tilde fences, wrap it in a longer tilde fence.

~~~html
<p>A nested fenced example.</p>
~~~

Credits

Use credits for structured production credits. Keep the format plain: role, colon, names.

Directed by

Director Name

Cinematography by

Daniel Voshart

Produced by

Producer One
Producer Two

Starring

Actor One as Character One

***

Complex material: social sources and exchanges

Social material is still just quoted and cited prose. Do not recreate platform UI unless there is a strong editorial reason. Do not make the article depend on live fetching, sidecar files, or derived metadata.

Quoted social post

This is the quoted Bluesky post. The article preserves the exact text it relies on.
Daniel Voshart on Bluesky, April 2, 2024

The attribution line should be readable even before the page is built.

Quoted Reddit comment

This is the original comment being discussed. It may contain multiple paragraphs if the original does.

This is the second paragraph of the same quoted comment.
OriginalPoster on Reddit, March 12, 2024

Use multiple blockquoted paragraphs when the source material needs them. Keep the attribution as the final blockquoted line.

Reply exchange

Use prose to explain the relationship. The Markdown grammar does not need to encode every social relationship.

Original poster wrote:

This is the original comment being replied to.
OriginalPoster on Reddit, March 12, 2024

I replied:

This is the response.

This nested quote remains an ordinary nested blockquote inside the response.

The response continues here.
Daniel Voshart on Reddit, March 12, 2024

Grouped exchange

Use exchange only when a set of related quotes should be styled as one grouped unit. The block carries no metadata. The citations remain ordinary attribution links.

Social source with images

Do not try to rebuild a platform embed. Cite the post, then use a normal figure.

The post included three reference images:

First reference image from the thread. — Images from Daniel Voshart on Bluesky, April 3, 2024.

Second reference image from the thread. — Images from Daniel Voshart on Bluesky, April 3, 2024.

Nested figure inside an exchange

If an exchange contains another container, use a longer fence outside.

Dashboard view of the application. — A short caption.

Math notation test

Inline dollar math: $E = mc^2$

Inline bracket math: $E = mc^2$

A fraction inline: $\frac{a+b}{c}$

Superscripts and subscripts: $x_1^2 + x_2^2 = r^2$

Greek letters: $\alpha + \beta = \gamma$

Square root: $\sqrt{x^2 + y^2}$

Summation: $\sum_{n=1}^{\infty} \frac{1}{n^2}$

Integral: $\int_0^1 x^2\,dx = \frac{1}{3}$

Display math with dollar delimiters:

E = mc^2

Display math with bracket delimiters:

E = mc^2

A larger display equation:

\frac{d}{dx}\left(\int_a^x f(t)\,dt\right) = f(x)

Matrix:

A = \begin{pmatrix} 1 & 2 \\ 3 & 4 \end{pmatrix}

Piecewise function:

f(x) = \begin{cases} x^2, & x \ge 0 \\ -x, & x < 0 \end{cases}

Aligned equations:

\begin{aligned} a &= b + c \\ d &= e - f \\ g &= h \times i \end{aligned}

Vector notation:

\mathbf{v} = \begin{bmatrix} v_x \\ v_y \\ v_z \end{bmatrix}

Set notation:

A = \{x \in \mathbb{R} \mid x > 0\}

Probability:

P(A \mid B) = \frac{P(B \mid A)P(A)}{P(B)}

Limit:

\lim_{x \to 0} \frac{\sin x}{x} = 1

Complex numbers:

e^{i\pi} + 1 = 0

Units and text inside math:

v = 12\,\mathrm{m/s}

Text inside an equation:

\text{Area} = \pi r^2

Currency collision test — these should remain ordinary text:

The object cost $20.

The price increased from $20 to $30.

The budget was approximately $1.5 million.

Code collision test — this should remain code and not render as math:

const price = "$20";

And this fenced block should also remain untouched:

const equation = "$E = mc^2$";
const latex = "\\(x^2 + y^2\\)";

Boxed math

\boxed{E = mc^2}

\boxed{x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}}

\boxed{\text{Final Answer}}

What not to do

Do not put a complex caption in an image title. Use ::: figure instead.

Do not write multi-paragraph captions. Write one caption paragraph, then continue in body prose.

Do not use pair or gallery as author-facing blocks. Use ::: figure and let the renderer decide the layout.

Do not put aside labels after the block name. Use ::: aside, then put the label as the first line inside the block.

Do not model social posts as metadata blocks. Quote them as blockquotes with attribution links.

Do not rely on a build script to fetch social metadata. The article should preserve the quoted text and source link directly.

Do not omit source URLs from social material. Use archived URLs where possible.

Do not use a table for layout.

Do not nest blocks inside captions.

Do not use a short outer fence around a block that contains other fenced containers.

Do not use triple backticks as the house style for code blocks. Use tilde fences instead.

A simple footnote called from a list item. ↩︎
A footnote called from a rich figure caption. The definition stays at document level. ↩︎
A footnote called from a video caption. ↩︎