Components, images and media

Make pages richer with callouts, steps, images, GIF recordings and the Media block.

0:00 / 0:19

Images

docs/quickstart.md

![The inbox receiving its first email](./images/first-email.gif)

PNG, JPEG, WebP or GIF — checked by bytes, never by extension
2 MiB per file, 20 MiB per project
Paths are relative to the page and must stay under docs/
Images must be their own block — not inside a sentence
Alternative text is required to be meaningful

Recordings and video

The reader embeds no video player. For a short recording, use an animated GIF as an image. For a longer walkthrough, use Media on the homepage: a poster with play chrome, a caption, a duration, and a link to the written steps.

docs/index.mdx

<Hero eyebrow="TestInbox · v1">
  <Action label="Get started" href="./quickstart" />
  <Media
    poster="./images/see-it-work.png"
    alt="A test creating an inbox and the email arriving."
    caption="See it work: from create() to a passing test."
    duration="0:42"
    linkLabel="Show as steps"
    linkHref="./quickstart"
  />
</Hero>

NoteAlways provide the written path

Because the play chrome is decorative, the caption should say what the media shows and linkHref should point to an equivalent written page.

Edge cases

SVG in page content

CONTENT_ASSET_UNSUPPORTED

✕ FAILS

docs/arch.md

![Architecture](./images/arch.svg)

✓ FIX

docs/arch.md

![Architecture](./images/arch.png)

SVG is allowed for the logo, not in content.

GIF over 2 MiB

CONTENT_ASSET_TOO_LARGE

✕ FAILS

docs/

images/walkthrough.gif   6.4 MB

✓ FIX

docs/

# trim to ≤ 12 s, reduce colours and size,
# or use <Media> with a poster on the homepage

Each image is capped at 2 MiB.

Image inside a sentence

CONTENT_UNSUPPORTED

✕ FAILS

docs/x.md

Click ![gear](./gear.png) to open settings.

✓ FIX

docs/x.md

Open **Settings**.

![The settings panel](./settings.png)

Images are block-level only.

Hero not first

CONTENT_COMPONENT_NESTING_INVALID

✕ FAILS

docs/index.mdx

Welcome!

<Hero>…</Hero>

✓ FIX

docs/index.mdx

<Hero>…</Hero>

Welcome!

`Hero` must be the first block of the homepage.