快速上手

在几分钟内部署文档

本快速上手指南将演示如何在几分钟内设置并部署你的文档站点。

完成本指南后，你将拥有一个已上线的文档站点，可随时进行自定义和扩展。

前提条件：开始之前，请先创建账号并完成入门流程。

入门

完成入门流程后，你的文档站点会自动部署到一个唯一的 URL，格式如下：

https://<your-project-name>.mintlify.app

在你的仪表板的 Overview 页面找到该 URL。

你的站点 URL 会立即生效。在你设置文档站点期间，使用该 URL 进行测试并与团队共享。

安装 GitHub 应用

Mintlify 提供了一个 GitHub 应用，可在你将更改推送到仓库时自动部署。

按照入门清单或控制台中的指引安装 GitHub 应用。

1. 在 Mintlify 控制台中进入 Settings。
2. 在侧边栏选择 GitHub App。
3. 选择 Install GitHub App。这将在新标签页中打开 GitHub 应用的安装页面。
4. 选择要安装该应用的组织或个人账户。
5. 选择你要连接的仓库。

如果你将文档迁移到其他仓库，请更新 GitHub 应用的权限。

授权你的 GitHub 账户

1. 在 Mintlify 仪表盘中前往 Settings。
2. 在侧边栏选择 My Profile。
3. 点击 Authorize GitHub account。这会在新标签页中打开 GitHub 授权页面。

根据你所在组织的设置，你的 GitHub 组织管理员可能需要为你的账户授权。

编辑工作流

Mintlify 提供两种用于创建和维护文档的工作流：

基于代码的工作流

适合在本地环境中使用现有工具的用户。点击以跳转至本节。

网页编辑器工作流

适合在浏览器中使用可视化界面的用户。点击以跳转至本节。

基于代码的工作流

基于代码的工作流可与您现有的开发环境和 Git 仓库集成。此工作流最适合希望将文档与代码并行管理的技术团队。

安装 CLI

要在本地编辑文档，请在终端运行以下命令安装命令行工具（CLI）mint：

npm

npm i -g mint

你的机器需要预先安装 Node.js。若遇到安装问题，请查看故障排查指南。

编辑文档

完成环境配置后，你就可以开始编辑文档文件了。例如，更新简介页面的标题：

1. 打开你在引导流程中创建的代码仓库。
2. 打开 index.mdx 并找到文件顶部：

index.mdx

---
title: "Introduction"
description: "This is the introduction to the documentation"
---

3. 将 title 字段更新为 "Hello World"。

index.mdx

---
title: "Hello World"
description: "This is the introduction to the documentation"
---

预览更改

要在本地预览更改，请运行以下命令：

mint dev

预览可在 localhost:3000 访问。

推送更改

当你准备发布更改时，将它们推送到你的代码仓库。

Mintlify 会自动检测更改、构建文档，并将更新部署到你的网站。你可以在 GitHub 仓库的提交历史或仪表盘中查看部署状态。

部署完成后，你的最新更新将可通过 <your-project-name>.mintlify.app 访问。

跳转到添加自定义域名

你也可以跳过网页编辑器流程，直接前往添加自定义域名。

网页编辑器工作流

网页编辑器工作流提供一个所见即所得（WYSIWYG）界面，用于创建和编辑文档。该工作流最适合希望直接在浏览器中工作、且不需要额外本地开发工具的用户。

访问网页编辑器

1. 登录你的控制台。
2. 在左侧边栏选择 Editor。

如果你尚未安装 GitHub 应用，打开网页编辑器时会提示你进行安装。

编辑文档

在网页编辑器中，你可以在侧边栏浏览文档文件。我们来更新一下介绍页：

在文件浏览器中找到并选择 index.mdx。

然后在编辑器中，将标题字段更新为“Hello World”。

编辑器提供了丰富的格式化工具和组件。在编辑器中输入 / 可打开命令菜单以使用这些工具。

发布更改

当你对编辑结果满意时，点击右上角的 Publish 按钮。你的更改会立即部署到文档站点。

使用分支配合拉取请求，在部署到正式站点前先进行预览与评审。

有关使用网页编辑器的更多详情（包括如何通过分支和拉取请求协作并预览更改），请参阅我们的网页编辑器文档。

添加自定义域名

虽然你的 <your-project-name>.mintlify.app 子域名适合测试和开发，但大多数团队在生产环境的文档中更倾向于使用自定义域名。

要添加自定义域名，请在控制台前往 Domain Setup 页面。

输入你的域名（例如 docs.yourcompany.com），并按照页面提供的指引在你的域名服务商处配置 DNS 设置。

DNS 变更最多可能需要 48 小时才能完全生效，但通常会更快完成。

后续步骤

恭喜！您已使用 Mintlify 成功部署文档站点。以下是提升文档的建议后续步骤：

配置全局设置

使用 docs.json 文件配置站点级样式、导航、集成等。

自定义主题

了解如何自定义文档站点的配色、字体和整体外观。

组织导航

以直观的导航来组织文档，帮助用户快速找到所需内容。

添加交互式组件

通过手风琴、选项卡和代码示例等交互式组件增强文档。

设置 API 参考

使用 OpenAPI 和 AsyncAPI 规范创建交互式 API 参考。

故障排除

如果在设置过程中遇到问题，请查看以下常见解决方案：

本地预览无法运行

请确保已安装 Node.js v19+，并在包含 docs.json 文件的目录中运行 mint dev 命令。

更改未在线上站点生效

部署可能需要几分钟时间。请检查你的 GitHub Actions（用于代码化工作流）或在 Mintlify 控制台中的部署日志，确认没有构建错误。

自定义域名无法连接

请核对 DNS 记录配置是否正确，并预留足够的 DNS 传播时间（最长可达 48 小时）。你可以使用 DNSChecker 等工具验证 CNAME 记录。