配置 | Nimbus 中文文档

Nimbus 在 astro.config.ts 中进行配置。defineConfig（重新导出为 defineNimbusConfig）为站点配置提供类型支持；nimbus() 集成接收该配置以及构建时选项。

astro.config.tsts

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`	string	必填。规范站点 URL。桥接到 Astro 的 `site`。
`title`	string	必填。站点标题及元数据回退值。
`description`	string	默认 meta 描述。
`locale`	string	文档语言（如 `"en"`）。
`homeLabel`	string	「首页」面包屑的标签。
`github`	string \| null	头部链接的仓库 URL；`null` 则隐藏。
`editPattern`	string \| null	编辑链接模式；`{path}` 为页面路径。
`socialImage` / `socialImageAlt`	string	OG 回退图片和替代文本。参见元数据和 SEO。
`head`	array	站点级 `<head>` 元素。
`sidebar`	object	侧边栏配置——参见侧边栏。
`features`	object	`sidebar` / `tableOfContents` 开关。参见布局。
`search`	object \| `false`	搜索后端。参见搜索。
`versions`	object	版本清单——每个版本都是独立的内容集合。
`rendering`	object	规范内容集合路由的构建或请求渲染策略。

渲染策略

rendering 控制规范内容集合路由：Nimbus 用于文档、API 参考和其他注册集合的通配路由。它不会改变 src/pages/ 下的自定义文件。

模式	行为	部署要求
`"build"`	在 `astro build` 期间预渲染路由。这是默认值。	任何静态或服务端部署。
`"request"`	在访客请求时渲染路由。	Astro 服务端输出，配合 Nimbus 支持的适配器。

省略 rendering 等同于 rendering: { default: "build" }。

启用请求渲染

请求渲染需要三个条件：Astro 配置中的 output: "server"、Nimbus 支持的适配器，以及 Nimbus 配置中至少一个集合设置为 "request"。特定提供商的配置如下所列。

当大部分或全部规范集合路由需要按请求渲染时，设置默认值：

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

更改输出模式或渲染策略后，请运行生产构建。这是验证所选适配器是否支持 Nimbus 请求渲染的权威检查。

混合构建和请求渲染

rendering.default 应用于每个具有规范通配路由的已注册集合。rendering.collections 按 Astro 集合名称（而非 URL 或版本）覆盖该模式。

按请求渲染大部分集合，但保持归档集合预渲染：

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

或者保持站点静态，但为一个集合启用请求渲染：

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

每个覆盖必须指定一个具有自身规范通配路由的已注册集合。Nimbus 会对未知集合名称报错，而不是静默忽略。

请求渲染的路由在生产构建期间仍会添加到站点地图和 Pagefind 搜索索引。Nimbus 使用内容源创建这些构建时发现文件；无需额外的站点地图或搜索配置。

Cloudflare

Cloudflare 目前是 Nimbus 请求渲染集合路由的支持提供商。创建新站点时选择 Server 和 Cloudflare。对于现有站点，从项目根目录运行适配器安装程序：

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

安装程序会连接 @astrojs/cloudflare 并将 Astro 设置为服务端输出。当 wrangler.jsonc 不存在时会创建它，或替换未更改的 Nimbus 静态配置。自定义的 Wrangler 文件和替代的 JSON 或 TOML 配置会被保留，并提供手动操作指引。

当活跃的 Nimbus 配置没有渲染策略时，安装程序会添加 rendering: { default: "request" }。现有策略会被保留。如果导入的或模糊的 Nimbus 配置无法安全编辑，安装程序会完成适配器设置并打印生成编码智能体配方的说明。使用以下命令生成该配方：

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

将打印的配方传递给你的编码智能体以完成项目特定的配置。

生成的 Astro 配置包含渲染策略、服务端输出和适配器：

astro.config.tsts

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 部署还需要一个兼容服务端的 wrangler.jsonc。设置完成后运行 pnpm build 以验证适配器和 Wrangler 配置。

参见服务端适配器了解安装程序的行为和安全检查。

集成选项

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

选项	默认值	说明
`validateMdx`	`true`	PascalCase 标签验证。`false` 跳过；对象可覆盖路径。参见 Markdown 和 MDX。
`admonitions`	`true`	原生 Sätteri MDX 指令 → `<Aside>`；对象可添加 `typeAliases`、`contentDirs` 和 `skip`。使用不兼容的自定义处理器时设为 `false`。
`markdown`	Sätteri 处理器	配置编写的 Markdown 处理和生成的 Markdown 自定义。
`sitemap`	设置 `site` 时启用	`false` 可禁用。
`mdx`	—	转发给 Astro MDX 集成的选项。其行为仍由处理器控制。
`icons`	`true`	内置图标系统。`true` 自动检测 `@iconify-json/` 包（Phosphor、Material Icons 等）和本地 `src/icons/.svg`。`false` 禁用。对象用于显式配置（`iconDir`、`include`、`svgoOptions`）。参见图标。
`rules`	`off`（需主动启用）	编写规则严重级别——每条规则默认关闭，需手动启用。参见代码检查。
`collections`	—	按集合覆盖 lint 规则。

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

自定义生成的 Markdown

使用 markdown.componentMap 定义项目特定的 MDX 组件在生成的 Markdown 中的呈现方式。当 <Render> 属性映射到自定义片段 ID 时，使用 markdown.partialResolver：

astro.config.tsts

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 包。