多源部署

将多个 git 仓库的文档汇入一个 Mintlify 部署，每个源挂载在各自的路径下。

将多个 git 仓库连接到同一个 Mintlify 部署。每个仓库称为一个 源，提供自己的 docs.json 和内容，Mintlify 在构建时将它们合并为一个站点。当相关产品的文档位于不同仓库中，但需要在同一个域名和导航树下展示时，可以使用多源部署。

​

源的合并方式

当部署包含多个源时，Mintlify 会在每次构建时拉取每个源的 docs.json，并将其合并为一棵 navigation.products 树：

• 部署中列出的第一个源 是 主源。它的 docs.json 为合并后的站点提供顶层配置，包括 name、theme、colors、logo、favicon、redirects 以及其他所有顶层字段。
• 其他源 仅贡献它们的 navigation。这些配置中的其他顶层字段（例如 redirects 或 theme）将被忽略，并在构建时记录一条警告，列出被忽略的键。
• 每个源的 navigation 都会成为合并后的 navigation.products 数组中的一项。该产品的显示名称为源的标签，若未设置标签，则使用其 docs.json 中的 name。

合并后的结果等价于一个使用 products 作为顶层导航划分的 docs.json。

源自身的 docs.json 不能使用 navigation.products。products 仅存在于合并后的顶层，因此每个源必须使用非 product 的导航形式（例如 groups、tabs、versions 或 anchors）。

​

挂载路径

多源部署中的每个源都必须设置一个非空的 挂载路径。挂载路径是该源内容所提供服务的 URL 前缀，合并时会被添加到该源 docs.json 中的每个引用前：

• pages、root 和 href 字段中的页面路径。例如，挂载在 eng 的源中的 quickstart 会解析为 eng/quickstart。
• openapi 和 asyncapi 字段中的 OpenAPI 与 AsyncAPI 引用，包括 source 和 directory 属性。
• 全局导航条目（如 anchors 和 tabs）中的 href 值。

绝对 URL（https://…）和页面内锚点（#section）保持不变。同一部署中各源的挂载路径不能重叠。

最终上线站点中的 URL 会包含挂载路径。在挂载于 eng 的源中作为 quickstart.mdx 编写的页面，访问地址为 /eng/quickstart。

​

示例

一个包含两个源（分别挂载在 platform 和 eng）的部署，会生成如下合并配置：

主源 docs.json（挂载于 platform）：

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": { "primary": "#0D9373" },
  "favicon": "/favicon.svg",
  "redirects": [{ "source": "/old", "destination": "/new" }],
  "navigation": {
    "groups": [
      { "group": "Get started", "pages": ["index", "setup"] }
    ]
  }
}

第二个源 docs.json（挂载于 eng）：

{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Engineering",
  "navigation": {
    "groups": [
      { "group": "Guides", "pages": ["quickstart"] }
    ]
  }
}

Mintlify 实际构建并提供服务的合并配置：

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": { "primary": "#0D9373" },
  "favicon": "/favicon.svg",
  "redirects": [{ "source": "/old", "destination": "/new" }],
  "navigation": {
    "products": [
      {
        "product": "Platform",
        "groups": [
          { "group": "Get started", "pages": ["platform/index", "platform/setup"] }
        ]
      },
      {
        "product": "Engineering",
        "groups": [
          { "group": "Guides", "pages": ["eng/quickstart"] }
        ]
      }
    ]
  }
}

​

构建失败

在以下情况下，构建将失败，部署不会被更新：

• 任一源缺少 docs.json，或源的 docs.json 无效。
• 任一源的挂载路径为空。
• 两个源的挂载路径相互重叠。
• 某个源的 navigation 在顶层使用了 products。

构建错误信息会指出导致失败的源，便于你在对应的仓库中进行修复。

​

相关内容

• Monorepo 设置 — 将单个源指向大型仓库中的子目录。
• Products — 多源部署所生成的导航划分形式。