Adding Components to Your Pages

Markdoc (.mdoc) pages can use components written as Markdoc tags — {% tag %}…{% /tag %} — with no imports, which is what keeps them editable in Keystatic. The tags below come from two places: Starlight’s Markdoc preset, and one custom project tag.

These tags work in .mdoc files. In a plain .md file they render as literal text, so use them only on .mdoc pages — see Choosing a Page (File) Format for when a page should be .md, .mdoc, or .mdx.

Asides (callouts)

{% aside type="tip" title="Heads up" %}
Body of the callout.
{% /aside %}

type is note (the default), tip, caution, or danger; title is optional. See Starlight asides.

Embed a source file — showcode (custom)

A project-specific tag that inserts the actual contents of a real file, read at build time, as a highlighted block with a copy button — so the docs can’t drift from the source they show:

{% showcode file="src/content/tokens/tokens.yaml" lang="yaml" title="tokens.yaml" /%}

• file (required) — path relative to the docs/ project root.
• lang (optional) — language for syntax highlighting.
• title (optional) — label shown above the block.

It’s named showcode, not code, on purpose: Keystatic’s editor reserves code for inline code, so a code tag would break the visual editor. For literal, hand-written code, use a fenced code block instead (below).

Code blocks

A normal fenced code block renders with syntax highlighting and a copy button (Expressive Code). This is plain Markdown and works in every format (.md, .mdoc, .mdx):

```sh
npm run build
```

Other Starlight components

The Starlight Markdoc preset also registers the tags below. Their attributes mirror the matching Starlight component — see Using components and the component reference.

Tag	Purpose
badge	Small inline label.
card / cardgrid	Boxed callouts, optionally arranged in a grid.
linkcard / linkbutton	Prominent navigation links.
steps	Numbered, step-by-step lists.
tabs / tabitem	Tabbed content.
filetree	A rendered file/directory tree.
icon	An inline Starlight icon.

Example — tabbed content:

{% tabs %}
{% tabitem label="npm" %} Use `npm install`. {% /tabitem %}
{% tabitem label="pnpm" %} Use `pnpm install`. {% /tabitem %}
{% /tabs %}