安装 CLI - Mintlify
前提条件
克隆你的存储库
运行以下命令来安装 CLI：
本地预览
请进入你的文档目录（docs.json 文件所在的位置），然后运行：
可以在 http://localhost:3000 本地预览文档。
或者，如果你不想全局安装命令行界面（CLI），可以运行一次性脚本：
自定义端口
默认情况下，命令行界面（CLI）使用端口 3000。你可以使用 --port 选项来自定义端口。比如，要在 3333 端口上运行 CLI，请使用以下命令：
如果你尝试在已被占用的端口上运行，命令行界面（CLI）会改用下一个可用端口：
跳过 OpenAPI 处理
如果你有大量 OpenAPI 文件，可以在本地开发时使用 --disable-openapi 参数跳过对 OpenAPI 文件的处理，从而提升性能：
mint dev --disable-openapi
以特定组预览
如果你使用基于分组的访问控制来限制对文档的访问，可以通过 --groups [groupname] 标志，以特定认证组的身份进行预览。
例如，如果你有一个名为 admin 的组，可以使用以下命令以该组成员的身份进行预览：
创建新项目
要创建一个新的文档项目，请运行以下命令：
此命令会将入门套件克隆到指定目录。若未指定目录，命令行界面（CLI）工具会提示你创建新的子目录或覆盖当前目录。
CLI 工具会提示你输入项目名称和主题，以完成项目设置。
标志
| 标志 | 说明 | 是否必填 |
|---|---|---|
--name | 设置新项目的名称。 | 是 |
--theme | 设置新项目的主题。 | 是 |
--force | 在不提示的情况下覆盖当前目录，即使其中包含现有文件。 | 否 |
在非交互式环境（例如 CI/CD 流水线或使用 AI 编码代理工具）中运行 mint new 时，必须提供所有必填标志（--name 和 --theme）。
更新命令行界面（CLI）
如果本地预览与线上生产环境中的内容不一致，请更新你的本地 CLI：
如果本地版本中没有提供 mint update 命令，请使用最新版本重新安装命令行界面（CLI）：
附加命令
查找损坏链接
使用以下命令检查并识别所有损坏的内部链接：
该命令会忽略与 .mintignore 模式相匹配的文件。若要同时检查类似 /path/to/page#anchor 的锚点链接，请使用 --check-anchors 标志：
mint broken-links --check-anchors
查找无障碍问题
使用以下命令测试颜色对比度比例，并在文档中查找图像和视频缺失的 alt 文本：
使用标志检查特定的无障碍问题。
# Check only for missing alt text
mint a11y --skip-contrast
# 仅检查颜色对比度问题
mint a11y --skip-alt-text
验证文档构建
在严格模式下验证你的文档构建；如果存在任何警告或错误，则会以错误状态退出。在 CI/CD 流水线中使用此命令，以防止有问题的文档被部署。
使用标志配置验证命令。
--groups [groupname]：为验证模拟用户组（在测试基于用户组的访问控制时很有用）--disable-openapi：在验证过程中禁用 OpenAPI 文件生成
检查 OpenAPI 规范
使用以下命令检查你的 OpenAPI 文件是否存在错误：
mint openapi-check <OpenAPI 文件名或 URL>
传入文件名（例如 ./openapi.yaml）或 URL（例如 https://petstore3.swagger.io/api/v3/openapi.json）。
重命名文件
使用以下命令重命名文件并更新所有对它们的引用：
mint rename <旧文件名路径> <新文件名路径>
迁移 MDX 端点页面
使用以下命令，将 MDX 端点页面迁移为基于你的 OpenAPI 规范自动生成的页面：
此命令会将单个 MDX 端点页面转换为在你的 docs.json 中定义的自动生成页面，将 MDX 内容移至 OpenAPI 规范中的 x-mint 扩展，并更新你的导航。详见 从 MDX 迁移 获取详细信息。
格式化
在本地开发时，我们建议在你的 IDE 中安装相关扩展/插件，以便识别并格式化 MDX 文件。 如果你使用 Cursor、Windsurf 或 VS Code，我们推荐使用 MDX VS Code extension 进行语法高亮显示，并使用 Prettier 进行代码格式化。 如果你使用 JetBrains，我们推荐安装 MDX IntelliJ IDEA plugin 以实现语法高亮显示，并配置 Prettier 进行代码格式化。