---
title: "Philosophy"
---

> 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.

# Philosophy

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

Some of the opinions behind Nimbus, what we believe documentation should look like in a world where humans and agents are both creators and consumers.

## You own all your code

Layouts, components, content, styles — every visible piece of your site lives in your repo. The scaffolder writes them once and steps back. From there, the project is yours: edit any file, restructure any directory, change any default. No upstream API to wait on, no opinionated theme to fork around.

Coding agents work the same way you do, when nothing important hides behind an import boundary, an agent is able to reason about the repo a lot better.

- my-docs/
  - src/
    - components/
    - content/docs/
    - layouts/
    - pages/
    - styles/
      - globals.css
    - components.ts
  - astro.config.mjs
  - package.json

## Human and agent first

Documentation is no longer read only by people, and as a result every Nimbus site ships several surfaces alongside the HTML:

- A Markdown alternate for every page at `/<slug>/index.md`
- A site-level index at `/llms.txt`, naming every page
- A larger sibling at `/llms-full.txt`, concatenating the full corpus into one file for offline ingestion
- JSON-LD in every page's head, giving search and agent tools enough structured data to recognise what they're looking at

```text
# Nimbus

A way to build documentation sites on top of Astro.

## Pages
- [Getting started](https://nimbus-docs.com/getting-started/index.md)
- [Installation](https://nimbus-docs.com/installation/index.md)
- [CLI](https://nimbus-docs.com/cli/index.md)
```

These surfaces are defaults, not add-ons. The cost of being a dead end on the agent web is real, and it grows.

## Agentic authoring

Adding Nimbus default components or features is done with `nimbus-docs add`. It works differently depending on what you're adding. Components and utilities copy as files — `registry:ui` and `registry:lib` slugs resolve their dependencies and land in your repo. Features hand off as prompts — a `registry:feature` slug is a markdown recipe the coding agent in your environment reads, adapts to your project, and applies.

```sh
npx add 404-page
pnpm dlx add 404-page
yarn dlx add 404-page
bunx add 404-page
```

The split between the two modes is the one question that matters: which kind of change actually wants a coding agent in the loop, and which is better as a file copy.

## Authoring quality is first-class

A docs site whose content drifts in quality undermines its own product. Nimbus treats authoring quality the way a code linter treats source — a layered set of validators, each catching a different class of mistake.

Pre-build validators run automatically and gate the build only when the issue would actually break the site:

- **Config validation** — `defineConfig` is checked for shape and required fields; errors echo the offending value back to you
- **Frontmatter schema validation** — Zod-typed schemas catch missing or malformed fields per collection, with editor-friendly error messages
- **MDX component validation** — a pre-build content pass catches lowercase usages, unregistered components, and missing imports
- **Registry validation** — `src/components.ts` is parsed and checked against actual MDX usage at build time

The lint engine adds an on-demand authoring-quality layer. Rules have stable identifiers like `nimbus/single-h1` and `nimbus/link-text-meaningful`, configured in `astro.config.ts` alongside the rest of your Nimbus integration. Run `nimbus-docs lint` for human output, `--format json` for diagnostics an agent can read, `--fix` to apply auto-fixes. The build is never gated by lint findings — drafts still render, warnings stay loud but unblocking.

```ts title="astro.config.ts" {6-9}
import { defineConfig } from "astro/config";

export default defineConfig({
  integrations: [
nimbus(nimbusConfig, {
  rules: {
    "nimbus/single-h1": "error",
    "nimbus/link-text-meaningful": "warn",
  },
}),
  ],
});
```

Component-prop validation against TypeScript signatures lands post-v1.

## The tree is the truth

There is no second config to maintain alongside your content. The directory structure under `src/content/` is the URL structure. The directory structure is also the sidebar. Move a file and its entry moves with it; delete a file and the entry disappears. Frontmatter handles the fine-grain knobs — order, badges, draft state — but the shape of the tree comes from the filesystem itself.

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

The result is a single source of truth for what pages exist. The site can't drift from its own contents, because its contents are the site.

## Versions are just collections

Most docs tools bolt versioning on as a special case — parallel filesystems, URL rewrites, custom routing. Nimbus does it with a primitive it already has: multi-collection content.

Each version is its own content collection, with the same schema. A `docs-v2/` collection is a v2 site; a `docs-v3/` collection is v3. Routes and sidebars pick up each version independently. The version picker is a thin layer on top.

- src/content/
  - docs/
  - docs-v2/
  - docs-v3/

The same primitive handles internationalisation (a `docs-fr/` collection is a French site) and per-product splits (a `docs-api/` collection sits next to `docs-cli/`). When you need versions, you already have most of what you need; you didn't pay for it earlier.

Source: https://nimbus-docs.com/undefined