A Nimbus site has two layers. Read this before changing a component or a layout, so you know what an upgrade will and won’t touch.
Your files and the framework’s
Everything the scaffolder writes into your repo is yours: components, layouts, routes, styles and content. Change any of it. Nothing overwrites your files: upgrading the package leaves them alone, and Nimbus offers upstream changes to them as diffs you choose to take. Project structure maps each file and where the framework’s part begins.
The @cloudflare/nimbus-docs package’s exports are a stable contract, versioned with semver: a breaking change comes with a migration, which nimbus-docs migrate applies or explains. Package API lists the helpers your files call.
The ladder
Customize at the lowest rung that does the job, since each rung up is more of your own code to maintain:
- Configuration. Options in
astro.config.ts, such as the sidebar, search and rendering. See Configuration. - Tokens. Colours, type and spacing in
src/styles/globals.css. See Theme and tokens. - Components from the registry. Install with
nimbus-docs add; they land as files you own. See Add components and features. - Editing a file. Change a component, layout or route directly.
- Your own components. Write new ones and use them in MDX. See Custom components.
Staying current
Upstream changes to files you own arrive as changes you review:
| Command | What it does |
|---|---|
nimbus-docs outdated |
Lists starter files, registry components and package API work that changed upstream. --to <templates-vX.Y.Z> compares against a specific release. |
nimbus-docs diff <file> |
Shows the upstream change to one starter file next to yours. --apply takes it when you haven’t edited the file. |
nimbus-docs add <slug> --overwrite |
Reinstalls a registry component, asking before it replaces one you’ve edited. |
nimbus-docs migrate |
Applies package API migrations and lists the upgrade reviews for your new version. |
nimbus-docs init |
Writes nimbus.json for a project that doesn’t have one, so the commands above know where it started. |
outdated and diff download the starter from GitHub. If GitHub rate-limits you, set GIGET_AUTH to a GitHub token; see Troubleshooting.
Upgrade Nimbus puts these in order for a release.