> ## Documentation Index
> Fetch the complete documentation index at: https://dob.topfde.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Mintlify setup

# Mintlify 配置指南：用 GitHub 发布 Markdown 文档

> 本文中由 Jeff Wang（Cloud Unfold Studio）创作的原创内容采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可，可用于商业转载和改编；使用时请注明作者、本文标题和来源链接，并说明是否修改。第三方文字、代码、图片、商标等不在本许可范围内，请遵循各自权利说明。

**文档版本：** 1.0.2

本文介绍如何在 VS Code 中编辑 Markdown，将文档保存在 GitHub，再由 Mintlify 构建并发布网站。文中的账号、仓库、项目名称、域名和表单地址都是示例，使用时请换成自己的信息。

```text theme={null}
VS Code 中的 Markdown → GitHub → Mintlify 构建 → 文档网站
```

## 准备工作

* 一个 GitHub 仓库，以及安装 Mintlify GitHub 应用的权限。组织仓库可能需要管理员批准。
* 至少一篇准备公开的 Markdown 页面。
* 一个用于发布的分支，例如 `main`。
* 如果要直接使用自定义域名，准备好域名的 DNS 管理权限。
* 如果要设置「联系作者」入口，准备好联系表单的公开链接。

下面是个性化字段的填写示例：

| 字段 | 示例值 | 说明 |
| - | - | - |
| GitHub 仓库 | `your-account/your-docs` | 替换为自己的 GitHub 账号或组织及仓库名 |
| 站点名称 | `Example Docs` | 替换为自己的文档站名称 |
| 文档目录 | `/docs` | 按仓库中的实际目录填写 |
| 自定义域名 | `docs.example.com` | 替换为自己拥有的域名；`example.com` 是示例域名 |
| 联系表单 | `https://tally.so/r/your-form-id` | 替换为自己的表单链接 |

## 一、准备文档目录

文档可以放在仓库根目录，也可以放在一个子目录中。这里以 `docs/` 为例：

```text theme={null}
your-docs/
└── docs/
    ├── docs.json
    ├── index.md
    └── guide.md
```

Mintlify 的 `docs.json` 用于设置站点名称、主题和导航。导航中的页面路径相对于 `docs.json` 所在的文档根目录，通常省略 `.md` 扩展名。页面没有列入导航时不会出现在侧边栏，但仍可能通过直接链接访问；不要用隐藏导航保护敏感内容。

如果文档放在仓库根目录，就把 `docs.json` 也放在根目录。配置文件和要发布的 Markdown 页面应位于同一个文档根目录。

## 二、连接 GitHub 仓库

如果仓库里已经有 Markdown 文档，按下面的顺序接入。Mintlify 的页面文字可能随产品更新略有变化，选项名称以控制台当前显示为准。

1. 登录 Mintlify 并创建文档站点。若出现迁移内容页面，而文档已经在自己的 GitHub 仓库中，选择 **Continue setup**；「克隆」或下载 ZIP 是把其他位置的内容迁入 GitHub 时使用的。
2. 按提示授权 Mintlify 访问 GitHub 账号。授权页面显示的账号权限与后续安装 GitHub App 的仓库权限可能是两步设置。
3. 安装 Mintlify 的 GitHub App。选择 **Only select repositories**（仅选择仓库），并勾选要发布文档的仓库；不要为了发布一个仓库就开放全部仓库。组织仓库可能需要组织管理员批准。
4. 回到 Mintlify，选择 GitHub 账号或组织、仓库和发布分支，例如 `main`。
5. 因为示例目录是 `docs/`，打开 **docs.json is in a subdirectory**（`docs.json` 位于子目录）选项，并填写 `/docs`。不要在路径末尾再加斜线。
6. 检查仓库、分支和文档目录后，继续完成连接并等待首次构建。
7. 在 Mintlify 控制台查看部署状态和构建日志。构建失败时先根据报错定位具体文件，不要直接覆盖 GitHub 上的内容。

