快速入门

在几分钟内部署文档

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

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

准备工作：开始之前，请先创建账号并完成引导设置。

​

入门

完成初始设置后，你的文档站点会自动部署到一个唯一的 URL，格式如下：

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

在你的控制台的“概览”页面查找你的 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）mint：

npm

npm i -g mint

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

​

编辑文档

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

1. 打开你在入门引导过程中创建的代码仓库。
2. 打开 index.mdx，定位到文件顶部：

index.mdx

---
title: "介绍"
description: "这是文档的介绍"
---

3. 将 title 字段改为 "Hello World"。

index.mdx

---
title: "Hello World"
description: "这是文档的简介"
---

​

预览更改

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

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 记录。