> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ficcaurora.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Mintlify - 自动托管的文档平台

## 应用总览

<Tabs>
  <Tab title="定位与价值">
    技术文档的撰写和维护往往令开发团队头疼：传统文档工具要么配置繁琐、要么界面陈旧，更新流程复杂且耗时。开发者需要在编写代码和维护文档之间不断切换，导致文档质量参差不齐，最终影响用户体验和产品采用率。
    **Mintlify 是一个专为开发者设计的智能文档平台**，采用 Markdown
    驱动、开箱即用的现代化设计。它的核心价值在于：让开发团队能够在几分钟内部署一个美观、专业的文档网站，并通过
    Git 工作流无缝集成到现有开发流程中。无需学习复杂的 CMS 系统，也不需要前端设计技能，只需用熟悉的
    Markdown 编写内容即可。
  </Tab>

  <Tab title="用户与场景">
    Mintlify 主要面向 **SaaS 公司、开源项目和 API 产品团队**。 **典型使用场景包括**：

    <ul>
      <li>为新产品快速搭建产品文档网站</li>
      <li>为开源项目创建易于维护的贡献指南和 API 参考</li>
      <li>为技术团队建立内部知识库</li>
    </ul>

    **工作原理**：你在 GitHub 仓库中用 Markdown 编写文档，通过简单的 JSON
    配置文件定义导航结构，Mintlify
    会自动将其渲染为一个响应式、搜索友好的现代化文档网站，并在每次代码推送时自动更新。
  </Tab>

  <Tab title="对比与权衡">
    与 GitBook、Docusaurus 等工具相比，Mintlify 的核心优势在于 **零配置启动** 和 **设计精美**。

    <ul>
      <li>**vs GitBook**：GitBook 需要付费才能使用自定义域名和高级功能</li>
      <li>**vs Docusaurus**：Docusaurus 虽然功能强大但需要深入了解 React 和复杂的配置</li>
      <li>**Mintlify 优势**：提供开箱即用的专业设计、内置 AI 搜索能力以及即时部署</li>
    </ul>

    **需要注意的局限性**：

    <ul>
      <li>作为托管服务，自定义程度不如自托管方案灵活</li>
      <li>免费版有一定使用限制</li>
    </ul>

    对于需要极致定制或完全控制的团队，Docusaurus
    可能更合适；但对于希望快速上线、专注内容而非技术细节的团队，Mintlify 是理想选择。
  </Tab>
</Tabs>

## 安装准备

<Steps>
  <Step title="检查系统要求">
    在开始之前，确保你的系统满足以下条件：

    <ul>
      <li>**Node.js**: 18.0 或更高版本</li>
      <li>**npm**: 9.0 或更高版本</li>
      <li>**Git**: 用于版本控制和部署</li>
      <li>**GitHub 账号**: 用于托管文档仓库和自动部署</li>
    </ul>
  </Step>

  <Step title="安装 Mintlify CLI">
    Mintlify CLI 是本地预览和开发文档的命令行工具。打开终端，运行以下命令： `bash npm install -g
            mintlify ` **验证安装是否成功**： `bash mintlify --version ` 如果显示版本号（如
    `v4.x.x`），说明安装成功。
  </Step>
</Steps>

## 快速上手

