---
description: 从零创建、预览并构建一个 Doctrine 网站。
---

# 入门教程

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

## 1. 检查构建环境

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

安装包：

<InstallTabs packageName="@amamo/doctrine" />

然后创建内容目录：

```sh
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` 负责首页和
子目录的顺序：

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

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

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

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

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

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

## 4. 启动开发服务器

```sh
doctrine dev docs
```

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

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

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

```sh
doctrine dev docs --host 0.0.0.0 --port 4173
```

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

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

```ts
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. 构建静态网站

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

```sh
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 文件。

继续阅读[配置参考](/zh-CN/configuration/)了解全部选项、[自定义](/zh-CN/customization/)配置样式
与覆盖，查看 [MDX 组件](/zh-CN/mdx-components/)参考内置能力，或使用
[GitHub Pages](/zh-CN/deployment/) 的部署工作流。