包 API

起始模板的路由和布局会调用这些辅助函数，你定制它们时也会调用。本页涵盖定制所需的那些；包的每个入口导出更多内容，其 TypeScript 类型记录了每个导出。包遵循 semver，nimbus-docs migrate 处理破坏性变更（升级）。

页面路由

来自 @cloudflare/nimbus-docs。起始模板的 src/pages/[...slug].astro 使用它们。

导航

页面详情

URL

路由匹配使用逻辑的、不含 base 的路径；发送到浏览器的链接使用带 base 的路径：

import {
  entryRouteKey,
  stripBase,
  withBase,
} from "@cloudflare/nimbus-docs/runtime";

const route = entryRouteKey(entry.id);
const requestedRoute = stripBase(Astro.url.pathname, import.meta.env.BASE_URL);
const href = withBase(`/${route}`, import.meta.env.BASE_URL);

Nimbus 在构建期间拒绝歧义或不安全的生成路由。常见原因包括同时存在 foo 和 foo/index、与保留的 llms.txt 路由冲突、编码的路径分隔符，以及编码的 . 或 .. 段。构建错误会指出冲突的条目。

页面 URL

getDocsPage() 和 getCollectionPage() 会返回每个页面的 URL，与 entry、Content 和 headings 并列，因此页面路由无需手动构建它们。getIndexedEntries() 在每个 IndexedEntry 上返回相同的值。

URL 跟随条目 ID。Astro 的 glob 加载器会对文件路径做 slug 化，从而去掉点号：src/content/docs/1.1.1.1/encryption.mdx 得到的 ID 是 1111/encryption。在 Astro 不做 slug 化的地方，点号会保留：版本前缀（/v1.2/guide/）、API 操作（payment.succeeded），或 slug frontmatter 字段（Astro 将其用作 ID）。docsCollection() 接受 slug，无需更改 schema。

每个 URL 都是站点相对的，不含 Astro 的部署 base；起始模板的布局在输出时会添加 base。起始模板的页面路由直接使用这些 URL：

---
const page = await getDocsPage(Astro);
if (page instanceof Response) return page;
const { entry, Content, headings, markdownUrl, ogImageUrl } = page;
const socialImage = entry.data.socialImage ?? ogImageUrl;
---

getOgImagePages() 为每个索引页面返回一个条目，以卡片在 /og/ 下的路径为键，因此卡片会写在该页面的 ogImageUrl 处，值是该页面的 IndexedEntry。getPageSection(page) 返回该页面最近父级的标签，卡片会将其打印在标题上方。起始模板的 src/pages/og/[...slug].ts 会透传它；参见自定义 OG 卡片。

API 参考页面

来自 @cloudflare/nimbus-docs/runtime。添加 OpenAPI 参考展示了它们在 API 路由中的用法。

用整份参考构建页面

要以整份参考构建自己的页面，用 @cloudflare/nimbus-docs/runtime 的 getApiRoot 读取某个版本的根页面；省略 version 表示默认版本。其 index 恰好包含每个操作和 webhook 各一次，每个都带 method、path 和链接。apiIndexRows(index) 将其展平，chunkApiIndex(index, { size }) 按首页的方式拆分。

---
import { apiIndexRows, getApiRoot, withBase } from "@cloudflare/nimbus-docs/runtime";

const root = await getApiRoot(Astro, { collection: "api" });
const rows = root ? apiIndexRows(root.index) : [];
---

<ul>
  {rows.map(([method, path, label, href]) => (
    <li><a href={withBase(href, import.meta.env.BASE_URL)}>{label}</a> <code>{method} {path}</code></li>
  ))}
</ul>

链接到另一版本中的同一页面

const href = await getVersionSwitchUrl({
  collection: "api",
  sourceVersion: "2026-10-09",
  id: coordinate,
  targetVersion: "2026-10-02",
});

从 @cloudflare/nimbus-docs/runtime 导入，并在渲染链接时应用一次 withBase。传入页面的确切源版本，包括在最新版本的页面上。链接会指向目标版本中的同一操作；若该操作在目标版本中不存在，则指向该版本的落地页。

自定义 API head 请使用 getApiVersionHead；起始模板的 ApiLayout 也使用它。

集合

来自 @cloudflare/nimbus-docs/content，位于 src/content.config.ts。

浏览器中的行为

来自 @cloudflare/nimbus-docs/client，在组件脚本中。

Markdown 插件

来自 @cloudflare/nimbus-docs/markdown，用于集成选项中的 markdown.hastPlugins。参见Markdown 与 MDX。

组件