---
description: 配置网站元数据、URL、输出目录、多语言、导航、样式和自定义 MDX 组件。
---

# 配置参考

Doctrine 不要求根配置文件。存在多个候选文件时，它会从 CLI 工作目录按以下顺序加载第一个：

```text
doctrine.config.ts
doctrine.config.mts
doctrine.config.js
doctrine.config.mjs
```

这些文件是可执行的 Vite 配置模块。`defineConfig` 只是 TypeScript 恒等辅助函数，不会沙箱化或
序列化模块。

```ts
import { defineConfig } from '@amamo/doctrine'

export default defineConfig({
  title: '我的项目文档',
  description: '我的项目产品指南和 API 说明。',
  siteUrl: 'https://docs.example.com/',
  githubUrl: 'https://github.com/your-org/my-project',
  pageActions: true,
  copyright: '版权所有 © 2026 你的组织。',
  iconLibrary: 'lucide-react',
  outDir: 'dist',
  locales: {
    default: 'en',
    names: ['en', 'zh-CN'],
    labels: { en: 'English', 'zh-CN': '简体中文' },
  },
  components: './docs/components.tsx',
  styles: './docs/theme.css',
})
```

## 网站选项

| 选项               | 类型                    | 默认值                             | 用途                                     |
| ------------------ | ----------------------- | ---------------------------------- | ---------------------------------------- |
| `title`            | `string`                | `"Documentation"`                  | 品牌文案和页面 title 后缀。              |
| `description`      | `string`                | `"Documentation built from MDX."`  | 默认 meta description。                  |
| `siteUrl`          | `string`                | `"http://localhost/"`              | 绝对公开 URL 和 Vite 部署 base。         |
| `githubUrl`        | `string`                | 无                                 | Header 与 MDX 页面操作使用的仓库链接。   |
| `githubSourceRoot` | `string`                | 位于项目 root 内时自动推导         | 源码链接所用的仓库内 content 路径。      |
| `pageActions`      | `boolean`               | `true`                             | 输出原始 `.md` 路由并显示 MDX 页面操作。 |
| `copyright`        | `string`                | 无                                 | Footer 文案。                            |
| `iconLibrary`      | `string`                | 无                                 | 提供导航图标命名 React 导出的模块。      |
| `outDir`           | `string`                | `"dist"`                           | 静态输出目录。                           |
| `locales`          | `IDoctrineLocaleConfig` | `{ default: "en", names: ["en"] }` | 语言路由、导航集合和切换标签。           |
| `components`       | `string`                | 无                                 | 自定义 MDX 组件模块。                    |
| `styles`           | `string`                | 无                                 | 在 Doctrine CSS 后加载的自定义样式表。   |

`title`、`description` 和 `copyright` 是站点级单一值。本地化页面描述应写在对应 MDX 的
frontmatter，或 locale 对应的导航条目中。

`siteUrl` 必须使用 HTTP 或 HTTPS，且不能包含 query 或 fragment。Doctrine 会把 pathname 归一化
为一个开头斜杠和一个结尾斜杠；这个 pathname 就是 `base`。`githubUrl` 应设为 GitHub 仓库的
HTTP 或 HTTPS URL，Header 图标会链接到该地址。启用页面操作时，**Open in GitHub** 会追加
`blob/HEAD` 和当前 locale 的源码路径，让 GitHub 打开仓库默认分支中的真实 MDX 文件。Doctrine
通常根据 content 目录相对项目 root 的路径自动推导。若 monorepo 中项目 root 位于仓库 root
之下，请把 `githubSourceRoot` 设为 content 目录相对仓库的 POSIX 路径，例如
`packages/docs/docs`。

`pageActions` 只作用于 MDX 正文页。默认值 `true` 会将每个页面的原始 MDX 输出到路由对应的
`.md` URL，并显示 **Copy Page**、**View as Markdown** 和条件性的 GitHub 操作。源码仍是 MDX，
可以包含 frontmatter、import 和 JSX。设为 `false` 会同时关闭 `.md` 输出和页面操作 UI。独立
TSX 页面始终不会获得这两项能力，Header 中的 GitHub 链接则不受影响。

生成的 Markdown 与 HTML 不能争用同一文件或彼此的父目录；生成的 `.md` 路径也不能与 `public/`
中的文件冲突。Doctrine 会在写入文档页面前报告这些冲突，而不会静默选择其中一份内容。

## 路径、优先级与生成目录

CLI 工作目录就是项目 root。相对路径从这里解析；绝对路径也可以使用，但仍须满足构建限制。

- 位置参数指定的内容目录默认是 `docs`，必须存在，并会被 canonicalize。
- `components` 和 `styles` 必须解析到现有文件，并会被 canonicalize。
- `outDir` 从 root 解析；它必须位于 root 内，不能等于 root，也不能位于内容目录内。
- 构建时，`--site-url` 和 `--out-dir` 会覆盖配置文件中的对应值。

