---
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://docs.klounge.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Project structure

import { FileTree } from "@/components/ui/file-tree";

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/
  - src/
    - components/
      - ui/
    - content/
      - docs/
    - layouts/
    - pages/
    - styles/
      - globals.css
    - components.ts
  - astro.config.ts
  - nimbus.json
  - package.json

- **`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).
- **`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`](/cli) — 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`](/cli) appends to it; [`nimbus-docs init`](/cli) 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.

- 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://docs.klounge.kr/project-structure/index.mdx