跳转到主要内容
完成本指南后，你将拥有一个已上线的文档站点，可以开始对其进行自定义和扩展。
前提条件：在开始之前，请先创建账户并完成引导流程。

​
快速开始

完成入门引导后，你的文档站点会自动部署到一个符合以下格式的唯一 URL： 
https://<你的项目名称>.mintlify.app
在你的控制台的概览（Overview）页面中找到你的 URL。
Mintlify 域名
你的网站 URL 会立即生效。在你设置文档站点的过程中，可以使用这个 URL 进行测试并与团队分享。

​
安装 GitHub 应用

Mintlify 提供了一个 GitHub 应用，你在将更改推送到仓库时，它会自动触发部署。 按照新手引导清单或仪表盘中的指引来安装 GitHub 应用。
  1. 在 Mintlify 仪表盘中前往 Settings。
  2. 在侧边栏中选择 GitHub App。
  3. 选择 Install GitHub App。这会在新标签页中打开 GitHub 应用的安装页面。
  4. 选择你希望安装该应用的组织或用户账号。
  5. 选择你想要连接的仓库。
GitHub 应用安装
如果你将文档迁移到其他仓库，请更新 GitHub 应用的权限。

​
授权你的 GitHub 账户

  1. 在 Mintlify 控制台前往 Settings。
  2. 在侧边栏选择 My Profile。
  3. 选择 Authorize GitHub account。会在新标签页中打开 GitHub 授权页面。
根据你组织的设置，你的 GitHub 组织管理员可能需要为你的账户进行授权。

​
编辑工作流程

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

基于代码的工作流程

适合在本地环境中配合现有工具工作的用户。点击跳转到该章节。

网页编辑器工作流程

适合在网页浏览器中使用可视化界面的用户。点击跳转到该章节。

​
基于代码的工作流

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

​
安装 CLI

前置条件：CLI 需要 Node.js v20.17.0 至 v24 之间的版本（含 v20.17.0），推荐使用 LTS 版本。
要在本地编辑你的文档，请在终端中运行以下命令安装名为 mint 的命令行工具（CLI）： 
npm i -g mint

​
创建新项目

运行 mint new 以创建一个新的文档项目。关于该命令及其可用选项的详细说明，请参阅 命令行界面（CLI）安装指南。

​
编辑文档

完成项目设置后，你就可以开始编辑文档文件了。例如，更新介绍页面的标题：
  1. 打开你的文档存储库。
  2. 打开 index.mdx，找到文件顶部：
index.mdx
---
title: "简介"
description: "这是文档的介绍"
---
  1. 将 title 字段更新为 "Hello World"。
index.mdx
---
title: "Hello World"
description: "这是文档的介绍"
---

​
预览更改

要在本地预览这些更改，请运行以下命令： 
mint dev
你可以在 localhost:3000 查看预览。
Mintlify Dev

​
推送更改

当你准备好发布更改时，将它们推送到你的代码仓库。 Mintlify 会自动检测这些更改，构建你的文档，并将更新部署到你的站点。你可以在 GitHub 仓库的提交记录或在 仪表盘 中监控部署状态。 部署完成后，你的最新更新将可以通过 <your-project-name>.mintlify.app 访问。

前往添加自定义域名

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

​
Web editor 工作流

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

​
访问网页编辑器

  1. 登录你的控制台。
  2. 在左侧边栏选择 Editor。
如果你还没有安装 GitHub App，打开网页编辑器时系统会提示你安装该应用。
Mintlify 网页编辑器的可视化编辑模式

​
编辑文档

在 Web 编辑器中，你可以在侧边栏中浏览文档文件。我们来更新一下简介页面： 在文件浏览器中找到并选择 index.mdx。 然后在编辑器中，将标题字段更新为 “Hello World”。
在 Web 编辑器中编辑
编辑器提供了丰富的格式化工具和组件。在编辑器中输入 / 以打开命令菜单并使用这些工具。

​
发布你的更改

当你对编辑结果满意时，点击右上角的 Publish 按钮。你的更改会立即部署到文档站点。
使用 branch，通过拉取请求（PR；亦称“合并请求”/Merge Request）在部署到线上站点之前进行预览和评审。
有关使用网页编辑器的更多信息，包括如何使用 branch 和拉取请求进行协作与预览更改，请参阅我们的网页编辑器文档。

​
添加自定义域名

虽然你的 <your-project-name>.mintlify.app 子域名非常适合测试和开发环境，但大多数团队更倾向于在生产环境的文档中使用自定义域名。 要添加自定义域名，请在控制台中前往 Domain Setup 页面。
自定义域名
输入你的域名（例如 docs.yourcompany.com），然后按照页面提示，在你的域名服务商处配置 DNS 设置。
DNS 变更的全球生效可能需要长达 48 小时，但通常会在更短时间内完成。

​
后续步骤

恭喜！你已成功使用 Mintlify 部署文档站点。以下是一些推荐的后续步骤，帮助你进一步完善文档：

配置全局设置

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

自定义你的主题

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

组织导航结构

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

添加交互组件

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

设置 API 参考

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

​
故障排查

如果你在配置过程中遇到问题，请查看以下常见解决方案：
请确保你已安装 Node.js v20.17.0 或更高版本，并且在包含 docs.json 文件的目录中运行 mint dev 命令。
部署可能需要几分钟时间。请检查你的 GitHub Actions（适用于基于代码的工作流）或 Mintlify 控制台中的部署日志，以确保没有构建错误。
请确认你的 DNS 记录配置正确，并预留足够的 DNS 传播时间（最长可达 48 小时）。你可以使用 DNSChecker 等工具来验证你的 CNAME 记录。