可复用片段

Partial 是可复用的内容片段。编写一次片段，在多个页面中引用，只需在一个地方编辑。

编写 partial

Partial 存放在 src/content/partials/ 中，格式为 .md 或 .mdx，在 src/content.config.ts 中注册为集合：

import { defineCollection } from "astro:content";
import { partialsCollection } from "@cloudflare/nimbus-docs/content";

export const collections = {
  partials: defineCollection(partialsCollection()),
};

Nimbus requires Node 22.12 or later and any package manager.

引用 partial

<Render> 在默认注册表中。通过 ID 引用 partial——即 src/content/partials/ 下的路径（不含扩展名）：

<Render file="install-note" />
<Render file="workers/setup" />

如果在渲染规范 HTML 时 ID 无法解析，Render.astro 会抛出“你是否指的是……“的建议和可用 partial 列表。生成的 Markdown 构建会按 ID 报告缺失的准备好的 partial。

Nimbus 在构建时会展开生成的 Markdown 中的 partial 并合并它们的标题。循环引用或缺失的 partial、非静态或缺失的 file、无效的 params、未声明的参数以及被排除或未知的可见性决策都会在部署前导致构建失败。

自定义 partial ID

如果 <Render> 上的属性决定了 partial 的位置，在 Nimbus 集成上配置一个解析器：

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

解析器控制 Markdown 替代版本、llms-full.txt 和准备好的标题中的 partial ID。当其输出规则变更时更改 revision，Nimbus 会重建受影响的 Markdown。

Render.astro 是用户拥有的，单独解析规范 HTML partial。如果你自定义了 partial ID，请将解析器函数移到共享的项目文件中，并在 astro.config.ts 和 Render.astro 中的 getVisibleEntry("partials", id) 之前调用它。这确保 HTML、标题和生成的 Markdown 保持一致。

路由级 partialHeadings 选项不受支持。在集成上配置准备好的标题解析，这样请求渲染的页面不会打包生成的 Markdown 和标题逻辑。用户拥有的 Render.astro 仍然会加载并渲染选定的 partial 作为 HTML 页面的一部分。

参数

在 partial 的 frontmatter 中声明接受的参数——可选参数以 ? 后缀标识。它们以 props 的形式传入：

---
params: [runtime, version?]
---
This page targets the {props.runtime} runtime.

<Render file="runtime-note" params={{ runtime: "node" }} />

缺失必填参数和意外参数名称都会导致构建失败并给出清晰的错误信息——partial 是类型化契约，而非字符串插值。