多仓库部署

将多个 Git 仓库中的文件合并到一个 Mintlify 站点，并为每个源仓库分配独立的 URL 路径。

多仓库部署在企业版套餐中可用。

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

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

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

​

多仓库部署的工作原理

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

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

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

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

多仓库部署不同于monorepo 配置。当你将所有内容与源代码一起存放在单个仓库的子目录中时，请使用 monorepo 配置。当你将内容分散存放在不同的仓库中时，请使用多仓库部署。

​

要求

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

URL 路径必须唯一且不能重叠。例如，不要同时将一个源配置为 /docs，另一个源配置为 /docs/api。

​

配置多个仓库

1. 打开 Git 设置

   在仪表板中前往 Git 设置。

   
2. 添加另一个仓库

   点击 Add repository。

3. 配置仓库源

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

   

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

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

4. 设置 URL 路径

   为仓库源输入一个 URL path。

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

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

5. 保存更改

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

​

更改基础源

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

1. 打开 Git 设置

   在你的控制台中前往 Git 设置。

   当前的基础源会在仓库名称旁显示 Base 徽章。

2. 设置新的基础源

   在你想用作基础的仓库上，选择 Set as base。

   Mintlify 会立即更新基础源，并使用新基础仓库的 docs.json 作为站点级配置来排队进行一次部署。

更改基础源会用新基础仓库 docs.json 中的值替换站点级设置，例如主题、颜色、Logo、站点名称和顶层导航。其他源的 URL 路径和内容不受影响。

​

示例仓库布局

在此示例中，每个源都有自己的仓库以及自己的 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 路径：

仓库	URL 路径	发布路径
acme/product-docs	product	/product
acme/api-docs	api	/api
acme/sdk-docs	sdks	/sdks

​

导航行为

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 — 根相对路径可保证预览和自定义域名正常工作。

​

从其他源引用导航

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

​

要求

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

​

用法

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

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

sourceRef 支持在 anchors、tabs、groups、pages、products 以及 navigation.global 下的数组中使用。

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

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

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

​

移除仓库源

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