Images & media

Drop in a picture, caption it, size it, align it, and embed audio or video — all with 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, at low tide)

<img src="./harbour.jpg" alt="The harbour's east jetty, at low tide">

The src is a path or URL; alt describes the image. A value runs to the next parameter name, so it can hold commas and apostrophes without quotes. An image takes no body and no closer.

A captioned figure

Wrap the image in a figure and add a caption:

@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.

Sizing

size takes a named preset, a 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:

You write	Emitted style	Behaviour
size: small	max-width 220px	caps the width
size: medium	max-width 380px	caps the width
size: large	max-width 600px	caps the width
size: full	width 100%	fills the column
size: 240	max-width 240px	caps at that many pixels
size: 50%	width 50%	fills that fraction

Alignment

align takes left, center, or right. On an image it positions the image within its line; on a figure it aligns the figure's contents — image and caption together.

Size and alignment compose into one style attribute:

@img(src: ./map.png, alt: Coast survey, size: medium, align: center)

<img src="./map.png" alt="Coast survey" style="max-width:380px;height:auto;display:block;margin-left:auto;margin-right:auto">

Links

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

Visit (a(href: https://example.org/archive) the back issues a) before Friday.

Parentheses inside an address balance, so a URL like https://en.wikipedia.org/wiki/Mercury_(planet) keeps its own. To open a link in a new tab, add target: _blank:

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

Audio and video

Give a media node a source and turn on the player controls:

@audio(src: ./bell.mp3, controls: true)

@video(src: ./tour.mp4, controls: true)

<audio src="./bell.mp3" controls></audio><video src="./tour.mp4" controls></video>

Each renders the browser's player — play button, scrubber, volume.

Where media degrades

Links and images survive every output format. Audio and video are HTML-only: Markdown has no media element, and a PDF can't play a video. Make sure the surrounding prose stands without them.

Paths

Keep src paths relative to your document. HTML resolves them against wherever the finished file sits. For PDF, the build points the headless browser back at your document's folder, so ./assets/chart.svg still resolves.