客户端构建会先清空 `outDir`。不要把它指向源码或其它重要目录。Doctrine 还会创建
`.amamo-mdx/` 保存生成的内容注册表与缓存记录，并用 `.doctrine/` 保存临时构建文件；两者都
不应提交。

## 目录导航

每个包含对应 locale MDX 的目录都需要匹配的 TypeScript 导航模块：

- 默认 locale 使用 `meta.ts`
- 目录中存在的其他 locale 使用 `meta.<locale>.ts`

`defineDirectory` 同样只是恒等辅助函数。`items` 数组就是侧栏的准确顺序：

```ts
// docs/meta.zh-CN.ts
import { defineDirectory } from '@amamo/doctrine'

export default defineDirectory({
  items: [
    {
      page: 'index',
      title: '概览',
      description: '我的项目文档概览。',
      icon: 'House',
    },
    { directory: 'guide' },
    { page: 'configuration', title: '配置', icon: 'Settings' },
  ],
})
```

子目录定义分组标题和直属内容：

```ts
// docs/guide/meta.zh-CN.ts
import { defineDirectory } from '@amamo/doctrine'

export default defineDirectory({
  title: '指南',
  icon: 'BookOpen',
  items: [{ page: 'install', title: '安装', icon: 'PackagePlus' }],
})
```

根目录的 `title` 可省略；嵌套导航文件必须提供非空 title。页面条目可以定义 locale 对应的
`description`，在页面没有 frontmatter description 时使用。`page` 必须是不含斜杠、扩展名和 locale
后缀的直属 MDX basename。`directory` 必须是直属子目录名，不能是 `.` 或 `..`。

生产构建要求每个匹配页面和子目录恰好出现一次。重复条目、重复路由、非法结构、遗漏条目或
不存在的引用都会失败。Serve 模式仍会校验结构与重复项，但会省略暂时不存在的引用，并忽略
尚未加入导航的新文档。

页面条目与嵌套目录都可以使用图标。每个图标名必须符合 Doctrine 的 ASCII identifier 格式：
首字符只能是 `$`、`_` 或字母，后续可以使用数字；同时它必须是 `iconLibrary` 的命名 React
组件导出。Doctrine 只静态 import 导航实际使用的名称；缺少导出会导致打包失败。只要配置了
一个图标，就必须设置 `iconLibrary`。

## 路由与多语言

`locales.default` 必须包含在 `locales.names` 中；名称不能重复，并且只能由连字符分隔的字母与
数字片段组成。

```ts
locales: {
  default: 'en',
  names: ['en', 'zh-CN', 'ja'],
  labels: {
    en: 'English',
    'zh-CN': '简体中文',
    ja: '日本語',
  },
}
```

翻译通过文件名后缀定义：

```text
docs/guide/install.mdx       -> /guide/install/
docs/guide/install.zh-CN.mdx -> /zh-CN/guide/install/
docs/guide/install.ja.mdx    -> /ja/guide/install/
```

无后缀文件属于默认 locale。导航文件不会跨 locale fallback；只有另一个已配置 locale 具有相同
slug 时，语言按钮才会出现。`locales.labels` 缺失的条目直接显示 locale code。

内置界面文案在名称以 `zh` 开头的 locale 中使用中文，其余使用英文。路由、导航、元数据和
`<html lang>` 仍使用准确的配置 locale。

`index.mdx` 和 `page.mdx` 都映射到所在目录。同一目录、同一 locale 不要同时创建两者，否则会
产生重复路由。

## Frontmatter

Frontmatter 可省略。Doctrine 配置了一个公开字段：

```mdx
---
description: 用于 HTML 元数据的页面描述。
---
```

存在时，`description` 必须是字符串。页面 title 来自导航而不是 frontmatter。MDX 是可执行
内容；schema 校验不会让不可信文档变安全。

## 自定义组件与样式

`components` 指向默认导出 React 组件映射的模块：

```tsx
import type { IDoctrineComponents } from '@amamo/doctrine'
import type { ReactNode } from 'react'

interface INoticeProps {
  children: ReactNode
}

function Notice({ children }: INoticeProps) {
  return <aside className="project-notice">{children}</aside>
}

export default { Notice } satisfies IDoctrineComponents
```

该模块同时进入 SSR 与浏览器 bundle。它必须能在 Node.js 中渲染；浏览器专属全局变量只能在
effect 或事件处理器中使用，不能在模块初始化或渲染阶段访问。自定义名称会覆盖内置组件，包括
默认的 `a` 链接组件。

用 `styles` 设置组件 CSS 和主题变量。如果根 `package.json` 声明了 `tailwindcss`，Doctrine
还会启用 Tailwind Vite 插件。样式与覆盖详见[自定义](/zh-CN/customization/)，内置能力见
[MDX 组件](/zh-CN/mdx-components/)。