快速上手

几分钟内部署你的文档

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

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

先决条件：开始前，请先创建账户并完成引导设置。

​

入门

完成初始设置后，你的文档站点会自动部署到一个唯一的 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）

要在本地处理文档，请在终端运行以下命令，安装名为 mint 的命令行界面（CLI）：

npm

npm i -g mint

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

​

编辑文档

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

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

index.mdx

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

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

index.mdx

---
title: "你好世界"
description: "这是文档的介绍"
---

​

预览更改

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

mint dev

你的预览将可在 localhost:3000 查看。

​

推送更改

当你准备发布更改时，将其推送到你的存储库。

Mintlify 会自动检测更改，构建你的文档，并将更新部署到你的网站。你可以在 GitHub 存储库的提交历史或 控制台 中查看部署状态。

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

跳转到添加自定义域名

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

​

Web editor 工作流

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

​

访问网页编辑器

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

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

​

编辑文档

在 Web 编辑器中，你可以通过侧边栏浏览文档文件。现在更新介绍页：

在文件资源管理器中找到并选择 index.mdx。

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

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

​

发布更改

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

使用 branch，并通过拉取请求（PR；亦称“合并请求”/Merge Request）在部署到线上站点前进行预览和评审。

关于使用网页版编辑器的更多详情（包括如何使用 branch 和拉取请求进行协作与预览更改），请参阅我们的网页版编辑器文档。

​

添加自定义域名

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

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

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

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

​

后续步骤

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

配置全局设置

使用 docs.json 文件配置全站样式、导航、integrations 等更多设置。

自定义主题

了解如何自定义颜色、字体，以及文档站点的整体外观。

组织导航

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

添加交互组件

使用折叠面板、选项卡和代码示例等交互组件增强文档。

设置 API 参考

基于 OpenAPI 和 AsyncAPI 规范创建交互式 API 参考。

​

疑难解答

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

本地预览无法运行

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

更改未在在线站点生效

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

自定义域名无法连接

请确认你的 DNS（域名系统）记录已正确配置，并留出足够的 DNS 传播时间（最长可达 48 小时）。你可以使用 DNSChecker 等工具验证你的 CNAME 记录。