From 17c9c5b3a30b8af380174d52cc3e3f71ccdd4b4e Mon Sep 17 00:00:00 2001 From: Leyland Yang Date: Mon, 17 Aug 2026 08:13:31 -0700 Subject: [PATCH 1/2] Document variable merging in multi-repository deployments --- deploy/multi-repo.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/deploy/multi-repo.mdx b/deploy/multi-repo.mdx index 7a02b6883..ed4d1412f 100644 --- a/deploy/multi-repo.mdx +++ b/deploy/multi-repo.mdx @@ -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. 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. @@ -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 wins. +- 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 update that names the conflicting repositories. + ## 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. From 68f1b5c2c9adada5a7d896c1fe405eca2a5bbc94 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 17 Aug 2026 09:48:34 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- deploy/multi-repo.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy/multi-repo.mdx b/deploy/multi-repo.mdx index ed4d1412f..8283493a6 100644 --- a/deploy/multi-repo.mdx +++ b/deploy/multi-repo.mdx @@ -180,8 +180,8 @@ Mintlify merges the [`variables`](/organize/settings-reference#variables) define When more than one source defines the same variable key: -- The base source's value always wins. -- 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 update that names the conflicting repositories. +- 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