内容路由

Lotus 路由由两个输入决定：

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

路由决策集中在这里。Locale 目录和 UI translation 行为见 国际化。

Collection Setup

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

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。

• Directory src

  • Directory content

    • Directory docs

      • index.mdx/
      • installation.mdx/installation/
      • Directory components

        • icon.mdx/components/icon/

本地化文档中，locales.*.directory 是相对于 src/content/docs 的目录。Lotus 会在匹配 sidebar string items 和 autogenerated directories 前移除 locale 目录。 见 Directory Mapping。

Custom Loader Base

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

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 时：

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

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

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

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

带前缀的搜索索引是 /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 创建。

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

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

---
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。

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

• Directory src

  • Directory content

    • Directory docs

      • index.mdxdocs homepage at /
      • installation.mdx/installation/

Slug Overrides

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

---
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 })：

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 字段仍然可用。