---
title: "页面与路由"
description: "src/content/docs 下的文件系统如何生成你的路由和侧边栏。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 页面与路由

import { FileTree } from "@/components/ui/file-tree";

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

<h2 id="file-to-url">文件到 URL</h2>

| 文件 | URL |
|---|---|
| `src/content/docs/get-started.mdx` | `/get-started` |
| `src/content/docs/guides/styling.mdx` | `/guides/styling` |
| `src/content/docs/guides/index.mdx` | `/guides` |

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

- src/content/docs/
  - introduction.mdx
  - guides/
    - index.mdx
    - styling.mdx

<h2 id="custom-astro-routes">自定义 Astro 路由</h2>

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

```astro title="src/pages/status.astro"
---
export const prerender = false;
---

<h1>Service status</h1>
```

```ts title="src/pages/api/ping.ts"
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 的原生渲染行为。

<h2 id="page-modes">页面模式</h2>

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

```yaml
---
title: Welcome
mode: custom
---
```

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

<h2 id="drafts">草稿</h2>

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

```yaml
---
title: Experimental feature
draft: true
---
```

<h2 id="redirecting-a-sidebar-entry">重定向侧边栏条目</h2>

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

<h2 id="other-collections">其他集合</h2>

`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()` 包装它：

```ts title="src/content.config.ts"
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 提供了其渲染器。如果集合未准备就绪，构建时会指出并提示你包装其加载器。

<h2 id="custom-route-helpers">自定义路由辅助函数</h2>

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

```ts
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` 路由冲突、编码的路径分隔符以及编码的 `.` 或 `..` 段。构建错误会指出冲突的条目。

<h2 id="page-urls">页面 URL</h2>

`getDocsPage()` 和 `getCollectionPage()` 在返回 `entry`、`Content` 和 `headings` 的同时返回每个页面的 URL，这样页面路由无需手动构建它们。`getIndexedEntries()` 在每个 `IndexedEntry` 上返回相同的值。

| 字段 | 示例 | 描述 |
| --- | --- | --- |
| `markdownUrl` | `/blog/welcome/index.md` | 页面的简洁 Markdown 版本。站点根目录为 `/index.md`。 |
| `sourceUrl` | `/blog/welcome/index.mdx` | 页面的原始源文件。没有原始正文的条目为 `undefined`。 |
| `ogImageUrl` | `/og/blog/welcome.png` | 页面的生成 OG 卡片。站点根目录为 `/og/index.png`，挂载在 `/blog` 的集合根目录为 `/og/blog.png`。 |

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：

```astro title="src/pages/[...slug].astro (excerpt)"
---
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 卡片](/ai/override-markdown#customize-og-cards)。

Source: https://nimbus-docs.cn/writing/pages-and-routing/index.mdx