---
title: "Project structure"
description: "What the scaffolder writes into your repo, the line between your files and the framework, and how the tree becomes the site."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

- my-docs/
  - public/
  - src/
    - components/
      - ui/
    - content/
      - docs/
    - layouts/
    - lib/
    - pages/
    - styles/
      - globals.css
    - components.ts
    - content.config.ts
  - AGENT.md
  - CLAUDE.md
  - astro.config.ts
  - nimbus.json
  - package.json
  - tsconfig.json
  - pnpm-workspace.yaml
  - wrangler.jsonc

- **`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](/writing/markdown-and-mdx).
- **`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](/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`](/cli).
- `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`](/cli), 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`](/cli) writes to it, and [`nimbus-docs init`](/cli) 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.

- src/content/docs/
  - introduction.mdx
  - guides/
    - styling.mdx
    - deploying.mdx
  - reference/
    - api.mdx

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](/writing/pages-and-routing) for the details.

Source: https://nimbus-docs.com/project-structure/index.mdx