跳到正文
@amamo/doctrine
本页目录

配置参考

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

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

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

TypeScript
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',
})

网站选项

选项类型默认值用途
titlestring"Documentation"品牌文案和页面 title 后缀。
descriptionstring"Documentation built from MDX."默认 meta description。
siteUrlstring"http://localhost/"绝对公开 URL 和 Vite 部署 base。
githubUrlstring无Header 与 MDX 页面操作使用的仓库链接。
githubSourceRootstring位于项目 root 内时自动推导源码链接所用的仓库内 content 路径。
pageActionsbooleantrue输出原始 .md 路由并显示 MDX 页面操作。
copyrightstring无Footer 文案。
iconLibrarystring无提供导航图标命名 React 导出的模块。
outDirstring"dist"静态输出目录。
localesIDoctrineLocaleConfig{ default: "en", names: ["en"] }语言路由、导航集合和切换标签。
componentsstring无自定义 MDX 组件模块。
stylesstring无在 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 数组就是侧栏的准确顺序：

TypeScript
// 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' },
  ],
})

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

TypeScript
// 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 中；名称不能重复，并且只能由连字符分隔的字母与 数字片段组成。

TypeScript
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 插件。样式与覆盖详见自定义，内置能力见 MDX 组件。

copyright © 2026 白熱。