如果看不到私有仓库，检查 GitHub App 的安装范围是否包含该仓库，并确认当前账号有仓库访问权限。Mintlify 的 GitHub 账号授权和 GitHub App 的仓库授权是不同设置。

### 编辑位置与 GitHub 同步

本项目以 VS Code 中的 Markdown 和 GitHub 提交记录为准。接入后，先在 Mintlify 查看构建结果；平时继续在 VS Code 编辑并推送。Mintlify 编辑器中的保存或发布操作可能会写入 Git 分支。若接受 Mintlify 提出的自动修改，之后到 GitHub 检查文件差异和提交记录，确认修改已进入预期分支，再继续编辑。

## 三、设置导航和联系入口

在 `docs.json` 的导航中加入需要展示的文档页面。新建页面后也要更新导航，否则页面不会出现在侧边栏。

如果希望读者联系你，可以添加一个名为「联系作者」的外部链接，并将目标地址替换成自己的联系表单，例如：

```text theme={null}
https://tally.so/r/your-form-id
```

在表单中可将留言设为必填、回复邮箱设为选填，并开启新提交提醒。普通链接不会自动传递读者正在查看的文档页面；如需记录来源页面，需要额外实现并验证动态传递功能。

## 四、设置自定义域名

你可以先使用 Mintlify 提供的子域名，也可以在首次发布前直接配置自己的域名。

1. 在 Mintlify 控制台的站点设置中添加自定义域名，例如 `docs.example.com`。如果计划首发就使用自定义域名，可以在首次公开分享前完成这一步。
2. 在域名服务商的 DNS 管理页面，按 Mintlify 控制台当前显示的记录添加或调整 DNS。不要照抄其他教程里的记录值，因为平台提供的值可能变化。
3. 不要覆盖仍在使用的 DNS 记录；记录值和验证方式以 Mintlify 控制台为准。
4. 等待域名验证及 HTTPS 证书配置完成，再打开域名检查网站。

## 五、验证自动发布

1. 在本地修改 Markdown，并在 VS Code 的源代码管理面板中查看文件差异。
2. 提交并推送到 Mintlify 配置的发布分支；如果使用拉取请求流程，先完成复核并合并。
3. 在 Mintlify 控制台查看构建状态和错误信息。
4. 打开网站，检查页面内容、导航、图片、代码块、自定义域名和联系表单链接。
5. 再推送一次小的文档修改，确认后续更新也能触发构建。

构建成功只说明网站已生成，不代表页面内容已经验收。还要在公开网站实际检查链接和显示效果。若站点设置为公开，发布目录中的所有内容都会对公众开放；不要放密钥、密码、私人信息或未清理的内网地址。

## 检查清单

* [ ] Mintlify 连接到预期的 GitHub 仓库和发布分支。
* [ ] 文档根目录和 `docs.json` 位置正确。
* [ ] 导航引用的页面均存在。
* [ ] 推送到发布分支后成功触发构建。
* [ ] 若在 Mintlify 编辑器中接受过修改，已在 GitHub 检查对应差异和提交记录。
* [ ] 公开网站上的导航、页面、图片和代码块显示正常。
* [ ] 自定义域名可访问并使用 HTTPS（若已配置）。
* [ ] 联系表单链接指向自己的表单，提交后能收到提醒（若已配置）。
* [ ] 发布目录中没有密钥、私人信息或其他不应公开的内容。

## 官方资料

* [Mintlify 快速开始指南](https://mintlify.com/docs/quickstart)
* [Mintlify 的 GitHub 部署说明](https://www.mintlify.com/docs/deploy/github)
* [Mintlify 导航配置](https://mintlify.com/docs/navigation)
* [Mintlify 隐藏页面说明](https://mintlify.com/docs/guides/hidden-pages)
* [Mintlify 自定义域名](https://mintlify.com/docs/settings/custom-domain)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.