Build your docs

Write content

Create MDX documentation pages with frontmatter, links, callouts, cards, steps, tabs, and code examples.

Write pages as MDX files in the project root. Each page should teach one clear task, concept, or reference topic.

Create a page

Add a file such as installation.mdx:

mdx
---
title: "Installation"
description: "Install the package and verify that it works."
---

This page explains how to install the package.

## Install

\`\`\`bash
npm install your-package
\`\`\`

Then add the page slug to site.config.ts:

ts
navigation: {
  groups: [
    {
      group: "Start here",
      pages: ["index", "getting-started", "installation"],
    },
  ],
}

The slug is the file path without .mdx.

Frontmatter

Every page should include:

  • title: The page heading and search result title.
  • description: A short summary for search, metadata, and page previews.
  • sidebarTitle: Optional shorter label for navigation.

Use root-relative links for internal pages:

mdx
Read [Deploy to Vercel](/deploy-to-vercel).

Use full URLs for external pages:

mdx
Read the [Next.js documentation](https://nextjs.org/docs).

Built-in MDX components

Use components when they make the content easier to scan.

Cards

Link readers to related pages.

Callouts

Highlight notes, tips, checks, and warnings.

Steps

Use steps for ordered workflows:

  1. Open the file you want to edit.
  2. Make one focused change.
  3. Run npm run type-check before you publish.

Tabs

Use tabs when readers need to choose one option:

bash
npm install

Code blocks

Code fences support titles, line numbers, highlighting, focus, wrapping, and copy buttons:

site.config.ts
export const siteConfig = {
  name: "Your Docs",
  shortName: "Docs",
};

Next step: Customize the site