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

入门教程

这份指南从空项目开始，最终会在 dist 中得到可以直接部署的静态网站。

1. 检查构建环境

Doctrine 需要 Node.js 20.19 或更新版本，并且机器必须属于 @amamo/mdx 的 受支持原生目标。原生编译器没有 JavaScript fallback。MDX 可以在打包、预渲染和 hydration 时执行 JavaScript，因此只能使用可信作者提供的 内容与配置。

安装包：

Shell
pnpm add @amamo/doctrine

然后创建内容目录：

Shell
mkdir -p docs/guide

2. 添加两篇页面

创建 docs/index.mdx：

MDX
# 我的项目文档

从导航中选择一篇指南。

创建 docs/guide/install.mdx：

MDX
# 安装我的项目

<InstallTabs packageName="my-project" />

页面不要求 frontmatter。可选的字符串 description 会成为该页面的 meta description。

3. 定义导航

每个含有对应 locale MDX 的目录都需要匹配的导航模块。根目录的 docs/meta.ts 负责首页和 子目录的顺序：

TypeScript
import { defineDirectory } from '@amamo/doctrine'

export default defineDirectory({
  items: [{ page: 'index', title: '我的项目文档' }, { directory: 'guide' }],
})

在嵌套页面旁创建 docs/guide/meta.ts：

TypeScript
import { defineDirectory } from '@amamo/doctrine'

export default defineDirectory({
  title: '指南',
  items: [{ page: 'install', title: '安装我的项目' }],
})

数组决定侧栏的准确顺序。page 是直属 MDX basename；directory 是直属子目录。生产构建要求 每个页面和子目录恰好出现一次。

4. 启动开发服务器

Shell
doctrine dev docs

打开 http://localhost:5173。Vite 会服务端渲染每次请求，再在浏览器 hydration。MDX 修改由 内容插件更新；新增、删除或编辑导航元数据会刷新路由模型，不需要重启服务器。

当页面与 meta.ts 条目分两次保存时，开发模式可以容忍短暂的不一致。内容变化会让开发 Pagefind 索引失效，下一次搜索请求才会惰性重建它。

需要其他监听地址或端口时：

Shell
doctrine dev docs --host 0.0.0.0 --port 4173

5. 添加可选的网站元数据

在 CLI 运行目录创建 doctrine.config.ts：

TypeScript
import { defineConfig } from '@amamo/doctrine'

export default defineConfig({
  title: '我的项目文档',
  description: '我的项目产品指南和 API 说明。',
  githubUrl: 'https://github.com/your-org/my-project',
})

没有配置文件时，title 是 Documentation，description 是 Documentation built from MDX.，并且只启用 en locale。

6. 构建静态网站

传入真实公开网址，包括可能存在的仓库路径：

Shell
doctrine build docs --site-url https://docs.example.com/

默认产物为：

text
dist/
├── 404.html
├── assets/
├── guide/install.md
├── guide/install/index.html
├── index.html
├── index.md
└── pagefind/

Doctrine 会构建客户端与 SSR bundle、预渲染全部导航路由、把原始 MDX 写入对应的 .md 路径、 移除 Vite 私有 manifest，再由 Pagefind 索引最终 HTML。https://user.github.io/my-project/ 这样的仓库网址会把公开 URL 改为 /my-project/...，而不会创建 dist/my-project。

7. 不要提交生成目录

除了 dist，Doctrine 还用 .amamo-mdx/ 保存生成的内容注册表与缓存记录，并用 .doctrine/ 保存临时构建文件。请把三个目录都加入项目的 ignore 文件。

继续阅读配置参考了解全部选项、自定义配置样式 与覆盖，查看 MDX 组件参考内置能力，或使用 GitHub Pages 的部署工作流。

copyright © 2026 白熱。