Project structure

A scaffolded Nimbus project is a regular Astro project. Everything visible lives in your repo as real files; the framework ships the plumbing as a dependency.

What lands in your repo

• src/components/ — UI components, yours to edit or replace.
• src/content/docs/ — your MDX content. The tree here is the site (see below).
• src/layouts/ — page shells (BaseLayout, DocsLayout).
• src/pages/ — routes, including the docs catch-all, alternate Markdown/MDX versions, and llms.txt indexes.
• src/styles/globals.css — design tokens and Tailwind layers.
• src/components.ts — the MDX globals registry.
• src/content.config.ts — your content collections.
• AGENT.md — the guide for coding agents working in the project. CLAUDE.md points to it.
• nimbus.json — a committed record of what your project is made of (see below).
• pnpm-workspace.yaml — pnpm only, for its dependency build-script settings. Yarn sites get .yarnrc.yml instead.
• wrangler.jsonc — only when you deploy to Cloudflare.

A site with an API reference also has its spec at src/api/, its route at src/pages/api/[...slug].astro, and the reference components in src/components/ui/, recorded in nimbus.json like components from nimbus-docs add. A site that is only the reference has no src/content/docs/, and its route is src/pages/[...slug].astro. See API reference to configure it.

nimbus.json — the provenance record

Alongside your files the scaffolder writes a small, CLI-managed nimbus.json. It records:

• version and templatesTag: the create-nimbus-docs version and the templates-v* tag your starter came from.
• lastReviewedNimbusVersion: the last Nimbus version whose upgrade steps the site has reviewed with nimbus-docs migrate.
• templatesTagByFile: the tag each file taken with nimbus-docs diff --apply came from.
• install.root: where components install.
• components: one entry per component you add, with its source registry, the registry release it shipped in, and a content hash.

You write your site’s behavior, such as versions and the sidebar, in astro.config.ts. nimbus.json is the CLI’s half: nimbus-docs add writes to it, and nimbus-docs init creates it for a project without one.

Commit it: it’s how upgrades know what you own. (.nimbus/ is different: gitignored build scratch.)

The framework boundary

The nimbus-docs package is the invisible half — the Astro integration, data helpers (getSidebar, getPrevNext, getTOC), content schemas, and helpers for alternate Markdown/MDX versions and llms.txt indexes. You import it; you don’t fork it.

Everything else is yours. There is no upstream theme to override and no API to break — coding agents reason about the repo more easily when nothing important hides behind an import boundary.

The tree is the truth

The directory structure under src/content/docs/ is the URL structure and the sidebar. Move a file and its route and sidebar entry move with it; delete a file and both disappear. Frontmatter handles the fine grain — order, badges, draft state — but the shape of the site comes from the filesystem.

There is no second navigation config to keep in sync. The site can’t drift from its own contents, because its contents are the site. See Pages and routing for the details.