Writing pages

Every source page is an .md or .mdx file under the pages/ directory with a small frontmatter block:

pages/quickstart.mdx

---
title: Quickstart
description: From zero to a running site in five minutes.
---

Your content starts here.

Create the page file

Create the file itself under pages/ before adding it to navigation. For example, create pages/guides/setup.mdx for a guide whose navigation path will be guides/setup.

pages/guides/setup.mdx

---
title: Setup
description: Configure the project for local development.
---

Follow these steps to configure the project.

Navigation

After creating the page file, add its path to docs.json so it appears in the sidebar:

docs.json (excerpt)

{
  "navigation": {
    "groups": [
      { "group": "Getting started", "pages": ["index", "quickstart"] }
    ]
  }
}

Info:

The pages entries are paths relative to the pages/ directory, without the .md or .mdx extension. For example, pages/guides/setup.mdx becomes guides/setup. Order in the array is order in the sidebar.

Header tabs

Larger sites can split the navigation into top-level spaces — the header tabs you see on this site. Replace groups with tabs, where each tab holds its own groups and gets its own sidebar:

docs.json (excerpt)

{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          { "group": "Getting started", "pages": ["welcome", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "API reference",
            "pages": ["api-reference/overview"],
            "openapi": "api-reference/openapi.yaml"
          }
        ]
      }
    ]
  }
}

Info:

A tab links to its first page. The sidebar, search filtering, and previous/next links all scope to the active tab; the AI assistant still answers from the whole site.

Frontmatter fields

titlepathstringrequired

The page title, shown in the sidebar, the browser tab, and search results.

descriptionpathstring

A one-sentence summary used for search-engine metadata and the AI assistant’s context.