Authoring Content

Writing docs with this theme is mostly writing Markdown. This guide covers the project layout, page frontmatter, and the built-in components you’ll reach for most. Everything here works in .md files except the components, which require .mdx.

Where content lives

All pages live under src/content/docs/. The path of a file becomes its URL, so organize directories to match your sidebar groups:

• Directorysrc/content/docs

  • index.mdx / — your landing page
  • Directorygetting-started

    • installation.mdx /getting-started/installation/
    • quickstart.mdx
  • Directoryguides

    • authoring-content.mdx
    • Directorydeployment

      • build.mdx /guides/deployment/build/
  • Directoryreference/

    • …

Page frontmatter

Every page starts with a YAML frontmatter block. title is required; the rest is optional:

src/content/docs/guides/example.md

---
title: Example page
description: Shown in search results and social cards.
sidebar:
  order: 2        # control position within its group
  badge: New      # a badge next to the sidebar label
---

Your content starts here.

Note

description feeds both the page’s <meta> tag and its Pagefind search result snippet. Write it for a human skimming search results, not for keywords.

Callouts (asides)

Use asides to pull the reader’s attention aside without breaking the flow. The theme maps their colors to Nebari’s feedback tokens.

Note

A neutral aside for context or a side remark.

Tip

A tip — the friendly “here’s a shortcut” callout.

Heads up

A caution, with a custom title in brackets. Use it for footguns.

Danger

A danger callout for irreversible or destructive actions.

The syntax is a fenced block with the variant name:

:::tip
This is a tip.
:::

Code blocks

Code blocks are styled with Fira Code and support titles, line highlighting, and diff markers via Expressive Code (bundled with Starlight):

astro.config.mjs

starlight({
  title: 'My Pack',
  plugins: [nebari()],
  // sidebar: legacyConfig,
  sidebar: newConfig,
});

Group related commands with tabs so readers see only their package manager:

npm

npm run build

Bun

bun run build

Tip

Give <Tabs> a syncKey and every tab group with the same key switches together across the whole site — set it once to “npm” and all your install snippets follow.

Numbered procedures

Wrap an ordered list in <Steps> for a visually distinct walkthrough:

1. Write the page under src/content/docs/.

2. Add it to the sidebar in astro.config.mjs.

3. Run npm run dev and check it renders.

Badges

Use <Badge> inline to flag status: New, Beta, or Deprecated. Variants are note, tip, caution, danger, success, and default.

Linking between pages

Use root-relative links so they keep working under a base path:

See the [configuration reference](/reference/configuration/).

Caution

Don’t link to the source file (configuration.mdx) — link to the built URL (/reference/configuration/), with a trailing slash. Broken internal links fail the build.

Next

• Customizing the Theme — colors, logo, and overrides.
• Components reference — every component and its props.