Writing pages

Frontmatter

Each file starts with YAML metadata. The title becomes the page heading; the remaining Markdown forms the article.

---
title: Installation
description: Set up your documentation project.
order: 1
draft: false
---

For the complete field list, see Frontmatter reference.

Links and routes

Additional metadata separates navigation and search-engine titles from the page heading. slug retains the public URL when a source file moves:

navTitle: Install
seoTitle: Install the SDK
slug: guides/install
updatedAt: 2026-10-02
tags: [setup, sdk]
badge: New
layout: reference
search: true
noindex: false

updatedAt must be a real calendar date. layout: reference widens reference content; it is not an Astro component import. search: false omits a page from search. noindex: true also omits it from sitemap, Markdown and AI exports, but the HTML page remains publicly accessible. Drafts are excluded from production.

Use Markdown file links such as [Introduction](index.md), or root-relative documentation routes such as [Introduction](index.mdx). The builder checks page and heading targets, then adds the configured deployment base.

Headings

The frontmatter title is the only H1. Start article sections at H2. A source H1 is rendered as H2; other levels are preserved. Repeated headings receive distinct IDs, and headings inside code fences never enter the table of contents.

Raw HTML is displayed as text. Use normal Markdown for prose, lists, code, and tables.

MDX and React

Use .mdx for trusted project content that imports local or installed components. Static Astro components need no configuration. For React 19, install react and react-dom, set react: true, and add a client directive only when the component needs browser interaction:

import Counter from "../components/Counter.jsx"

<Counter client:visible />

Without client:load, client:idle, or client:visible, a React component is rendered as static HTML. Ordinary pages do not receive the React runtime. MDX and module configuration execute trusted project code during the build; do not use them for untrusted or remotely supplied content.

Inside authored JSX, use import.meta.env.BASE_URL for local site URLs so links work at both / and a deployment subpath.

Drafts

Set draft: true to exclude a page from production builds. Remove references to that draft from configured navigation and published pages before building.

Callouts

Use a blockquote with an uppercase marker on its first line. Supported markers are NOTE, TIP, WARNING, and CAUTION.

> [!NOTE]
> Keep configuration files in version control.

Callouts support Markdown paragraphs, links, and lists. Other markers remain ordinary blockquotes. Their labels do not appear in the table of contents.

Heading permalinks

Each section heading has a keyboard-accessible # link to its section. Heading IDs are generated from the heading text; duplicate headings receive distinct IDs. Renaming a heading changes its link, so update references when editing it.

Structured authoring

Use authoring components in MDX for steps, link cards, tabs, package-manager commands, and API references. These components are static by default; only tabs add a small progressive-enhancement script.