# 内容路由

配置 docsLoader、docsSchema、docsBase、slugs 和生成路由。

import { FileTree } from '@prosefly/astro-components';

Lotus 路由由两个输入决定：

- `docsLoader` 生成的 content collection entry IDs
- `docsBase` 配置的公开路由前缀

路由决策集中在这里。Locale 目录和 UI translation 行为见
[国际化](/docs/zh-cn/configuration/i18n/)。

## Collection Setup

默认 loader 会从 `src/content/docs` 读取 MDX 文件：

```ts
import { defineCollection } from 'astro:content';
import { docsLoader, docsSchema } from '@prosefly/astro-theme-lotus/content';

const docs = defineCollection({
  loader: docsLoader(),
  schema: docsSchema(),
});

export const collections = { docs };
```

未启用 i18n 时，`src/content/docs/installation.mdx` 的 entry ID 是 `installation`，
`src/content/docs/components/icon.mdx` 的 entry ID 是 `components/icon`。

<FileTree>

- src
  - content
    - docs
      - index.mdx `/`
      - installation.mdx `/installation/`
      - components
        - icon.mdx `/components/icon/`

</FileTree>

本地化文档中，`locales.*.directory` 是相对于 `src/content/docs` 的目录。Lotus
会在匹配 sidebar string items 和 autogenerated directories 前移除 locale 目录。
见 [Directory Mapping](/docs/zh-cn/configuration/i18n/#directory-mapping)。

## Custom Loader Base

`docsLoader()` 默认使用 `src/content/docs`，但当你确实想使用不同 collection root 时，
也可以传入 `base`。

```ts
const docs = defineCollection({
  loader: docsLoader({
    base: './src/content',
  }),
  schema: docsSchema(),
});
```

在这个设置下，`src/content/docs/en/installation.mdx` 的 entry ID 是
`docs/en/installation`，而 `src/content/index.mdx` 的 entry ID 是 `index`。
大多数站点应保留默认 loader，并使用 Astro 正常的 `src/pages` routing 创建非 docs 页面。

## Docs Base

`docsBase` 控制 Lotus 注入页面路由、Markdown 路由和搜索路由的位置。默认是 `/`，
与 Starlight 的路由模型一致：`src/content/docs` 是 content collection root，
不是公开 URL prefix。

默认 `docsBase: '/'` 且使用默认 loader 时：

| Entry ID | Page URL | Markdown URL |
| --- | --- | --- |
| `index` | `/` | `/index.md` |
| `installation` | `/installation/` | `/installation.md` |
| `components/icon` | `/components/icon/` | `/components/icon.md` |

搜索索引也使用同一个 base。默认 route base 下，它位于 `/search.json`。

当项目还有 marketing site、app routes 或其他非文档页面时，设置 `docsBase`。

```ts
export default defineLotusConfig({
  docsBase: '/docs',
});
```

设置 `docsBase: '/docs'` 且使用默认 loader 时：

| Entry ID | Page URL | Markdown URL |
| --- | --- | --- |
| `index` | `/docs/` | `/docs/index.md` |
| `installation` | `/docs/installation/` | `/docs/installation.md` |
| `components/icon` | `/docs/components/icon/` | `/docs/components/icon.md` |

带前缀的搜索索引是 `/docs/search.json`。

## Site Homepage

docs collection 中的 `index` entry 总是渲染到当前 `docsBase`。默认 `docsBase: '/'`
时，`src/content/docs/index.mdx` 是站点首页。设置 `docsBase: '/docs'` 时，同一 entry
渲染到 `/docs/`。

自定义 marketing homepage 应放在 docs collection 外，并使用 Astro 正常的
file-based routing 创建。

```txt
src/
  pages/
    index.astro          -> /
  content/
    docs/
      index.mdx          -> /docs/
      installation.mdx   -> /docs/installation/
```

你也可以在自定义页面上复用 Lotus page primitives：

```astro
---
import {
  BaseLayout,
  PageSection,
  SiteFooter,
  SiteHeader,
} from '@prosefly/astro-theme-lotus/layouts';
---

<BaseLayout title="Home">
  <SiteHeader currentPath="/" />
  <main>
    <PageSection>
      <h1>Product documentation</h1>
    </PageSection>
  </main>
  <SiteFooter />
</BaseLayout>
```

对于纯文档站点，保留默认 `docsBase: '/'`，并将文档首页放在
`src/content/docs/index.mdx`。

```txt
src/content/
  docs/
    index.mdx            -> /
    installation.mdx     -> /installation/
```

<FileTree>

- src
  - content
    - docs
      - index.mdx docs homepage at `/`
      - installation.mdx `/installation/`

</FileTree>

## Slug Overrides

当页面的公开路径需要不同于 entry ID 时，使用 frontmatter `slug`：

```md
---
title: CLI Reference
slug: reference/cli
---
```

设置 `docsBase: '/docs'` 时，这个页面会渲染到 `/docs/reference/cli/` 和
`/docs/reference/cli.md`。

Slug overrides 会影响公开 URL。Sidebar 归属仍然取决于 entry IDs，因此
`sidebars` 应引用 content entry，而不是 slug override。

## Schema Extensions

项目需要额外 frontmatter 字段时，使用 `docsSchema({ extend })`：

```ts
import { z } from 'astro/zod';

const docs = defineCollection({
  loader: docsLoader(),
  schema: docsSchema({
    extend: z.object({
      product: z.string().optional(),
    }),
  }),
});
```

Extension 会合并进 Lotus docs schema。`title`、`sidebar`、`tableOfContents`、
`template`、`pagefind` 和 `draft` 等已有 Lotus 字段仍然可用。