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.
• nimbus.json — a committed record of what your project is made of (see below).

nimbus.json — the provenance record

Alongside your files the scaffolder writes a small, CLI-managed nimbus.json. It records the create-nimbus-docs version and the templates-v* tag your starter came from, where components install (install.root), and one entry per component you add — each with its source registry, the registry release it shipped in, and a content hash.

It is the machine half of a pair: your behavior config (versions, features, sidebar) is human-authored in astro.config.ts via nimbus(...); nimbus.json is the surface the CLI reads and rewrites. nimbus-docs add appends to it; nimbus-docs init rebuilds it for a project that predates it or is adopting Nimbus. Commit it — it is how upgrades know what you own (it is not .nimbus/, which is 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.