Configuration

Nimbus is configured in astro.config.ts. defineConfig (re-exported as defineNimbusConfig) types the site config; the nimbus() integration takes that config plus build-time options.

import { defineConfig } from "astro/config";
import nimbus, {
  defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";

const config = defineNimbusConfig({
  site: "https://docs.example.com",
  title: "Acme",
  description: "Build with Acme.",
  github: "https://github.com/acme/docs",
  editPattern: "https://github.com/acme/docs/edit/main/{path}",
  sidebar: { items: [/* … */] },
});

export default defineConfig({
  integrations: [nimbus(config, {/* options */})],
});

Site config

Rendering policy

rendering controls canonical content collection routes: the catch-all routes Nimbus uses for docs, API references, and other registered collections. It does not change custom files under src/pages/.

Omitting rendering is equivalent to rendering: { default: "build" }.

Enable request rendering

Request rendering requires three things: output: "server" in the Astro config, an adapter supported by Nimbus, and at least one collection set to "request" in the Nimbus config. Provider-specific setup is listed below.

Set the default when most or all canonical collection routes should render on request:

const nimbusConfig = defineNimbusConfig({
  // ...
  rendering: {
    default: "request",
  },
});

Run the production build after changing output mode or rendering policy. It is the authoritative check that the selected adapter supports Nimbus request rendering.

Mix build and request rendering

rendering.default applies to every registered collection with a canonical catch-all route. rendering.collections overrides that mode by Astro collection name, not by URL or version.

Render most collections on request but keep an archive prerendered:

rendering: {
  default: "request",
  collections: {
    archived: "build",
  },
},

Or keep the site static except for one collection:

rendering: {
  default: "build",
  collections: {
    api: "request",
  },
},

Every override must name a registered collection with its own canonical catch-all route. Nimbus fails the build for unknown collection names rather than silently ignoring them.

Request-rendered routes are still added to the sitemap and Pagefind search index during the production build. Nimbus uses the content source to create those build-time discovery files; no extra sitemap or search configuration is required.

Cloudflare

Cloudflare is currently the supported provider for request-rendered Nimbus collection routes. Choose Server and Cloudflare when creating a new site. For an existing site, run the adapter installer from the project root:

npx @cloudflare/nimbus-docs add adapter-cloudflare

yarn dlx @cloudflare/nimbus-docs add adapter-cloudflare

pnpm dlx @cloudflare/nimbus-docs add adapter-cloudflare

bunx @cloudflare/nimbus-docs add adapter-cloudflare

The installer wires @astrojs/cloudflare and sets Astro to server output. It creates wrangler.jsonc when none exists or replaces an unchanged Nimbus static configuration. Customized Wrangler files and alternate JSON or TOML configurations are preserved with manual guidance.

When the active Nimbus config has no rendering policy, the installer adds rendering: { default: "request" }. Existing policies are preserved. If an imported or ambiguous Nimbus config cannot be edited safely, the installer completes the adapter setup and prints instructions for generating a coding-agent recipe. Generate that recipe with:

npx @cloudflare/nimbus-docs add adapter-cloudflare --print

yarn dlx @cloudflare/nimbus-docs add adapter-cloudflare --print

pnpm dlx @cloudflare/nimbus-docs add adapter-cloudflare --print

bunx @cloudflare/nimbus-docs add adapter-cloudflare --print

Pass the printed recipe to your coding agent to finish the project-specific configuration.

The resulting Astro configuration includes the rendering policy, server output, and adapter:

import cloudflare from "@astrojs/cloudflare";
import { defineConfig } from "astro/config";
import nimbus, {
  defineConfig as defineNimbusConfig,
} from "@cloudflare/nimbus-docs";

const nimbusConfig = defineNimbusConfig({
  site: "https://docs.example.com",
  title: "Acme",
  rendering: {
    default: "request",
  },
});

export default defineConfig({
  output: "server",
  adapter: cloudflare({ prerenderEnvironment: "node" }),
  integrations: [nimbus(nimbusConfig)],
});

Cloudflare deployments also require a server-compatible wrangler.jsonc. Run pnpm build after setup to verify the adapter and Wrangler configuration together.

See Server adapters for installer behavior and safety checks.

Integration options

The second argument to nimbus() controls build behavior:

nimbus(config, {
  validateMdx: true,
  rules: { "nimbus/single-h1": "error", "nimbus/bare-url": "warn" },
});

Customize generated Markdown

Use markdown.componentMap to define how project-specific MDX components appear in generated Markdown. Use markdown.partialResolver when <Render> attributes map to a custom partial ID:

nimbus(config, {
  markdown: {
    componentMap: {
      ProductName: {
        revision: "product-name-v1",
        render: ({ children }) => children,
      },
    },
    partialResolver: {
      revision: "product-partials-v1",
      resolve: ({ file, product }) =>
        product ? `${product}/${file}` : file,
    },
  },
});

<ProductName>Acme</ProductName> becomes Acme in clean Markdown. Nimbus normalizes static authored href values before a transform runs, so validate and render those values directly. The transform also receives the active base for destinations it constructs itself.

Each transform requires a non-empty revision. Increment it whenever its output changes so Nimbus invalidates the generated Markdown cache.

Request-rendered HTML consumes prepared entries and headings. Generating alternate Markdown/MDX versions, llms.txt indexes, llms-full.txt, reusable-snippet expansion, and syntax highlighting remains build-time work. Their endpoints can prerender or serve those payloads on request. Run a production build after changing these options; development mode does not validate the final Worker bundle.