<Steps>
  <Step title="注册账号并初始化项目">
    <ol>
      <li>访问 [Mintlify 官网](https://mintlify.com/start)，点击「Start for Free」创建账号</li>
      <li>完成简短的引导流程后，Mintlify 会自动为你创建一个演示文档站点</li>
      <li>你将获得一个临时 URL，格式为：`https://<your-project-name>.mintlify.app`</li>
    </ol>

    **预期结果**：在浏览器中打开该 URL，你会看到一个包含示例内容的文档网站。
  </Step>

  <Step title="使用 GitHub 模板创建文档仓库">
    <ol>
      <li>访问 [Mintlify Starter 仓库](https://github.com/mintlify/starter)</li>
      <li>点击绿色的「Use this template」按钮</li>
      <li>填写你的仓库名称（如 `my-docs`），选择公开或私有</li>
      <li>点击「Create repository」</li>
    </ol>

    **作用说明**：这个模板包含了完整的文档结构示例，包括配置文件、导航设置和示例页面，可以直接在此基础上修改。
  </Step>

  <Step title="克隆仓库并启动本地预览">
    在终端中执行以下命令：

    ```bash theme={null}
    # 克隆你的仓库（替换为你的仓库地址）
    git clone https://github.com/your-username/my-docs.git
    # 进入项目目录
    cd my-docs
    # 启动本地预览服务器
    mintlify dev
    ```

    **预期结果**：终端显示 `✓ Ready on http://localhost:3000`，浏览器自动打开本地预览页面。
  </Step>

  <Step title="修改内容并查看实时变化">
    <ol>
      <li>用你喜欢的代码编辑器（如 VS Code）打开项目文件夹</li>
      <li>找到 `index.mdx` 文件，这是首页内容</li>
      <li>将文件顶部的 `title` 字段改为「Hello World」</li>
    </ol>

    ```mdx theme={null}
    ---
    title: 'Hello World'
    description: '欢迎来到我的文档站点'
    ---
    ## 这是我的第一个 Mintlify 文档！
    你可以在这里编写任何内容...
    ```

    保存文件后，查看浏览器中的实时更新（无需刷新）。
    **作用说明**：Mintlify CLI 提供热重载功能，每次保存文件后，浏览器会自动更新内容，让你立即看到修改效果。
  </Step>

  <Step title="连接 GitHub 并自动部署">
    <ol>
      <li>登录 [Mintlify Dashboard](https://dashboard.mintlify.com)</li>
      <li>进入「Settings」→「GitHub」，点击「Install GitHub App」</li>
      <li>授权 Mintlify 访问你刚创建的文档仓库</li>
      <li>回到本地项目，提交并推送你的修改</li>
    </ol>

    ```bash theme={null}
    git add .
    git commit -m "Update homepage title"
    git push origin main
    ```

    **预期结果**：几秒钟后，访问你的 `<your-project-name>.mintlify.app` URL，会看到线上网站已自动更新。
  </Step>
</Steps>

## 核心功能说明

<Columns>
  <Card title="Markdown 驱动的内容编辑" icon="markdown">
    Mintlify 使用增强版 Markdown（MDX），支持标准 Markdown 语法加上交互式组件。你可以像写普通文档一样编写内容，同时插入代码块、提示框、选项卡等丰富元素。
    **示例**：
    <Tip>这是一个提示框，用于突出重要信息</Tip>

    <CodeGroup>
      ```bash npm theme={null}
      npm install package-name
      ```

      ```bash yarn theme={null}
      yarn add package-name
      ```
    </CodeGroup>
  </Card>

  <Card title="配置文件驱动的导航结构" icon="list">
    项目根目录的 `mint.json` 文件控制整个网站的外观和导航。你可以定义侧边栏分组、顶部导航、品牌颜色等，无需编写任何前端代码。
    **关键配置示例**：

    ```json theme={null}
    {
      "name": "我的产品文档",
      "navigation": [
        {
          "group": "快速开始",
          "pages": ["index", "quickstart"]
        },
        {
          "group": "API 参考",
          "pages": ["api/authentication", "api/endpoints"]
        }
      ]
    }
    ```
  </Card>

  <Card title="Git 工作流自动部署" icon="git-branch">
    一旦连接 GitHub App，任何推送到默认分支（通常是 `main`）的改动都会自动触发部署。这意味着团队成员可以通过熟悉的 Pull Request 流程协作编写文档，合并后立即上线。
    **优势**：

    <ul>
      <li>无需手动部署操作</li>
      <li>支持团队协作和代码审查</li>
      <li>版本控制和回滚能力</li>
      <li>自动化的 CI/CD 流程</li>
    </ul>
  </Card>
</Columns>

## 参考资源

<Columns>
  <Card title="官方文档" icon="book" href="https://mintlify.com/docs">
    涵盖所有高级功能、配置选项和 API 集成指南的权威参考
  </Card>

  <Card title="GitHub 仓库" icon="github" href="https://github.com/mintlify/starter">
    官方提供的起始模板，包含各种组件使用示例和最佳实践
  </Card>

  <Card title="视频教程" icon="play" href="https://www.youtube.com/results?search_query=mintlify+tutorial">
    社区创作的视频教程，适合视觉学习者快速了解操作流程
  </Card>

  <Card title="Discord 社区" icon="message-circle" href="https://mintlify.com/community">
    加入官方 Discord 频道，与其他用户交流经验并获得团队支持
  </Card>
</Columns>

## 下一步建议

完成快速上手后，你可以：

* **自定义外观**：在 `mint.json` 中修改品牌颜色、logo 和 favicon
* **添加更多页面**：创建新的 `.mdx` 文件并更新导航配置
* **集成 API 文档**：使用 OpenAPI/Swagger 规范自动生成 API 参考页面
* **设置自定义域名**：在 Dashboard 中绑定你自己的域名（如 `docs.yourcompany.com`）
  祝你使用愉快！