mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
59fde7770c
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
298 lines
10 KiB
Plaintext
298 lines
10 KiB
Plaintext
---
|
||
title: "快速入门"
|
||
description: "部署你的文档站点并完成首次更改。"
|
||
keywords: ["快速入门","部署","入门","第一步"]
|
||
---
|
||
|
||
完成本指南后，你将拥有一个已上线的文档站点，可以开始对其进行自定义和扩展。
|
||
|
||
<Info>
|
||
**前提条件**：在开始之前，请先[创建账户](https://mintlify.com/start)并完成引导流程。
|
||
</Info>
|
||
|
||
<div id="getting-started">
|
||
## 快速开始
|
||
</div>
|
||
|
||
完成入门引导后，你的文档站点会自动部署到一个符合以下格式的唯一 URL：
|
||
|
||
```
|
||
https://<你的项目名称>.mintlify.app
|
||
```
|
||
|
||
在你的[控制台](https://dashboard.mintlify.com/)的概览（Overview）页面中找到你的 URL。
|
||
|
||
<Frame>
|
||
<img src="/images/quickstart/mintlify-domain-light.png" alt="Mintlify 域名" className="block dark:hidden" />
|
||
|
||
<img src="/images/quickstart/mintlify-domain-dark.png" alt="Mintlify 域名" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
你的网站 URL 会立即生效。在你设置文档站点的过程中，可以使用这个 URL 进行测试并与团队分享。
|
||
|
||
<div id="install-the-github-app">
|
||
### 安装 GitHub 应用
|
||
</div>
|
||
|
||
Mintlify 提供了一个 GitHub 应用，你在将更改推送到仓库时，它会自动触发部署。
|
||
|
||
按照新手引导清单或仪表盘中的指引来安装 GitHub 应用。
|
||
|
||
1. 在 Mintlify 仪表盘中前往 **Settings**。
|
||
2. 在侧边栏中选择 **GitHub App**。
|
||
3. 选择 **Install GitHub App**。这会在新标签页中打开 GitHub 应用的安装页面。
|
||
4. 选择你希望安装该应用的组织或用户账号。
|
||
5. 选择你想要连接的仓库。
|
||
|
||
<Frame>
|
||
<img src="/images/quickstart/github-app-installation-light.png" alt="GitHub 应用安装" className="block dark:hidden" />
|
||
|
||
<img src="/images/quickstart/github-app-installation-dark.png" alt="GitHub 应用安装" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<Info>
|
||
如果你将文档迁移到其他仓库，请更新 GitHub 应用的权限。
|
||
</Info>
|
||
|
||
<div id="authorize-your-github-account">
|
||
### 授权你的 GitHub 账户
|
||
</div>
|
||
|
||
1. 在 Mintlify 控制台前往 **Settings**。
|
||
2. 在侧边栏选择 **My Profile**。
|
||
3. 选择 **Authorize GitHub account**。会在新标签页中打开 GitHub 授权页面。
|
||
|
||
<Info>
|
||
根据你组织的设置，你的 GitHub 组织管理员可能需要为你的账户进行授权。
|
||
</Info>
|
||
|
||
<div id="editing-workflows">
|
||
## 编辑工作流程
|
||
</div>
|
||
|
||
Mintlify 提供两种用于创建和维护文档的工作流程：
|
||
|
||
<Card title="基于代码的工作流程" icon="terminal" horizontal href="#code-based-workflow">
|
||
适合在本地环境中配合现有工具工作的用户。点击跳转到该章节。
|
||
</Card>
|
||
|
||
<Card title="网页编辑器工作流程" icon="mouse-pointer-2" horizontal href="#web-editor-workflow">
|
||
适合在网页浏览器中使用可视化界面的用户。点击跳转到该章节。
|
||
</Card>
|
||
|
||
<div id="code-based-workflow">
|
||
## 基于代码的工作流
|
||
</div>
|
||
|
||
基于代码的工作流可与您现有的开发环境和 Git 仓库集成。该工作流最适合希望将文档与代码并行管理的技术团队。
|
||
|
||
<div id="install-the-cli">
|
||
### 安装 CLI
|
||
</div>
|
||
|
||
<Info>
|
||
**前置条件**：CLI 需要 [Node.js](https://nodejs.org/en) v20.17.0 至 v24 之间的版本（含 v20.17.0），推荐使用 LTS 版本。
|
||
</Info>
|
||
|
||
要在本地编辑你的文档，请在终端中运行以下命令安装名为 [mint](https://www.npmjs.com/package/mint) 的命令行工具（CLI）：
|
||
|
||
<CodeGroup>
|
||
```bash npm
|
||
npm i -g mint
|
||
```
|
||
|
||
```bash pnpm
|
||
pnpm add -g mint
|
||
```
|
||
</CodeGroup>
|
||
|
||
<div id="create-a-new-project">
|
||
### 创建新项目
|
||
</div>
|
||
|
||
运行 `mint new` 以创建一个新的文档项目。关于该命令及其可用选项的详细说明，请参阅 [命令行界面（CLI）安装指南](/zh/installation#create-a-new-project)。
|
||
|
||
<div id="edit-the-documentation">
|
||
### 编辑文档
|
||
</div>
|
||
|
||
完成项目设置后，你就可以开始编辑文档文件了。例如，更新介绍页面的标题：
|
||
|
||
1. 打开你的文档存储库。
|
||
2. 打开 `index.mdx`，找到文件顶部：
|
||
|
||
```mdx index.mdx
|
||
---
|
||
title: "简介"
|
||
description: "这是文档的介绍"
|
||
---
|
||
```
|
||
|
||
3. 将 `title` 字段更新为 `"Hello World"`。
|
||
|
||
```mdx index.mdx {2}
|
||
---
|
||
title: "Hello World"
|
||
description: "这是文档的介绍"
|
||
---
|
||
```
|
||
|
||
<div id="preview-the-changes">
|
||
### 预览更改
|
||
</div>
|
||
|
||
要在本地预览这些更改，请运行以下命令：
|
||
|
||
```bash
|
||
mint dev
|
||
```
|
||
|
||
你可以在 `localhost:3000` 查看预览。
|
||
|
||
<Frame>
|
||
<img src="/images/quickstart/mintlify-dev-light.png" alt="Mintlify Dev" className="block dark:hidden" />
|
||
|
||
<img src="/images/quickstart/mintlify-dev-dark.png" alt="Mintlify Dev" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<div id="push-the-changes">
|
||
### 推送更改
|
||
</div>
|
||
|
||
当你准备好发布更改时，将它们推送到你的代码仓库。
|
||
|
||
Mintlify 会自动检测这些更改，构建你的文档，并将更新部署到你的站点。你可以在 GitHub 仓库的提交记录或在 [仪表盘](https://dashboard.mintlify.com) 中监控部署状态。
|
||
|
||
部署完成后，你的最新更新将可以通过 `<your-project-name>.mintlify.app` 访问。
|
||
|
||
<Card title="前往添加自定义域名" icon="arrow-down" horizontal href="#adding-a-custom-domain">
|
||
你也可以选择跳过网页编辑器的流程，直接前往添加自定义域名。
|
||
</Card>
|
||
|
||
<div id="web-editor-workflow">
|
||
## Web editor 工作流
|
||
</div>
|
||
|
||
Web editor 工作流提供 WYSIWYG（所见即所得）界面，用于创建和编辑文档。该工作流最适合希望直接在网页浏览器中工作且无需额外本地开发工具的用户。
|
||
|
||
<div id="access-the-web-editor">
|
||
### 访问网页编辑器
|
||
</div>
|
||
|
||
1. 登录你的[控制台](https://dashboard.mintlify.com)。
|
||
2. 在左侧边栏选择 **Editor**。
|
||
|
||
<Info>
|
||
如果你还没有安装 GitHub App，打开网页编辑器时系统会提示你安装该应用。
|
||
</Info>
|
||
|
||
<Frame>
|
||
<img alt="Mintlify 网页编辑器的可视化编辑模式" src="/images/quickstart/web-editor-light.png" className="block dark:hidden" />
|
||
|
||
<img alt="Mintlify 网页编辑器的可视化编辑模式" src="/images/quickstart/web-editor-dark.png" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<div id="edit-the-documentation">
|
||
### 编辑文档
|
||
</div>
|
||
|
||
在 Web 编辑器中，你可以在侧边栏中浏览文档文件。我们来更新一下简介页面：
|
||
|
||
在文件浏览器中找到并选择 `index.mdx`。
|
||
|
||
然后在编辑器中，将标题字段更新为 "Hello World"。
|
||
|
||
<Frame>
|
||
<img alt="在 Web 编辑器中编辑" src="/images/quickstart/web-editor-editing-light.png" className="block dark:hidden" />
|
||
|
||
<img alt="在 Web 编辑器中编辑" src="/images/quickstart/web-editor-editing-dark.png" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
<Tip>
|
||
编辑器提供了丰富的格式化工具和组件。在编辑器中输入 <kbd>/</kbd>
|
||
以打开命令菜单并使用这些工具。
|
||
</Tip>
|
||
|
||
<div id="publish-your-changes">
|
||
### 发布你的更改
|
||
</div>
|
||
|
||
当你对编辑结果满意时，点击右上角的 **Publish** 按钮。你的更改会立即部署到文档站点。
|
||
|
||
<Tip>
|
||
使用 branch，通过拉取请求（PR；亦称“合并请求”/Merge Request）在部署到线上站点之前进行预览和评审。
|
||
</Tip>
|
||
|
||
有关使用网页编辑器的更多信息，包括如何使用 branch 和拉取请求进行协作与预览更改，请参阅我们的[网页编辑器文档](/zh/editor)。
|
||
|
||
<div id="adding-a-custom-domain">
|
||
## 添加自定义域名
|
||
</div>
|
||
|
||
虽然你的 `<your-project-name>.mintlify.app` 子域名非常适合测试和开发环境，但大多数团队更倾向于在生产环境的文档中使用自定义域名。
|
||
|
||
要添加自定义域名，请在控制台中前往 [Domain Setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) 页面。
|
||
|
||
<Frame>
|
||
<img src="/images/quickstart/custom-domain-light.png" alt="自定义域名" className="block dark:hidden" />
|
||
|
||
<img src="/images/quickstart/custom-domain-dark.png" alt="自定义域名" className="hidden dark:block" />
|
||
</Frame>
|
||
|
||
输入你的域名（例如 `docs.yourcompany.com`），然后按照页面提示，在你的域名服务商处配置 DNS 设置。
|
||
|
||
<Table>
|
||
| 记录类型 | 名称 | 值 | TTL |
|
||
| -------- | ------------------- | ---------------------- | ---- |
|
||
| CNAME | docs（或子域名） | cname.vercel-dns.com | 3600 |
|
||
</Table>
|
||
|
||
<Info>
|
||
DNS 变更的全球生效可能需要长达 48 小时，但通常会在更短时间内完成。
|
||
</Info>
|
||
|
||
<div id="next-steps">
|
||
## 后续步骤
|
||
</div>
|
||
|
||
恭喜！你已成功使用 Mintlify 部署文档站点。以下是一些推荐的后续步骤，帮助你进一步完善文档：
|
||
|
||
<Card title="配置全局设置" icon="settings" horizontal href="zh/organize/settings">
|
||
使用 `docs.json` 文件配置站点级样式、导航、集成等。
|
||
</Card>
|
||
|
||
<Card title="自定义你的主题" icon="paintbrush" horizontal href="zh/customize/themes">
|
||
了解如何自定义文档站点的颜色、字体和整体外观。
|
||
</Card>
|
||
|
||
<Card title="组织导航结构" icon="map" horizontal href="zh/organize/navigation">
|
||
通过直观的导航结构组织你的文档，帮助用户快速找到所需内容。
|
||
</Card>
|
||
|
||
<Card title="添加交互组件" icon="puzzle" horizontal href="/zh/components/accordions">
|
||
使用折叠面板、选项卡和代码示例等交互组件增强你的文档。
|
||
</Card>
|
||
|
||
<Card title="设置 API 参考" icon="code" horizontal href="/zh/api-playground/overview">
|
||
使用 OpenAPI 和 AsyncAPI 规范创建交互式 API 参考文档。
|
||
</Card>
|
||
|
||
<div id="troubleshooting">
|
||
## 故障排查
|
||
</div>
|
||
|
||
如果你在配置过程中遇到问题，请查看以下常见解决方案：
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="本地预览无法运行">
|
||
请确保你已安装 Node.js v20.17.0 或更高版本，并且在包含 `docs.json` 文件的目录中运行 `mint dev` 命令。
|
||
</Accordion>
|
||
|
||
<Accordion title="更改未在线上站点生效">
|
||
部署可能需要几分钟时间。请检查你的 GitHub Actions（适用于基于代码的工作流）或 Mintlify 控制台中的部署日志，以确保没有构建错误。
|
||
</Accordion>
|
||
|
||
<Accordion title="自定义域名无法连接">
|
||
请确认你的 DNS 记录配置正确，并预留足够的 DNS 传播时间（最长可达 48 小时）。你可以使用 [DNSChecker](https://dnschecker.org) 等工具来验证你的 CNAME 记录。
|
||
</Accordion>
|
||
</AccordionGroup> |