Skip to content

Document variable merging in multi-repository deployments #6994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yangleyland merged 2 commits into from
Aug 17, 2026
Merged

Document variable merging in multi-repository deployments #6994

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
17c9c5b
Document variable merging in multi-repository deployments
yangleyland Aug 17, 2026
68f1b5c
Apply suggestions from code review
ethanpalm Aug 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion deploy/multi-repo.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Each repository in a multi-repository deployment has its own:

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](#change-the-base-source) at any time.
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 its own navigation and content under its configured URL path, plus any [variables](#variables-across-sources) that the base source doesn't define. The first repository you configure is the base source by default, and you can [change which source is the base](#change-the-base-source) at any time.

<Note>
Multi-repository deployments are different from a [monorepo setup](/deploy/monorepo). 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.
Expand Down Expand Up @@ -174,6 +174,15 @@ Do not use full `https://` URLs for internal cross-source links. Root-relative p

When one source uses the root URL path, its pages can share the same final URL as pages in another source. If two sources produce the same page path, Mintlify serves the page from the source with the more specific URL path and logs a conflict warning in the deployment update. To avoid conflicts, keep filenames in the root source from overlapping with URL paths configured for other sources.

## Variables across sources

Mintlify merges the [`variables`](/organize/settings-reference#variables) defined in each source repository's `docs.json` into one set for the deployed site. Pages in any source can reference any merged variable with `{{variableName}}` syntax.

When more than one source defines the same variable key:

- The base source's value always takes precedence.
- If two non-base sources define the same key with different values and the base source doesn't define it, Mintlify uses the value from the source configured first and logs a warning in the deployment to update the conflicting names in the non-base sources.

## Reference navigation from another source

Use `sourceRef` to place another repository's navigation at a specific location in the base source's `docs.json`. If you don't use `sourceRef`, Mintlify adds each repository as a separate top-level product section.
Expand Down