Multi-repository deployments

Combine multiple Git repositories into one Mintlify site, with a dedicated URL path for each source repo’s content and navigation.

Multi-repository deployments are available on Enterprise plans.

Use a multi-repository deployment when one site needs content from more than one Git repository. When you configure multiple repositories as sources for the same Mintlify project, content from each repository has its own URL path.

For example, you can combine separate repositories for product documentation, API reference, and SDK guides into one site:

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

How multi-repository deployments work

Each repository in a multi-repository deployment has its own:

• Git provider connection
• Branch
• Optional content directory
• URL path
• docs.json

During deployment, Mintlify reads each repository and combines the configured sources into one site. Each source appears under its configured URL path.

One repository acts as the base source for the deployment. Its docs.json is the root docs.json and controls site-level configuration, including theme, colors, logo, site name, top-level navigation, integrations, SEO, and other top-level fields. Every other source contributes only its own navigation and content under its configured URL path. The first repository you configure is the base source by default, and you can change which source is the base at any time.

Multi-repository deployments are different from a monorepo setup. Use a monorepo setup when you store all content in a subdirectory alongside source code in a single repository. Use multi-repository deployments when you store content across separate repositories.

Requirements

• An Enterprise plan
• Admin access to your Mintlify project
• A docs.json file in each repository source
• All repository sources must use the same Git provider (all GitHub or all GitLab). Adding a source from a different provider removes all existing sources of the other type

URL paths must be unique and cannot overlap. For example, do not configure one source at /docs and another source at /docs/api.

Configure multiple repositories

1. Open Git settings

   Navigate to Git settings in your dashboard.

   
2. Add another repository

   Click Add repository.

3. Configure the repository source

   Select the repository, branch, and any required Git provider-specific fields (GitHub or GitLab).

   

   For GitHub sources, the Mintlify GitHub App must have access to the repository. For GitLab sources, provide the project ID and a deploy token with read_repository scope.

   If the repository’s docs.json is in a subdirectory rather than the root, enable docs.json is in a subdirectory and enter the path to that directory.

4. Set the URL path

   Enter a URL path for the repository source.

   The URL path determines where the content from that repository appears on your docs site. For example, a URL path of api serves the content under docs.example.com/api.

   You can enter the path with or without leading slashes. Mintlify normalizes the value when you save.

5. Save changes

   Click Save changes. Mintlify saves the configuration and queues a deployment of the combined site.

Change the base source

The base source provides the site-wide configuration for your multi-repository deployment. Change the base source when you want a different repository’s docs.json to control settings like theme, colors, site name, and top-level navigation.

1. Open Git settings

   Navigate to Git settings in your dashboard.

   The current base source shows a Base badge next to the repository name.

2. Set a new base source

   On the repository you want to use as the base, click Set as base.

   Mintlify updates the base source immediately and queues a deployment using the new base repository’s docs.json for site-level configuration.

Changing the base source replaces site-level settings such as theme, colors, logo, site name, and top-level navigation with the values from the new base repository’s docs.json. URL paths and content from other sources are unaffected.

Example repository layout

In this example, each source has its own repository and its own 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/

Configure each repository with a URL path:

Repository	URL path	Published path
acme/product-docs	product	/product
acme/api-docs	api	/api
acme/sdk-docs	sdks	/sdks

Navigation behavior

Mintlify combines the navigation from each repository into one site navigation. Each repository source becomes a top-level product section under the configured URL path.

The name of each product section comes from the name field in the corresponding repository’s docs.json. For example, if a repository’s docs.json sets "name": "API Reference", its product section appears as “API Reference” in the combined navigation.

Keep each source’s navigation scoped to that repository. For example, pages in the API repository should reference only files that live in the API repository, and pages in the SDK repository should reference only files that live in the SDK repository.

Nested navigation.products configurations are not supported inside individual source repositories.

Reference navigation from another source

By default, Mintlify wraps each repository’s navigation into a top-level product section. If you want more control over where another source’s navigation appears, use a sourceRef entry in the base source’s docs.json to inline the navigation from another repository at a specific location.

Use sourceRef when you want to:

• Show multiple repositories under a single set of tabs instead of separate product sections.
• Place a repository’s navigation inside a specific group, tab, or global anchor.
• Combine content from multiple repositories in a single navigation structure.

How sourceRef works

Add a sourceRef entry to a navigation array in the base source’s docs.json. The value must be the owner/repo identifier of another repository source in the deployment.

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

The comparison is case-insensitive and leading or trailing slashes are ignored. The value must be exactly two segments (owner/repo); other formats fail the merge.

When Mintlify builds the combined navigation, it replaces each sourceRef entry with the matching navigation array from the referenced repository’s docs.json. The key of the parent array determines which array Mintlify reads from the referenced source. For example, a sourceRef inside a tabs array is replaced by the tabs array from the referenced source’s docs.json.

sourceRef is supported inside any navigation array, including tabs, groups, pages, products, and arrays under navigation.global.

Mintlify prefixes every path from the referenced source with that source’s URL path, so pages resolve to the correct location without extra configuration.

Example

In this example, the base source (owned by acme at repository docs) is served at /docs and shows a Guides tab. The sourceRef inlines the tabs from a second source (acme/api-docs) configured at /api.

Base source docs.json:

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

Referenced source docs.json at URL path api:

{
  "navigation": {
    "tabs": [
      { "tab": "API", "pages": ["reference/introduction"] }
    ]
  }
}

After the deployment builds, the combined navigation looks like:

{
  "navigation": {
    "tabs": [
      { "tab": "Guides", "pages": ["docs/quickstart"] },
      { "tab": "API", "pages": ["api/reference/introduction"] }
    ]
  }
}

Requirements and limitations

• sourceRef values must use the owner/repo format and match a repository source configured in the same deployment.
• The referenced source must define a navigation array under the same key as the parent array. For example, a sourceRef inside tabs requires the referenced source to define navigation.tabs.
• Two repository sources in the same deployment cannot share the same owner/repo. If they do, sourceRef cannot resolve unambiguously and the merge fails.
• sourceRef entries cannot form a cycle. A source cannot reference itself, and two sources cannot reference each other.
• sourceRef must appear inside a navigation array. It is not valid at the top level of navigation.

Removing a repository source

You can remove a repository source from the Git settings page in your dashboard. When only one repository source remains, Mintlify removes the source URL path and treats the remaining repository as the root source for the deployment.