内容路由

Dahlia 路由由两个输入决定：

• 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-dahlia/content';

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

export const collections = { docs };

未启用 i18n 时，src/content/docs/installation.mdx 的 entry ID 是 installation， src/content/docs/references/configuration.mdx 的 entry ID 是 references/configuration。

• Directory src

  • Directory content

    • Directory docs

      • index.mdx/
      • installation.mdx/installation/
      • Directory references

        • configuration.mdx/references/configuration/

本地化文档中，locales.*.directory 是相对于 src/content/docs 的目录。Dahlia 会在匹配 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 控制 Dahlia 注入页面路由、Markdown 路由和搜索路由的位置。默认是 /， 与 Starlight 的路由模型一致：src/content/docs 是 content collection root， 不是公开 URL prefix。

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

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

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

{
  "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 创建。

• Directory src/

  • Directory pages/

    • index.astro-> /
  • Directory content/

    • Directory docs/

      • index.mdx-> /docs/
      • installation.mdx-> /docs/installation/

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

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

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

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

• 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，因此 docsNav 应引用 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 会合并进 Dahlia docs schema。title、sidebar、tableOfContents、 template、pagefind 和 draft 等已有 Dahlia 字段仍然可用。