多仓库部署

当一个站点需要来自多个 Git 仓库的内容时，请使用多仓库部署。当你为同一个 Mintlify 项目配置多个仓库作为源时，每个仓库的内容都会有自己的 URL 路径。

例如，你可以将产品文档、API 参考和 SDK 指南的独立仓库合并到一个站点中：

docs.example.com/product
docs.example.com/api
docs.example.com/sdks

多仓库部署中可以有一个源使用根 URL 路径（/）。来自该源的内容会在站点根路径下提供，不带任何路径前缀，而其他源则在各自配置的 URL 路径下提供。当一个仓库存放主文档、其他仓库添加 API 参考或 SDK 指南等分区时，这一点非常有用。

多仓库部署中的每个仓库都有各自的：

• Git 提供方连接
• 分支
• 可选的内容目录
• URL 路径
• docs.json

在部署期间，Mintlify 会读取每个仓库并将已配置的源合并到一个站点中。每个源会显示在其配置的 URL 路径下。

其中一个仓库作为部署的基础源。其 docs.json 是根 docs.json，控制站点级配置，包括主题、颜色、Logo、站点名称、顶层导航、集成、SEO 以及其他顶层字段。其他每个源仅在其配置的 URL 路径下贡献各自的导航和内容。你配置的第一个仓库默认就是基础源，你可以随时更改作为基础的源。

• 企业版套餐
• 你的 Mintlify 项目的管理员权限
• 每个源仓库中都必须有 docs.json 文件
• 所有源仓库必须使用相同的 Git 提供方（全部为 GitHub 或全部为 GitLab）。添加来自不同提供方的源会移除所有现有的另一类型的源

打开 Git 设置

在仪表板中前往 Git 设置。

添加另一个仓库

点击 Add repository。

配置仓库源

选择仓库、分支以及所需的 Git 提供方特定字段（GitHub 或 GitLab）。

对于 GitHub 源，Mintlify GitHub App 必须能够访问该仓库。对于 GitLab 源，请提供项目 ID 以及具有 read_repository 权限的部署令牌。

如果仓库的 docs.json 位于子目录而非根目录中，请启用 docs.json is in a subdirectory 并输入指向该目录的路径。

设置 URL 路径

为仓库源输入一个 URL path。

URL 路径决定了来自该仓库的内容在你的文档站点中显示的位置。例如，URL 路径为 api 时，内容会在 docs.example.com/api 下提供。

若要让某个源在站点的根路径下提供内容且不带任何路径前缀，请将 URL 路径留空或将其设置为 /。每个部署中只能有一个源使用根 URL 路径。

你可以使用或不使用前导斜杠输入路径。Mintlify 在保存时会自动规范化该值。

保存更改

点击 Save changes。Mintlify 会保存配置，并将合并后的站点的部署排入队列。

基础源为你的多仓库部署提供站点级配置。当你希望由另一个仓库的 docs.json 控制主题、颜色、站点名称和顶层导航等设置时，请更改基础源。

在此示例中，每个源都有自己的仓库以及自己的 docs.json。

acme/product-docs
├── docs.json
├── overview.mdx
└── guides/

acme/api-docs
├── docs.json
├── introduction.mdx
└── reference/

acme/sdk-docs
├── docs.json
├── quickstart.mdx
└── javascript/

为每个仓库配置一个 URL 路径：

Mintlify 会将每个仓库的导航合并到一个站点导航中。每个仓库源都会成为配置的 URL 路径下的一个顶级产品分区。

每个产品分区的名称来自对应仓库的 docs.json 中的 name 字段。例如，如果某个仓库的 docs.json 设置了 "name": "API Reference"，则其产品分区会在合并后的导航中显示为 “API Reference”。

请将每个源的导航限定在其自身的仓库范围内。例如，API 仓库中的页面应仅引用位于 API 仓库中的文件。同样地，SDK 仓库中的页面应仅引用位于 SDK 仓库中的文件。

源仓库内部不支持嵌套的 navigation.products 配置。

相对 Markdown 链接无法跨仓库解析，因为每个源在构建时只能看到自身的文件。要从某个源链接到另一个源中的页面，请使用包含目标源 URL 路径的根相对 URL 路径：

See the [API reference](/api/reference/authentication) for details.

在此示例中，/api 是为 API 仓库源配置的 URL 路径。该链接会在已发布站点层面解析为 docs.example.com/api/reference/authentication。

不要对内部跨源链接使用完整的 https:// URL — 根相对路径可保证预览和自定义域名正常工作。

当某个源使用根 URL 路径时，其页面可能会与另一个源中的页面产生相同的最终 URL。如果两个源生成了相同的页面路径，Mintlify 会从 URL 路径更具体的源提供该页面，并在部署更新中记录一条冲突警告。为避免冲突，请勿让根源中的文件名与其他源配置的 URL 路径重叠。

使用 sourceRef 可将另一个仓库的导航放置到基础源 docs.json 中的特定位置。如果未使用 sourceRef，Mintlify 会将每个仓库作为独立的顶层产品分区添加。

• 被引用的仓库必须已配置为同一多仓库部署中的源。
• sourceRef 的值必须使用 owner/repo 格式。不支持仅使用挂载路径或仓库名称。
• 被引用的源必须定义与主源相似的导航结构。例如，在 anchors 中使用 sourceRef 时，被引用的源必须定义 navigation.anchors。
• sourceRef 条目不能形成循环。源不能引用自身，两个源也不能相互引用。
• sourceRef 必须出现在导航数组中。它在 navigation 的顶层无效。

在基础源的 docs.json 的导航数组中添加一个 sourceRef 条目。其值必须是仓库的 owner/repo 标识符。

{ "sourceRef": "acme/api-docs" }

Mintlify 支持在 anchors、tabs、groups、pages、products 以及 navigation.global 下的数组中使用 sourceRef。其他导航结构（包括标签页内的 menu 条目）不支持 sourceRef。

例如，若要将多个仓库的 anchors 合并到单个 anchor 导航中：

{
  "navigation": {
    "anchors": [
      {
        "anchor": "Guides",
        "pages": ["quickstart"]
      },
      {
        "sourceRef": "acme/api-docs"
      }
    ]
  }
}

如果 acme/api-docs 定义了自己的 navigation.anchors，Mintlify 会用这些 anchors 替换 sourceRef 条目，并在其路径前加上被引用源的 URL 路径前缀。

你可以从仪表板的 Git 设置页面移除仓库源。当只剩一个仓库源时，Mintlify 会移除该源的 URL 路径，并将剩余的仓库作为部署的根源。