Images & media

Drop in a picture, caption it, size it, align it, and embed audio or video — all with writer-friendly parameters, no CSS. Sizing and alignment compile to inline styles, so they travel intact into HTML, raw output, and PDF.

A plain image

An image needs a source and, for anyone who can't see it, alternative text:

@img |src ./harbour.jpg| |alt The harbour's east jetty|

The src is a path or URL; alt describes the image. Keep the whole description on one parameter — an apostrophe inside it is fine.

A captioned figure

Wrap the image in a figure and add a caption to pair a picture with its label:

@figure
@img |src ./chart.svg| |alt Downloads by platform| |size large|
@figcaption Figure 1. Downloads by platform, this cycle. figcaption@
figure@

You get a semantic <figure> around the <img> and its <figcaption>. A figure centres itself and its caption by default, so it drops into a column and looks right with no further fuss.

Sizing

The size parameter takes a named preset, a raw pixel number, or a percentage. Presets and pixel values cap the width and never enlarge a small source; full or a percentage fills the available width:

So a preset guarantees an image never balloons past a comfortable width, while full or a percentage lets a chart stretch to the column. A source smaller than the cap keeps its natural size — presets only shrink.

Alignment

The align parameter takes left, center, or right — with a small difference between an image and a figure:

• On an image, it block-positions the image itself: centred, pushed right, or pushed left within its line.
• On a figure, it sets the alignment of the figure's contents — the image and caption together.

Size and alignment compose. Asking for medium and centred emits both the width cap and the centring margins in one style attribute:

@img |src ./map.png| |alt Coast survey| |size medium| |align center|

Links

The link text is the body; the address rides in a parameter:

Visit @a |href https://example.org| the Example archive a@ for the back issues.

That renders "Visit" followed by a link reading "the Example archive", then the rest of the sentence. Omit the address and the link falls back to a harmless placeholder, so a half-written link never breaks the build — but fill it in before you publish.

To open a link in a new tab, add a target parameter:

@a |href https://example.org| |target _blank| the archive, in a new tab a@

Audio and video

Embed a media file with the audio or video node. Give it a source and turn on the player controls:

@audio |src ./bell.mp3| |controls true| audio@

@video |src ./tour.mp4| |controls true| video@

Each renders the matching HTML media element with controls shown — a play button, a scrubber, a volume control in the browser.

Where media degrades

Links survive every output format. Audio and video are HTML-only: Markdown has no media element, and a PDF can't play a video. Treat embedded media as an HTML enhancement and make sure the surrounding prose stands without it.

Paths

Keep src paths relative to your document. HTML resolves them against wherever the finished file sits. For PDF, the build renders through a headless browser and injects a base URL pointing back at your document's directory, so a relative path like ./assets/chart.svg still resolves. Either way, relative paths are the safe habit.

See also

• Structure — an image beside text with rows and columns.
• Tables — the other construct that carries data in a parameter.
• Rendering — how each output format handles media.