Components

Doc components express semantics such as notes, diffs, structured blocks, and columns. Most components can be used as MDX tags or Markdown directives.

If you mainly need a syntax cheat sheet instead of rendered examples, go straight to Authoring Syntax.

Callout

Callouts should reflect intent:

• Tip/Note: neutral white block for light hints or clarifications.
• Info: blue block for stable info or consistency notes.
• Warning: orange block for risks or hard constraints.
• Deprecated: red block for deprecations and migration notices.

Alerts (GitHub syntax)

Use GitHub-style alerts in Markdown and they will map to callouts automatically.

Columns

Cards

Use cards to surface key entry points, landing sections, or recommended reading. The grid defaults to four columns and collapses to two on mobile.

• Quickstart

  Install dependencies and scaffold the docs.

• Components

  Built-in MDX UI primitives.

• Project structure

  Understand content and navigation layout.

• Build validation

  CI checks for doc quality and broken links.

Cards (directive)

• Quickstart

  Install dependencies and scaffold the docs.

• Components

  Built-in MDX UI primitives.

• Project structure

  Understand content and navigation layout.

• Build validation

  CI checks for doc quality and broken links.

Link Buttons

Badges

Inline syntax: Experimental.

Math Equations

Inline math uses $...$. Block math uses $$...$$ and renders with KaTeX.

Inline example: $E = mc^2$.

Diff Block

Use to compare two approaches side by side. beforeLabel and afterLabel are optional when you want the top labels.

Code Block

Use standard Markdown code fences. The renderer adds the shared code styling and copy action.

export const navStrategy = "filesystem";
export const contentPath = "content";

Colored Diffs

Lines starting with + or - in code blocks are rendered with diff backgrounds for upgrade guides.

- cache: "manual"
+ cache: "filesystem"

Code Tabs

Switch between multiple snippets inside one block. Use the code-group directive without extra JSX.

const completion = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Jane, 54 years old" }],
});

const response = await openai.responses.create({
  model: "gpt-5",
  input: "Jane, 54 years old",
});

Rich panels

For mixed content (text, images, blocks), use :::code-group with :::tab panels.

[docs]
static = true

:::

Steps

Turn ordered lists into step-by-step flows for long procedures.

1. Install the typematter dependencies.

2. Update the content/ directory structure.

3. Run npm run validate:docs before building.

File Tree

Render Markdown lists as a file tree with collapsible folders.

Details / Accordion

Use collapsible blocks for supporting or optional content.

Annotations

Inline annotations add contextual tooltips that still support Markdown.

This API is experimental iHeads upSee the migration guide for constraints..

Feature Matrix

Compare multiple offerings with a semantic Markdown table.

Endpoint / ParamTable / ResponseSchema

Use this set for API reference pages. The goal is to split endpoint header, parameters, and response structure into stable semantic blocks instead of loose prose and ad-hoc tables.

Directive syntax

:::endpoint{method="GET" path="/v1/docs/[slug]" title="Fetch a doc page" summary="Returns registry metadata for a route." auth="optional" since="0.4.0-rc"}:::param-table[Path params]::param-field[slug]{type="string[]" required="true" description="Route segments for the document."}::param-field[lang]{type='"cn" | "en"' default="cn" description="Language code."}::::::response-schema[200 Response]{code="200" mediaType="application/json"}::schema-field[title]{type="string" required="true" description="Page title"}::schema-field[section]{type="string" required="true" description="Section name"}:::schema-field[toc]{type="TocItem[]" description="Structured headings"}::schema-field[id]{type="string" required="true" description="Anchor id"}::schema-field[title]{type="string" required="true" description="Heading text"}::schema-field[level]{type="number" required="true" description="Heading depth"}:::::::::

DoDont

This is useful for best practices, migration rules, and review checklists where "do this / don't do this" is the core message.

Directive syntax

:::do-dont[When writing API docs]:::do[Keep fields stable]Public field names, enum values, and error codes should stay stable over time.::::::dont[Do not rely on examples alone]Example responses do not replace field-level structure.::::::

VersionGate

Use this to make it obvious when a capability was introduced, deprecated, or removed.

Directive syntax

:::version-gate[Legacy search index]{since="0.2.0" deprecated="0.4.0" removedIn="1.0.0" replacement="standard search manifest"}When a feature enters migration mode, do not just say "this may change later". Put the version policy next to the feature itself.:::

CommandGroup

Use it to switch commands by package manager, operating system, or environment.

pnpm install
pnpm dev

npm install
npm run dev

yarn
yarn dev

bun install
bun run dev

Directive syntax

:::command-group[Install Typematter]:::command[pnpm]{description="Recommended"}```bashpnpm installpnpm dev```::::::command[npm]```bashnpm installnpm run dev```::::::

PreviewFrame

Use this for screenshots, recordings, product demos, or same-origin iframe previews.

Directive syntax

::preview-frame[Quickstart page preview]{src="/en/get-started/quickstart/" caption="Good for same-origin page previews. You can also pass an image or video source."}

Timeline / ReleaseItem

Use it for version history, migration stages, and breaking change narratives.

Directive syntax

:::timeline:::release-item[Initial shell]{version="0.1.0" date="2026-01-26"}Introduced the static docs shell, MDX loading, and base navigation.::::::release-item[Versioning and localized search]{version="0.4.0-rc" date="2026-03-20" status="Current"}Added version links, document-type templates, richer Chinese search aliases, and improved Ask AI retrieval.::::::