页面与路由

页面是 src/content/docs/ 下的 .md 或 .mdx 文件。它在磁盘上的路径就是它的 URL 和在侧边栏中的位置——不需要单独的路由或导航配置。

文件到 URL

Slug 会被转为小写，目录的 index 文件会折叠为目录 URL。目录的 index.mdx 成为该章节的着陆页。

自定义 Astro 路由

在 src/pages/ 下添加的文件使用 Astro 原生的路由和渲染语义。在服务端输出项目中，页面或端点默认按需渲染；使用 Astro 的 prerender 导出来显式声明：

---
export const prerender = false;
---

<h1>Service status</h1>

export const prerender = false;

export function GET() {
  return new Response("pong");
}

使用 export const prerender = true 在构建时将自定义路由输出为静态文件。无需 Nimbus 路由注册或白名单。

此边界不仅限于 prerender。动态段、端点方法、重定向和响应以及其他原生 Astro 路由行为仍由路由自身控制。Nimbus 仅在路由与已配置的规范内容路由、包注入的基础设施、活跃功能或已发布内容条目完全冲突时才会介入。

Nimbus 的 rendering 配置控制规范内容集合路由，不影响 src/pages/ 下的其他文件。为 llms.txt、Markdown 替代版本、Open Graph 图片和 robots.txt 生成的文件属于你的项目，可以像其他路由一样使用 Astro 的原生渲染行为。

页面模式

每个页面默认在 DocsLayout 内渲染——侧边栏、目录、面包屑、上/下翻页。使用 mode 可让页面退出所有装饰：

---
title: Welcome
mode: custom
---

mode: custom 用于着陆页和自定义布局。逐列切换（sidebar: false、tableOfContents: false）可关闭单独的部分而不完全自定义——参见布局。

草稿

draft: true 会将页面从生产构建和 llms.txt 索引中排除，但在 astro dev 下仍会渲染（视为 noindex）。用于进行中的工作。

---
title: Experimental feature
draft: true
---

重定向侧边栏条目

external_link 可重写侧边栏链接目标而不改变构建位置——适用于将条目指向其他章节或外部 URL。参见重定向。

其他集合

src/content/docs/ 是主集合，挂载在站点根目录。其他集合（如 blog、api、版本化的 docs-v2）挂载在各自的 URL 命名空间下。在 src/content.config.ts 中使用 nimbus-docs/content 的工厂函数注册它们。

Nimbus 的 docsCollection()、partialsCollection() 和 componentsCollection() 工厂函数会自动为链接、Markdown/MDX 替代版本、llms-full.txt 和部分标题准备内容。如果你注册的加载器直接存储 Markdown 正文，请用 withNimbusMarkdown() 包装它：

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

export const collections = {
  blog: defineCollection({
    loader: withNimbusMarkdown(
      glob({ base: "./src/content/blog", pattern: "**/*.{md,mdx}" }),
    ),
  }),
};

包装器保留加载器的方法和生命周期。当加载器存储的条目包含 Markdown body 时使用它。每个通用索引集合必须为 Markdown/MDX 替代版本和 llms-full.txt 提供准备好的 Markdown；不支持纯数据集合。apiCollection() 是内置的例外，因为 Nimbus 提供了其渲染器。如果集合未准备就绪，构建时会指出并提示你包装其加载器。

自定义路由辅助函数

路由匹配使用逻辑路径（不含基础路径）；发送到浏览器的链接使用包含基础路径的路径。Nimbus 从 @cloudflare/nimbus-docs/runtime 导出两侧的辅助函数：

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);

• entryRouteKey() 保留 Astro 条目 ID 的同时折叠末尾的 /index。
• stripBase() 在路由匹配前移除已配置的基础路径。
• withBase() 在生成浏览器 URL 时添加已配置的基础路径。

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

页面 URL

getDocsPage() 和 getCollectionPage() 在返回 entry、Content 和 headings 的同时返回每个页面的 URL，这样页面路由无需手动构建它们。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）。要允许 slug，使用 schemaFields: { slug: z.string().optional() } 添加它。

每个 URL 都是站点相对路径，不包含 Astro 的部署基础路径；模板的布局在输出时会添加基础路径。模板的页面路由直接使用这些 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() 为 astro-og-canvas 的 OGImageRoute 返回 pages 映射：每个索引页面一个条目，键值确保卡片写入该页面的 ogImageUrl，值为页面的 IndexedEntry。模板的 src/pages/og/[...slug].ts 直接传递它；参见自定义 OG 卡片。