cloudflare/nimbus: an Astro docs site scaffolded into your repo, with agent-readable output by default

The problem Nimbus targets: docs sites you cannot edit, and docs agents cannot read

Most documentation tools put a theme between you and the markup. You configure options, override a slot or two, and live with the rest. Nimbus takes the opposite position: the scaffolder writes layouts, components, styles, routes and content into your repository as real files on the first commit, and only the invisible plumbing stays in an npm package. The README states that everything you see and shape is yours.

The second problem is narrower. A rendered HTML page is a poor input for a coding agent. Nimbus ships agent-readable formats by default rather than as an add-on: a clean Markdown version of every discoverable page, a prepared MDX source version of every discoverable authored page, /llms.txt, /llms-full.txt, JSON-LD, a sitemap, robots.txt and per-page OG images. The intended audience is a team that already writes in Markdown or MDX, wants a static site it can host anywhere, and treats agent consumption as part of the deliverable rather than a later integration.

How the scaffolding and the registry split the work

There are two distinct delivery paths, and mixing them up is the main source of confusion. The scaffolder, @cloudflare/create-nimbus-docs, writes a whole site into a directory. The registry command, nimbus-docs add, pulls individual pieces into an existing project.

The registry itself has two behaviours. Components and utilities copy in as editable files, so a dialog or a 404 page becomes source you can change. Features instead hand off a recipe that your coding agent reads, adapts to your project and applies. The README shows that split directly: adding adapter-cloudflare has a plain form, and a second form piped into a coding agent. That second form is the honest part of the design. Some changes are project-specific enough that a generator cannot make them for you.

The stack underneath is Astro 7, Sätteri for Rust-based markdown processing, Tailwind v4, and optional React 19. Static output deploys anywhere; request-rendered server output currently targets Cloudflare, and the default scaffold ships a wrangler.jsonc. The repository is a pnpm workspace with apps/ and packages/ at the top level, and the monorepo package.json pins packageManager to pnpm@9.0.0.

Install and first run: from npx to a served page

The README's quickstart is four commands. The first scaffolds a project directory, the rest install and serve it.

npx @cloudflare/create-nimbus-docs@latest my-docs
cd my-docs
pnpm install
pnpm dev

Open the URL the dev server prints. Editing anything under src/ triggers a reload, which is the quickest way to confirm that the files are genuinely yours to change.

The scaffolder asks about output mode, deploy target or adapter, package manager, and whether to start from a starter or empty content. Skipping the prompts is a single flag:

npx @cloudflare/create-nimbus-docs@latest my-docs --yes

One detail matters if you skip the prompts. With --yes the package manager defaults to npm, so if you want pnpm you have to say so:

npx @cloudflare/create-nimbus-docs@latest my-docs --yes --package-manager pnpm

Inside the project, the everyday commands are pnpm dev for the hot-reloading server, pnpm build for a build using the selected output mode and adapter, pnpm preview to serve the built site, pnpm typecheck for astro check, and pnpm lint:docs to lint prose and MDX, with --fix to autofix. A static build emits dist/, which you can host anywhere.

Adding components and the Cloudflare adapter after the fact

An existing project can pull optional components, utilities and agent-handoff features from the registry. Each lands in the repository as source you own.

pnpm dlx @cloudflare/nimbus-docs add dialog
pnpm dlx @cloudflare/nimbus-docs add 404-page

Server output on Cloudflare is a two-step job. The first command wires the adapter. The second prints the project-specific rendering edit and pipes it to a coding agent, which is the documented path for the part a generator will not do for you.

pnpm exec nimbus-docs add adapter-cloudflare
pnpm exec nimbus-docs add adapter-cloudflare --print | claude

Deployment then reuses the wrangler.jsonc the default scaffold already contains:

pnpm build
pnpm run deploy

The README does not document a rollback path for a registry add, so treat each one as a change to review in version control rather than something to undo with a matching remove command.

The limitations the README admits, and the ones it does not

Nimbus is pre-1.0 and the README says so plainly: the public surface can still change between minor releases, there are rough edges, and you should pin versions and check each package's changelog before upgrading. The release history bears that out. Three releases landed across 2026-09-14 and 2026-09-15, two of them minor bumps to @cloudflare/nimbus-docs and one to @cloudflare/create-nimbus-docs. A project moving that fast is a poor fit if you need a stable API contract across minor versions.

The ownership model cuts both ways. Because the layouts, components and theme tokens are copied into your repository, upstream improvements to those files do not reach you automatically. You either merge them by hand or stay on the version you scaffolded. The invisible plumbing in the npm package does update, but the visible half is a fork from day one.

Request-rendered server output is narrower than the static path. Static builds emit dist/ and deploy anywhere; server output currently targets Cloudflare. If you want request rendering somewhere else, the README does not describe a supported route. Contribution is also gated: the project works from issues and discussions rather than drive-by pull requests, and a maintainer approves your issue or discussion before your pull requests stay open. That is a deliberate filter, but it means a fix you need may sit behind someone else's triage.

Where Nimbus differs from a batteries-included docs framework

Compare it with Docusaurus. Docusaurus is a React-based framework you install as a dependency and configure; the theme lives in node_modules and you change it through swizzling or plugin options. Nimbus inverts that. Astro and Tailwind generate the site, and the output is committed as your own source, so there is no swizzle step and no theme layer to work around. The cost is that upstream fixes to those generated files are not delivered to you.

A second difference is the agent-facing output. Docusaurus serves HTML and whatever you add yourself. Nimbus ships a Markdown version of every discoverable page, a prepared MDX source of every discoverable authored page, /llms.txt, /llms-full.txt, JSON-LD, a sitemap, robots.txt and per-page OG images by default. If agent readability is not something you care about, that output is weight you did not ask for.

A third is the registry model. Docusaurus leans on plugins; Nimbus copies components and utilities in as files and hands off features as recipes for a coding agent. The recipe approach is more flexible and less predictable, because the result depends on the agent applying it.

Maintenance, upgrades and what the MIT licence means here

The repository is not archived and the last push was on 2026-09-15, so the project is being worked on. That says nothing about whether the API will hold still, and the README explicitly warns that it will not.

The upgrade path has a real cost that follows from the ownership model. The npm package updates like any dependency, but the layouts, components and theme tokens in your src/ directory do not. Every minor release is therefore a decision: read the changelog, decide whether the generated files changed in a way you want, and merge by hand if they did. The README's advice to pin versions is the practical version of that.

Licensing is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved. The repository carries a LICENSE file at the top level, and the scaffolder copies source into your project, so the notice obligations travel with the code you keep. Nothing here is legal advice; read the LICENSE file and the notices in the generated files if the distinction matters to your organisation.

Editorial conclusion

Adopt Nimbus if you want the docs site to be ordinary files in your own repository and you care that coding agents can read the same pages a browser can, and you are willing to pin versions while it is still 0.x. Do not adopt it if you need a stable public API across minor releases, or if you want a hosted documentation platform that upgrades itself without touching your repo. Before committing, run the scaffolder once with --yes into a scratch directory and inspect what lands under src/, check that the Node version on your machine satisfies the >=22.12.0 engine field in the monorepo package.json, and read each package's changelog before your first upgrade.

Frequently asked questions

Official sources

1. cloudflare/nimbus on GitHub
2. Issues
3. License: MIT
4. README
5. Releases