Writing pages

Every page is an .mdx file in src/content/docs/. The file path becomes the URL, so src/content/docs/guides/deploy.mdx is served at /guides/deploy/. Start from the introduction if you haven’t opened the project yet.

Create a page

Add a file with a title in its frontmatter. The title becomes the page heading, so don’t repeat it in the body.

src/content/docs/guides/deploy.mdxmdx

---
title: Deploy
description: Ship the site to production.
---

Run the build, then upload the output.

Frontmatter is validated at build time. A missing title or a misspelled field fails the build with a message that names the file and the field.

title is required. Everything else is optional.
description appears under the heading, in search results, and in social cards.
sidebar controls where the page sits in the navigation.
- order sorts pages within a group, lowest first.
- badge adds a short label next to the link.

Frontmatter fields

Field	Type	Description
`title`	string	The page heading and the `<title>` tag.
`description`	string	One-line summary for search, social cards, and the page header.
`sidebar.order`	number	Position within the sidebar group. Lower numbers come first.
`draft`	boolean	Builds the page in development only. It never reaches production.

Write with Markdown

Standard Markdown works everywhere: bold, italic, links, inline code, lists, tables, and fenced code blocks. Press ⌘ K to search the site for anything else.

Write the page you would want to find. One topic per page, and a title that says what the reader will be able to do.

Code blocks are highlighted at build time. Add a title to show a filename, and line numbers in braces to draw attention to specific lines.

astro.config.tsts

const nimbusConfig = defineNimbusConfig({
  site: "https://docs.example.com",
  title: "My docs",
  description: "Guides and reference for My product.",
});

Folders become sidebar groups. Inside a group, pages sort by sidebar.order, then by title.

Create a folder in src/content/docs/, for example guides/.
Move related pages into it.
Set sidebar.order on each page to fix the order.

Use components

Components are available in every .mdx file without an import. Install more from the registry when you need them.

Add a component
Run npx @cloudflare/nimbus-docs add accordion to copy it into src/components/ui/.
Register it
Add it to src/components.ts so every page can use it.

npx @cloudflare/nimbus-docs add accordion

pnpm dlx @cloudflare/nimbus-docs add accordion

What ships with the starter

Aside: Notes, tips, cautions, and warnings that stand apart from the text.
Steps: Numbered procedures, each with a title and its own content.
Tabs: The same content in several variants, such as one command per package manager.

Can I use plain Markdown files instead of MDX?

Yes. MDX is a superset of Markdown, so any .md content works unchanged in an .mdx file. You only need MDX syntax when you add a component.

Pages you write today keep working when you upgrade Nimbus¹. Use highlights sparingly; they lose their meaning when everything is marked.

Changes that need your attention are listed by npx @cloudflare/nimbus-docs migrate --dry-run. ↩