Nimbus config

Nimbus is configured in astro.config.ts. defineConfig from @cloudflare/nimbus-docs, imported as defineNimbusConfig so it doesn’t clash with Astro’s own defineConfig, 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

Content sources

sources declares git repositories by name; docsCollection({ source, base }) and api[].spec: { source, path } read them.

nimbus-docs check reports nimbus/source-floating-ref for a branch or tag ref and nimbus/source-unreferenced for a source nothing reads, both as warnings. NIMBUS_SOURCES_RESOLVE_TIMEOUT and NIMBUS_SOURCES_FETCH_TIMEOUT set the resolve and fetch timeouts in seconds (defaults 30 and 600).

Rendering policy

rendering controls the routes Nimbus manages: the catch-all routes for docs, API references, and other registered collections, and the Markdown and llms.txt routes that serve them. Other files under src/pages/ keep their own rendering.

"build" is what Astro calls prerendered, and "request" what it calls on-demand rendered. Every other route, such as a 404 page, Open Graph images or robots.txt, keeps its own prerender export.

Without rendering, Nimbus builds every route it manages ahead of time, every page collection’s included. Once rendering is set, default covers docs, version and API collections, and each other page collection needs its own entry in rendering.collections (see below).

To set up a server and choose modes, see Choose build or request rendering.

Agents

agents turns on services the site runs for agents, and controls the discovery files it publishes for them:

agents: { mcp: true },

See Remote MCP server for what it serves and how clients connect.

Links and trailing slashes

Nimbus reads Astro’s trailingSlash and build.format, and gives every URL it generates the shape Astro serves, from sidebar links to the sitemap.

With the defaults, page URLs end in a slash, such as /guides/. With trailingSlash: "never", or build.format: "file", they don’t.

Links you write keep the path you wrote; Nimbus only adds Astro’s base, so leave the base out. Write them in the shape your site serves, such as [Guides](/guides/) with the defaults.

With trailingSlash: "always" or "never", the other shape gets a 404 in astro dev, and often a redirect or 404 in production. nimbus/internal-link doesn’t check trailing slashes.

On Cloudflare, a static site with trailingSlash: "always" and build.format: "file" writes guides.html but links /guides/, and Cloudflare redirects /guides/ to /guides by default. The build and nimbus-docs check warn about it; set "assets": { "html_handling": "force-trailing-slash" } in wrangler.jsonc to serve /guides/ directly.

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.