diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml
index a94479cf2..826be4a4c 100644
--- a/fern/products/docs/docs.yml
+++ b/fern/products/docs/docs.yml
@@ -245,6 +245,8 @@ navigation:
path: ./pages/preview-publish/publishing-your-docs.mdx
- page: Setting up your domain
path: ./pages/preview-publish/setting-up-your-domain.mdx
+ - page: Multi-source docs
+ path: ./pages/preview-publish/multi-source.mdx
- section: Customization
collapsed: true
contents:
diff --git a/fern/products/docs/pages/changelog/2026-04-30.mdx b/fern/products/docs/pages/changelog/2026-04-30.mdx
new file mode 100644
index 000000000..a744aaaaa
--- /dev/null
+++ b/fern/products/docs/pages/changelog/2026-04-30.mdx
@@ -0,0 +1,20 @@
+---
+tags: ["configuration"]
+---
+
+## Multi-source docs
+
+Multi-source docs lets each team publish independently to a shared custom domain — for example, [docs.nvidia.com](https://docs.nvidia.com) spans sub-paths like `/nvcf`, `/brev`, and `/aiperf`, each owned by a different product team and repository.
+
+Set `multi-source: true` on the instance and reference a [global theme](/learn/docs/customization/global-themes) for consistent branding across repositories.
+
+```yaml docs.yml
+global-theme: my-org-theme
+
+instances:
+ - url: example.docs.buildwithfern.com/product-a
+ custom-domain: docs.example.com/product-a
+ multi-source: true
+```
+
+
diff --git a/fern/products/docs/pages/getting-started/project-structure.mdx b/fern/products/docs/pages/getting-started/project-structure.mdx
index 22619493f..15b8b408c 100644
--- a/fern/products/docs/pages/getting-started/project-structure.mdx
+++ b/fern/products/docs/pages/getting-started/project-structure.mdx
@@ -4,7 +4,7 @@ description: An overview of the file and folder structure of a Fern Docs project
---
-This page provides an overview of the file and folder structure of a Fern Docs project.
+This page provides an overview of the file and folder structure of a Fern Docs project. If you're spreading docs across multiple repositories that publish to the same domain, see [Multi-source docs](/learn/docs/preview-publish/multi-source).
## Directory structure
diff --git a/fern/products/docs/pages/navigation/site-level-settings.mdx b/fern/products/docs/pages/navigation/site-level-settings.mdx
index 6d06e4ade..3fb6ab4fb 100644
--- a/fern/products/docs/pages/navigation/site-level-settings.mdx
+++ b/fern/products/docs/pages/navigation/site-level-settings.mdx
@@ -158,6 +158,10 @@ instances:
You can use audiences to control which versions and products appear in each documentation instance, enabling you to create separate sites for different user groups. Content is included when its audience tag matches the instance audience. Content without an audience tag is included by default. Learn more about configuring instance audiences for [products and/or versions](/docs/configuration/products#add-instance-audiences).
+
+ When `true`, the CLI uses basepath-aware publishing so multiple independent repositories can publish to the same custom domain with different basepaths. The `url` and `custom-domain` must share the same basepath when this is enabled. Learn more about [multi-source docs](/learn/docs/preview-publish/multi-source).
+
+
## Colors configuration
Configure your documentation's color palette for both light and dark modes. Only `accent-primary` is required — all other colors have sensible defaults. These colors are also automatically available as [CSS custom properties](/learn/docs/customization/custom-css-js#built-in-css-color-variables) in your custom stylesheets.
diff --git a/fern/products/docs/pages/preview-publish/images/multi-repo.png b/fern/products/docs/pages/preview-publish/images/multi-repo.png
new file mode 100644
index 000000000..b362d5ff4
Binary files /dev/null and b/fern/products/docs/pages/preview-publish/images/multi-repo.png differ
diff --git a/fern/products/docs/pages/preview-publish/multi-source.mdx b/fern/products/docs/pages/preview-publish/multi-source.mdx
new file mode 100644
index 000000000..545339e46
--- /dev/null
+++ b/fern/products/docs/pages/preview-publish/multi-source.mdx
@@ -0,0 +1,220 @@
+---
+title: Multi-source docs
+subtitle: Let multiple teams publish to the same docs site from their own repositories.
+description: Learn how to set up multi-source documentation so independent teams can publish to shared domains with consistent branding using Fern.
+---
+
+
+
+Multi-source documentation lets multiple teams publish to the same custom domain from independent repositories. Each repository has its own `docs.yml` and content, while a shared [global theme](/learn/docs/customization/global-themes) keeps branding consistent across every sub-path.
+
+## How it works
+
+Each repository owns a unique basepath on the shared domain. Running `fern generate --docs` in one repository updates only its sub-path — every other sub-path is untouched.
+
+Three pieces of configuration make this work:
+
+1. **`multi-source: true`** set on the instance in each repository's `docs.yml`, with `url` and `custom-domain` ending in the same basepath.
+2. **[Global themes](/learn/docs/customization/global-themes)**, referenced by name in each `docs.yml`, deliver shared branding from a central source.
+3. **Multi-repo settings** in the [Fern Dashboard](https://dashboard.buildwithfern.com) control the domain's default path and search/Ask AI scope.
+
+For example, NVIDIA's docs are split across multiple independent repositories, each publishing to its own sub-path on `docs.nvidia.com`:
+
+- [docs.nvidia.com/nvcf](https://docs.nvidia.com/nvcf)
+- [docs.nvidia.com/brev](https://docs.nvidia.com/brev)
+- [docs.nvidia.com/aiperf](https://docs.nvidia.com/aiperf)
+- [docs.nvidia.com/nemo/curator](https://docs.nvidia.com/nemo/curator)
+
+Each sub-path is published independently, but end users see a single unified site. The root `docs.nvidia.com` itself is a separate site outside the Fern setup — multi-source covers only the sub-paths. A Fern-published landing page is optional ([example](#example-a-live-multi-source-site)), and any combination of sub-paths works, including just two.
+
+## Set up multi-source docs
+
+
+
+
+
+The control repository is a dedicated Fern project whose only job is to house your global theme — the shared logo, colors, fonts, layout, and site-level settings that every team repository will inherit. Define those settings in its `docs.yml`, then export and upload the theme:
+
+```bash
+fern docs theme export
+fern docs theme upload --name my-org-theme
+```
+
+See [Global themes](/learn/docs/customization/global-themes) for the full setup guide and the list of fields the theme controls.
+
+
+
+
+
+Each sub-path has its own repository (typically owned by a different team), separate from the control repository in Step 1. In each repository's `docs.yml`:
+
+- Reference the global theme by name: `global-theme: my-org-theme`.
+- Declare an instance with `multi-source: true` and a unique basepath on the shared domain. That basepath must appear at the end of both `url` and `custom-domain`.
+
+For example, here are two repositories on the same shared domain — one at `/product-a`, one at `/product-b`:
+
+
+
+```yaml docs.yml
+global-theme: my-org-theme
+
+instances:
+ - url: example.docs.buildwithfern.com/product-a
+ custom-domain: docs.example.com/product-a
+ multi-source: true
+```
+
+
+```yaml docs.yml
+global-theme: my-org-theme
+
+instances:
+ - url: example.docs.buildwithfern.com/product-b
+ custom-domain: docs.example.com/product-b
+ multi-source: true
+```
+
+
+
+
+
+
+
+Each repository publishes independently:
+
+```bash
+fern generate --docs
+```
+
+Only the sub-path owned by that repository is updated. Every other sub-path is unaffected.
+
+
+
+
+
+Open the [Fern Dashboard](https://dashboard.buildwithfern.com) and select your top-level domain (e.g., `docs.example.com`) — these settings apply to the whole domain, not per sub-path. In the **Settings** tab, navigate to the **Multi-repo settings** card and configure:
+
+- **Default path** *(optional)* — sets where users land when they visit the bare root of your domain. Set this when a Fern-managed page should serve as the root: for example, if your homepage lives at the `/home` sub-path, set the default path to `/home` so `docs.example.com` redirects to `docs.example.com/home`. Skip this if the root isn't Fern-managed, like NVIDIA's `docs.nvidia.com` (a separate marketing site outside the Fern setup).
+- **Search / Ask AI behavior** — controls how [Ask Fern](/learn/docs/ai-features/ask-fern/overview) and search work across sub-paths.
+
+
+
+
+
+Two search modes are available:
+
+- **Hierarchical** — searches under `/subpath` only return results from `/subpath` and below. Use this when each sub-path covers a distinct product and users expect scoped results.
+- **Unified** — searches under any sub-path return results from all sub-paths. Use this when the sub-paths are parts of a single product and users benefit from cross-cutting results.
+
+
+
+
+
+## Example: A live multi-source site
+
+
+Browse the live site at [multi-source.docs.buildwithfern.com](https://multi-source.docs.buildwithfern.com) and the source at [fern-api/docs-examples/multi-source](https://github.com/fern-api/docs-examples/tree/main/multi-source).
+
+
+This is the alternative shape to NVIDIA's setup: a Fern-managed homepage at the bare root, plus team sub-paths underneath. The example uses six independent `fern/` projects on one shared domain — a homepage at `/`, a `/seeds` team hub with two nested sub-children, and standalone `/greenhouses` and `/nursery` teams:
+
+```
+multi-source.docs.buildwithfern.com
+├── / ← homepage
+├── /seeds ← Seeds team hub
+│ ├── /seeds/sunflower ← Sunflower sub-team
+│ └── /seeds/tomato ← Tomato sub-team
+├── /greenhouses ← Greenhouses team
+└── /nursery ← Nursery team
+```
+
+All six projects share `global-theme: plantstore-theme` and set `multi-source: true` — they differ only in their basepath. Sub-paths can themselves contain nested sub-paths: `/seeds/sunflower` and `/seeds/tomato` are independently published projects that live under `/seeds`.
+
+The example uses Fern's preview domain (`*.docs.buildwithfern.com`), so no `custom-domain` is set. A production deployment typically adds `custom-domain: docs.example.com/...` to each instance.
+
+
+
+```yaml homepage/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com
+ multi-source: true
+
+navigation:
+ - page: Home
+ path: ./pages/home.mdx
+```
+
+The homepage `home.mdx` can use cards to direct users to each team's docs:
+
+```jsx home.mdx
+
+
+ A hub with nested sub-children at `/seeds/sunflower` and `/seeds/tomato`.
+
+
+ Climate control and monitoring.
+
+
+ Plant care and propagation.
+
+
+```
+
+
+```yaml seeds/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds
+ multi-source: true
+
+navigation:
+ - section: Getting started
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+```
+
+
+```yaml seeds-sunflower/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds/sunflower
+ multi-source: true
+
+navigation:
+ - section: Getting started
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+```
+
+
+```yaml greenhouses/fern/docs.yml
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/greenhouses
+ multi-source: true
+
+navigation:
+ - section: Getting started
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+```
+
+
+
+## Properties
+
+
+ When `true`, the CLI uses basepath-aware publishing so multiple repositories can coexist under one custom domain. The `url` and `custom-domain` must share the same basepath when this is enabled.
+
+
+
+ The name of a [global theme](/learn/docs/customization/global-themes) to apply. The CLI fetches the named theme from Fern's registry at publish time and merges its branding fields into the local `docs.yml`. See [What the theme controls](/learn/docs/customization/global-themes#what-the-theme-controls) for the full list of fields.
+