Skip to main content

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

本文中由 Jeff Wang（Cloud Unfold Studio）创作的原创内容采用 CC BY 4.0 许可，可用于商业转载和改编；使用时请注明作者、本文标题和来源链接，并说明是否修改。第三方文字、代码、图片、商标等不在本许可范围内，请遵循各自权利说明。
文档版本： 1.0.2 本文介绍如何在 VS Code 中编辑 Markdown，将文档保存在 GitHub，再由 Mintlify 构建并发布网站。文中的账号、仓库、项目名称、域名和表单地址都是示例，使用时请换成自己的信息。

​
准备工作

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

​
一、准备文档目录

文档可以放在仓库根目录，也可以放在一个子目录中。这里以 docs/ 为例：
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 的导航中加入需要展示的文档页面。新建页面后也要更新导航，否则页面不会出现在侧边栏。 如果希望读者联系你，可以添加一个名为「联系作者」的外部链接，并将目标地址替换成自己的联系表单，例如：
在表单中可将留言设为必填、回复邮箱设为选填，并开启新提交提醒。普通链接不会自动传递读者正在查看的文档页面；如需记录来源页面，需要额外实现并验证动态传递功能。

​
四、设置自定义域名

你可以先使用 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（若已配置）。
  • 联系表单链接指向自己的表单，提交后能收到提醒（若已配置）。
  • 发布目录中没有密钥、私人信息或其他不应公开的内容。

​
官方资料

Last modified on November 12, 2026