配置

Nimbus 在 astro.config.ts 中配置。@cloudflare/nimbus-docs 导出的 defineConfig 用于定义站点配置，为了不与 Astro 自己的 defineConfig 冲突，通常重命名为 defineNimbusConfig；nimbus() 集成接收这份配置，以及构建期选项。

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 */})],
});

站点配置

内容来源

sources 按名称声明 Git 仓库；docsCollection({ source, base }) 与 api[].spec: { source, path } 会读取它们。

nimbus-docs check 会把分支或标签形式的 ref 报告为 nimbus/source-floating-ref，把没有任何内容读取的来源报告为 nimbus/source-unreferenced，两者都是警告。NIMBUS_SOURCES_RESOLVE_TIMEOUT 与 NIMBUS_SOURCES_FETCH_TIMEOUT 以秒为单位设置解析与获取的超时（默认分别为 30 与 600）。

渲染策略

rendering 控制 Nimbus 管理的路由：文档、API 参考与其他已注册集合的兜底路由，以及为它们提供内容的 Markdown 与 llms.txt 路由。src/pages/ 下的其他文件保留各自的渲染设置。

"build" 就是 Astro 所说的预渲染，"request" 则是按需渲染。其他所有路由，例如 404 页面、Open Graph 图片或 robots.txt，都保留自己的 prerender 导出。

不设置 rendering 时，Nimbus 会提前构建它管理的每个路由，包括每个页面集合。一旦设置了 rendering，default 覆盖文档、版本与 API 集合，而其他每个页面集合都需要在 rendering.collections 中单独配置（见下文）。

要搭建服务端并选择模式，参见选择构建或按请求渲染。

智能体

agents 开启站点为智能体运行的服务，并控制它为智能体发布的发现文件：

agents: { mcp: true },

关于它提供的内容以及客户端如何连接，参见远程 MCP 服务器。

链接与结尾斜杠

Nimbus 会读取 Astro 的 trailingSlash 与 build.format，并让它生成的每个 URL（从侧边栏链接到 sitemap）都采用 Astro 提供的形态。

使用默认值时，页面 URL 以斜杠结尾，例如 /guides/。设置 trailingSlash: "never" 或 build.format: "file" 时则不以斜杠结尾。

你写的链接保持你写下的路径；Nimbus 只添加 Astro 的 base，因此不要在链接中写 base。请按站点实际提供的形态书写，例如默认值下写成 [Guides](/guides/)。

使用 trailingSlash: "always" 或 "never" 时，另一种形态会在 astro dev 中返回 404，在生产环境中通常是重定向或 404。nimbus/internal-link 不检查结尾斜杠。

在 Cloudflare 上，使用 trailingSlash: "always" 与 build.format: "file" 的静态站点会写出 guides.html，却链接到 /guides/，而 Cloudflare 默认会把 /guides/ 重定向到 /guides。构建与 nimbus-docs check 会对此发出警告；在 wrangler.jsonc 中设置 "assets": { "html_handling": "force-trailing-slash" } 即可直接提供 /guides/。

集成选项

nimbus() 的第二个参数控制构建行为：

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

定制生成的 Markdown

使用 markdown.componentMap 定义项目特定 MDX 组件在生成的 Markdown 中如何出现。当 <Render> 属性需要映射到自定义 partial ID 时，使用 markdown.partialResolver：

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> 在干净 Markdown 中会变成 Acme。Nimbus 会在转换运行前规范化手写的静态 href 值，请直接校验并渲染这些值。转换还会接收当前生效的 base，供它自行构造目标地址。

每个转换都需要非空的 revision。只要输出发生变化就递增它，这样 Nimbus 才会让生成的 Markdown 缓存失效。

按请求渲染的 HTML 会消费预处理好的条目与标题。生成 Markdown/MDX 备用版本、llms.txt 索引、llms-full.txt、可复用片段展开以及语法高亮仍属于构建期工作。它们的端点可以预渲染，也可以按请求提供这些载荷。修改这些选项后请运行生产构建；开发模式不会校验最终的 Worker 包。