Pages and frontmatter

Every Markdown (.md) or MDX (.mdx) file under src/content/docs/ is a page. Its path is its URL:

File	URL
src/content/docs/index.mdx	/
src/content/docs/writing/pages.md	/writing/pages/
src/content/docs/guides/install.md	/guides/install/

Use .md for plain writing. Use .mdx when a page needs components such as tabs or cards.

Frontmatter

The block between the --- lines at the top of a file. Only title is required:

---
title: Installing the CLI
description: One command on macOS and Linux, and how to check it worked.
sidebar:
  order: 2
  label: Install
---

The page starts here.

Field	What it does
title	The page heading, the browser tab and the sidebar entry.
description	The search-result snippet and the social preview text. Write it as one sentence that stands on its own.
sidebar.order	Position within its sidebar group. Lower comes first.
sidebar.label	A shorter sidebar entry, when the title is long.
sidebar.badge	A small label next to the sidebar entry, such as New.
draft	true keeps the page out of the production build.
template	splash for a full-width page with no sidebar, like the home page.
tableOfContents	false hides the “On this page” list.

Headings

Start the page body at ##. The title is the page’s one # heading, and every ## and ### appears in the table of contents.

Links between pages

Link with the URL, not the file path:

See [Deploying](/publishing/deploy/) for how releases work.

A link to a page that does not exist builds without complaint and 404s for the reader, so check new links in the dev server before you push.