Components

Every .mdx file can use these components without an import. Reusable partials use Render; the UI components live in src/components/ui/, so you can change how they look or work.

Reader tools

The layout adds these tools automatically to documentation pages:

• Breadcrumbs show the path from Home to the current page. The homepage has no parent, so it does not show a breadcrumb trail.
• The table of contents follows the page headings. Wide screens get a right-hand rail; smaller screens get a section menu below the title.
• Page actions let readers copy the page as Markdown or open its Markdown version. The updated date comes from Git history.
• Search, a theme switcher, heading permalinks, code-copy buttons, and previous/next navigation are included.
• “Edit this page” opens the source on GitHub for repository collaborators. The repository is private.

Write headings and code blocks normally; the layout provides these tools without adding components to the page body.

Aside

Set a note, tip, caution, or warning apart from the text around it.

<Aside type="note">
  Pages are validated at build time.
</Aside>

<Aside type="caution" title="Before you deploy">
  Set `site` in `astro.config.ts` to your production URL.
</Aside>

For a title with formatting, pass it as a slot: <Fragment slot="title">Uses <code>env</code></Fragment>.

Steps

Number a procedure. Each step has a title and its own content.

<Steps>
  <Step title="Create the page">
    Add `src/content/docs/deploy.mdx` with a `title`.
  </Step>
  <Step title="Preview it">
    Run `npm run dev` and open the page.
  </Step>
</Steps>

Tabs

Show the same content in several variants. Give tabs a syncKey, and the reader’s choice carries over to every set of tabs with the same key.

<Tabs syncKey="os">
  <TabItem label="macOS">
    Press <kbd>⌘</kbd> <kbd>K</kbd> to search.
  </TabItem>
  <TabItem label="Windows">
    Press <kbd>Ctrl</kbd> <kbd>K</kbd> to search.
  </TabItem>
</Tabs>

Package managers

Write an install command once and show it for npm, pnpm, Yarn, and Bun.

npm i your-package

yarn add your-package

pnpm add your-package

bun add your-package

<PackageManagers pkg="your-package" />

Add dev for a dev dependency, or type="run" args="build" for a script.

Cards

Link readers to the next places to go, in a grid that stacks on small screens.

<CardGrid>
  <Card title="Write a page" icon="ph:pencil-simple">
    Create an `.mdx` file in `src/content/docs/`.
  </Card>
  <Card title="Change the theme" icon="ph:palette">
    Edit the colour and type tokens in `src/styles/globals.css`.
  </Card>
</CardGrid>

Icons come from Phosphor: use any name with the ph: prefix.

Code display

Fenced code blocks get syntax highlighting, a copy button, and light/dark themes. Add a filename with title and highlight lines with braces:

const site = {
  url: "https://nimbus.focal.host",
  title: "Nimbus",
};

Use Code when the code comes from a string. Wrap blocks in CodeGroup to show language alternatives:

const site = "https://nimbus.focal.host";

const site: string = "https://nimbus.focal.host";

<CodeGroup titles={["JavaScript", "TypeScript"]}>
  <Code code={'const site = "https://nimbus.focal.host";'} lang="js" meta='title="site.js"' />
  <Code code={'const site: string = "https://nimbus.focal.host";'} lang="ts" meta='title="site.ts"' />
</CodeGroup>

File trees

Use a nested Markdown list to describe project structure. A trailing slash makes a folder collapsible; bold text highlights an entry.

<FileTree>

- src/
  - content/
    - docs/
      - **index.mdx**
- astro.config.ts

</FileTree>

Accordions

Keep optional explanations in expandable sections. Use ordinary headings for information every reader needs.

<Accordion>
  <AccordionTrigger>When should I use an accordion?</AccordionTrigger>
  <AccordionContent>
    For optional details that would interrupt the main explanation.
  </AccordionContent>
</Accordion>

Badges and link buttons

Use badges for short status labels and link buttons for a clear next step.

<Badge text="Available" variant="success" />
<LinkButton href="/writing-pages/" variant="secondary" icon>Start writing</LinkButton>

Partials

Write a passage once and include it on any page. Partials live in src/content/partials/.

This text lives in src/content/partials/example.mdx and is pulled in with <Render file="example" />. Edit the partial once and every page that renders it stays in sync — handy for install steps, support notes, or any boilerplate you’d otherwise copy between pages.

<Render file="example" />

Restyle any part

Every part of every component has a data-slot attribute, so you can restyle one piece from src/styles/globals.css without editing the component.

[data-slot="card-title"] {
  letter-spacing: -0.01em;
}

Corners come from two tokens in the same file: --nb-radius for cards, callouts, code blocks and buttons, and --nb-radius-sm for the small marks inside them. Change them to re-round the whole site.

Add more

Link cards, embeds, and other additions install from the registry when you need them. Each one lands as a file in src/components/ui/, like the components above.

npx @cloudflare/nimbus-docs add embed

yarn dlx @cloudflare/nimbus-docs add embed

pnpm dlx @cloudflare/nimbus-docs add embed

bunx @cloudflare/nimbus-docs add embed