diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index b098b66..9d7cbff 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -12,7 +12,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- project: [docs-starter, i18n, versioning]
+ project: [docs-starter, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
steps:
- name: Checkout repository
uses: actions/checkout@v4
diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml
index ca6fc1e..939aee3 100644
--- a/.github/workflows/preview-docs.yml
+++ b/.github/workflows/preview-docs.yml
@@ -11,7 +11,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- project: [docs-starter, i18n, versioning]
+ project: [docs-starter, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
steps:
- name: Checkout repository
uses: actions/checkout@v4
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index 75d1b59..a5588f5 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -12,7 +12,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- project: [docs-starter, i18n, versioning]
+ project: [docs-starter, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning]
steps:
- name: Checkout repository
uses: actions/checkout@v4
diff --git a/README.md b/README.md
index fe50428..485fef1 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ Example Fern docs projects. Each top-level folder is a self-contained example wi
| --- | --- | --- |
| [`docs-starter`](./docs-starter) | Minimal starter project | [docs-starter.docs.buildwithfern.com](https://docs-starter.docs.buildwithfern.com) |
| [`i18n`](./i18n) | Multi-language docs with English + Japanese translations | [i18n.docs.buildwithfern.com](https://i18n.docs.buildwithfern.com) |
+| [`multi-source`](./multi-source) | Multi-source docs — six independent projects publishing to one domain with global theme, nested sub-paths, and shared branding | [multi-source.docs.buildwithfern.com](https://multi-source.docs.buildwithfern.com) |
| [`versioning`](./docs-versioned) | Versioned site with a version dropdown and a shared page | [versioning.docs.buildwithfern.com](https://versioning.docs.buildwithfern.com) |
## Use an example
diff --git a/multi-source/greenhouses/fern/assets/logo-dark.svg b/multi-source/greenhouses/fern/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/greenhouses/fern/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/greenhouses/fern/assets/logo-light.svg b/multi-source/greenhouses/fern/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/greenhouses/fern/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/greenhouses/fern/docs.yml b/multi-source/greenhouses/fern/docs.yml
new file mode 100644
index 0000000..a33c12f
--- /dev/null
+++ b/multi-source/greenhouses/fern/docs.yml
@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
+
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/greenhouses
+ multi-source: true
+
+title: Greenhouses
+
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+
+navigation:
+ - section: Theming
+ contents:
+ - page: Unified theming
+ path: ./pages/overview.mdx
+ - page: Theme configuration
+ path: ./pages/climate-control.mdx
diff --git a/multi-source/greenhouses/fern/fern.config.json b/multi-source/greenhouses/fern/fern.config.json
new file mode 100644
index 0000000..3635565
--- /dev/null
+++ b/multi-source/greenhouses/fern/fern.config.json
@@ -0,0 +1,4 @@
+{
+ "organization": "fern-docs-examples",
+ "version": "5.3.0"
+}
diff --git a/multi-source/greenhouses/fern/pages/climate-control.mdx b/multi-source/greenhouses/fern/pages/climate-control.mdx
new file mode 100644
index 0000000..ddfa3e3
--- /dev/null
+++ b/multi-source/greenhouses/fern/pages/climate-control.mdx
@@ -0,0 +1,59 @@
+---
+title: Theme configuration
+subtitle: The full theme.yml that powers this site.
+---
+
+When you run `fern docs theme export`, the CLI extracts theme-eligible fields from your `docs.yml` into a `theme.yml` file. Here's the complete theme used by all six sites on this domain.
+
+## theme.yml
+
+```yaml
+colors:
+ accent-primary:
+ dark: '#70E155'
+ light: '#1B4332'
+ background:
+ dark: '#1A1A17'
+ light: '#F5F0E8'
+ border:
+ dark: '#3A3A30'
+ light: '#D4C9B5'
+ sidebar-background:
+ dark: '#1F1F1B'
+ light: '#F0EBE1'
+ header-background:
+ dark: '#1A1A17'
+ light: '#F5F0E8'
+ card-background:
+ dark: '#252520'
+ light: '#EDE8DC'
+css: ./assets/styles.css
+logo:
+ href: /
+ dark: ./assets/logo-dark.svg
+ light: ./assets/logo-light.svg
+ height: 28
+ right-text: Multi-Source Docs
+```
+
+## Upload workflow
+
+
+
+
+Set colors and CSS in the project that will own the theme (typically the homepage or a shared config project).
+
+
+
+Run `fern docs theme export` to extract theme-eligible fields into a `theme/` directory.
+
+
+
+Run `fern docs theme upload --name plantstore-theme` to save it under a name your org can reference.
+
+
+
+Each sub-site adds `global-theme: plantstore-theme` to their `docs.yml`. The CLI fetches and applies it at publish time.
+
+
+
diff --git a/multi-source/greenhouses/fern/pages/overview.mdx b/multi-source/greenhouses/fern/pages/overview.mdx
new file mode 100644
index 0000000..5807e67
--- /dev/null
+++ b/multi-source/greenhouses/fern/pages/overview.mdx
@@ -0,0 +1,45 @@
+---
+title: Unified theming
+subtitle: Consistent branding across independent sites.
+---
+
+This Greenhouses site looks the same as every other site on this domain — same colors, same card styles, same typography. That's the `global-theme` at work.
+
+## One theme, six sites
+
+All sites reference the same theme with a single line in their `docs.yml`:
+
+```yaml
+global-theme: plantstore-theme
+```
+
+The theme is [defined in the homepage project](https://github.com/fern-api/docs-examples/tree/main/multi-source/homepage/fern) and uploaded to Fern's registry. When any site publishes, the CLI fetches the theme and merges it with the local config.
+
+## The color palette
+
+| Token | Light | Dark |
+| --- | --- | --- |
+| Background | `#F5F0E8` (light tan) | `#1A1A17` |
+| Accent | `#1B4332` (forest green) | `#70E155` |
+| Border | `#D4C9B5` | `#3A3A30` |
+| Sidebar | `#F0EBE1` | `#1F1F1B` |
+| Card | `#EDE8DC` | `#252520` |
+
+## Custom CSS
+
+The theme also includes a `styles.css` with subtle refinements:
+
+```css
+/* Card hover lift effect */
+.fern-card {
+ transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+.fern-card:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+```
+
+
+Toggle dark mode to see both color schemes in action. The theme defines separate values for light and dark modes.
+
diff --git a/multi-source/homepage/fern/assets/logo-dark.svg b/multi-source/homepage/fern/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/homepage/fern/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/homepage/fern/assets/logo-light.svg b/multi-source/homepage/fern/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/homepage/fern/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/homepage/fern/docs.yml b/multi-source/homepage/fern/docs.yml
new file mode 100644
index 0000000..791b6f0
--- /dev/null
+++ b/multi-source/homepage/fern/docs.yml
@@ -0,0 +1,32 @@
+# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
+
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com
+ multi-source: true
+
+title: Multi-Source Docs
+
+navbar-links:
+ - type: minimal
+ text: Seeds
+ href: /seeds
+ - type: minimal
+ text: Greenhouses
+ href: /greenhouses
+ - type: minimal
+ text: Nursery
+ href: /nursery
+
+navigation:
+ - page: Home
+ path: ./pages/home.mdx
+ - section: Teams
+ contents:
+ - link: Seeds
+ href: /seeds
+ - link: Greenhouses
+ href: /greenhouses
+ - link: Nursery
+ href: /nursery
diff --git a/multi-source/homepage/fern/fern.config.json b/multi-source/homepage/fern/fern.config.json
new file mode 100644
index 0000000..3635565
--- /dev/null
+++ b/multi-source/homepage/fern/fern.config.json
@@ -0,0 +1,4 @@
+{
+ "organization": "fern-docs-examples",
+ "version": "5.3.0"
+}
diff --git a/multi-source/homepage/fern/pages/home.mdx b/multi-source/homepage/fern/pages/home.mdx
new file mode 100644
index 0000000..190b75b
--- /dev/null
+++ b/multi-source/homepage/fern/pages/home.mdx
@@ -0,0 +1,53 @@
+---
+title: Multi-Source Docs
+subtitle: A live example of Fern's multi-source documentation.
+---
+
+This site is built from [six independent projects](https://github.com/fern-api/docs-examples/tree/main/multi-source) — in the common case, each one is a team — publishing to different sub-paths on the same domain. Every team owns their own `fern/` directory and deploys independently.
+
+
+```
+multi-source.docs.buildwithfern.com
+├── / ← homepage (this page)
+├── /seeds ← Seeds team hub
+│ ├── /seeds/sunflower ← Sunflower sub-team
+│ └── /seeds/tomato ← Tomato sub-team
+├── /greenhouses ← Greenhouses team
+└── /nursery ← Nursery team
+```
+
+
+Search and Ask AI are scoped to the current source and any sources deeper in the path. For example, searching from `/seeds` returns results from `/seeds`, `/seeds/sunflower`, and `/seeds/tomato` — but not from `/greenhouses` or `/nursery`. Try it: navigate to [Seeds](/seeds) and open the search bar.
+
+
+
+ A hub with nested sub-children at `/seeds/sunflower` and `/seeds/tomato`.
+
+
+ Unified theming via `global-theme` — shared colors, CSS, and typography.
+
+
+ Independent publishing — each team deploys on their own schedule.
+
+
+
+## How it works
+
+Each sub-site is a separate `fern/` project with its own `docs.yml`. The key setting is `multi-source: true` on the instance:
+
+```yaml
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds
+ multi-source: true
+```
+
+All six projects share a `global-theme` for consistent branding — colors, CSS, and typography are defined once and [uploaded to the registry](https://github.com/fern-api/docs-examples/tree/main/multi-source/homepage/fern).
+
+## What's in this example
+
+- **Multi-source publishing** — every sub-path is a separate project that publishes independently
+- **Nested sub-children** — [/seeds](/seeds) acts as a hub for [/seeds/sunflower](/seeds/sunflower) and [/seeds/tomato](/seeds/tomato)
+- **Global theme** — shared colors and CSS across all six sites ([source](https://github.com/fern-api/docs-examples/tree/main/multi-source/homepage/fern))
+- **Per-site navbar** — each site defines its own header links
+- **Hierarchical search** — results scope to the current sub-path and its children
+- **Independent deploys** — teams publish without affecting each other
diff --git a/multi-source/homepage/fern/styles.css b/multi-source/homepage/fern/styles.css
new file mode 100644
index 0000000..0a4b33e
--- /dev/null
+++ b/multi-source/homepage/fern/styles.css
@@ -0,0 +1,42 @@
+/* Multi-Source Docs — shared minimalist theme */
+
+:root,
+.light {
+ --background: #F5F0E8;
+ --card-background: #EDE8DC;
+ --sidebar-background: #F0EBE1;
+ --header-background: #F5F0E8;
+ --border: #D4C9B5;
+}
+
+.dark {
+ --background: #1A1A17;
+ --card-background: #252520;
+ --sidebar-background: #1F1F1B;
+ --header-background: #1A1A17;
+ --border: #3A3A30;
+}
+
+/* Typography */
+.fern-page-heading {
+ letter-spacing: -0.03em;
+}
+
+/* Sidebar refinements */
+.fern-sidebar {
+ font-size: 0.875rem;
+}
+
+/* Card hover lift */
+.fern-card {
+ transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.fern-card:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+
+.dark .fern-card:hover {
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+}
diff --git a/multi-source/homepage/fern/theme/assets/logo-dark.svg b/multi-source/homepage/fern/theme/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/homepage/fern/theme/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/homepage/fern/theme/assets/logo-light.svg b/multi-source/homepage/fern/theme/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/homepage/fern/theme/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/homepage/fern/theme/assets/styles.css b/multi-source/homepage/fern/theme/assets/styles.css
new file mode 100644
index 0000000..0a4b33e
--- /dev/null
+++ b/multi-source/homepage/fern/theme/assets/styles.css
@@ -0,0 +1,42 @@
+/* Multi-Source Docs — shared minimalist theme */
+
+:root,
+.light {
+ --background: #F5F0E8;
+ --card-background: #EDE8DC;
+ --sidebar-background: #F0EBE1;
+ --header-background: #F5F0E8;
+ --border: #D4C9B5;
+}
+
+.dark {
+ --background: #1A1A17;
+ --card-background: #252520;
+ --sidebar-background: #1F1F1B;
+ --header-background: #1A1A17;
+ --border: #3A3A30;
+}
+
+/* Typography */
+.fern-page-heading {
+ letter-spacing: -0.03em;
+}
+
+/* Sidebar refinements */
+.fern-sidebar {
+ font-size: 0.875rem;
+}
+
+/* Card hover lift */
+.fern-card {
+ transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+.fern-card:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+
+.dark .fern-card:hover {
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+}
diff --git a/multi-source/homepage/fern/theme/theme.yml b/multi-source/homepage/fern/theme/theme.yml
new file mode 100644
index 0000000..503557d
--- /dev/null
+++ b/multi-source/homepage/fern/theme/theme.yml
@@ -0,0 +1,26 @@
+colors:
+ accent-primary:
+ dark: '#70E155'
+ light: '#1B4332'
+ background:
+ dark: '#1A1A17'
+ light: '#F5F0E8'
+ border:
+ dark: '#3A3A30'
+ light: '#D4C9B5'
+ sidebar-background:
+ dark: '#1F1F1B'
+ light: '#F0EBE1'
+ header-background:
+ dark: '#1A1A17'
+ light: '#F5F0E8'
+ card-background:
+ dark: '#252520'
+ light: '#EDE8DC'
+css: ./assets/styles.css
+logo:
+ href: /
+ dark: ./assets/logo-dark.svg
+ light: ./assets/logo-light.svg
+ height: 28
+ right-text: Multi-Source Docs
diff --git a/multi-source/nursery/fern/assets/logo-dark.svg b/multi-source/nursery/fern/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/nursery/fern/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/nursery/fern/assets/logo-light.svg b/multi-source/nursery/fern/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/nursery/fern/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/nursery/fern/docs.yml b/multi-source/nursery/fern/docs.yml
new file mode 100644
index 0000000..abe651e
--- /dev/null
+++ b/multi-source/nursery/fern/docs.yml
@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
+
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/nursery
+ multi-source: true
+
+title: Nursery
+
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+
+navigation:
+ - section: Publishing
+ contents:
+ - page: Independent publishing
+ path: ./pages/overview.mdx
+ - page: CI/CD setup
+ path: ./pages/propagation.mdx
diff --git a/multi-source/nursery/fern/fern.config.json b/multi-source/nursery/fern/fern.config.json
new file mode 100644
index 0000000..3635565
--- /dev/null
+++ b/multi-source/nursery/fern/fern.config.json
@@ -0,0 +1,4 @@
+{
+ "organization": "fern-docs-examples",
+ "version": "5.3.0"
+}
diff --git a/multi-source/nursery/fern/pages/overview.mdx b/multi-source/nursery/fern/pages/overview.mdx
new file mode 100644
index 0000000..afaf2be
--- /dev/null
+++ b/multi-source/nursery/fern/pages/overview.mdx
@@ -0,0 +1,36 @@
+---
+title: Independent publishing
+subtitle: Each team deploys on their own schedule.
+---
+
+This Nursery site is published independently from the other five sites on this domain. The Seeds team can ship updates without waiting on Nursery, and vice versa.
+
+## How multi-source publishing works
+
+Each sub-site is a separate `fern/` project with its own `fern.config.json` and `docs.yml`. Publishing one site doesn't affect the others:
+
+```bash
+# Publish only the Nursery site
+cd multi-source/nursery
+fern generate --docs
+```
+
+The other five sites remain unchanged. This is the key benefit of multi-source — teams don't block each other.
+
+## Project structure
+
+```
+multi-source/
+├── homepage/fern/ # publishes to /
+├── seeds/fern/ # publishes to /seeds
+├── seeds-sunflower/fern/ # publishes to /seeds/sunflower
+├── seeds-tomato/fern/ # publishes to /seeds/tomato
+├── greenhouses/fern/ # publishes to /greenhouses
+└── nursery/fern/ # publishes to /nursery (this site)
+```
+
+Each directory is self-contained with its own pages, assets, and configuration. The only shared element is the `global-theme` name — and even that is fetched from the registry at publish time, not from a local file.
+
+
+View the full source for all six projects on [GitHub](https://github.com/fern-api/docs-examples/tree/main/multi-source).
+
diff --git a/multi-source/nursery/fern/pages/propagation.mdx b/multi-source/nursery/fern/pages/propagation.mdx
new file mode 100644
index 0000000..f26f69d
--- /dev/null
+++ b/multi-source/nursery/fern/pages/propagation.mdx
@@ -0,0 +1,41 @@
+---
+title: CI/CD setup
+subtitle: Automated publishing with GitHub Actions.
+---
+
+Each sub-site can be published through CI/CD. This example uses a GitHub Actions matrix to check and publish all six projects.
+
+## Workflow matrix
+
+The `publish-docs.yml` workflow runs `fern generate --docs` for each project in the matrix:
+
+```yaml
+strategy:
+ matrix:
+ project:
+ - multi-source/homepage
+ - multi-source/seeds
+ - multi-source/seeds-sunflower
+ - multi-source/seeds-tomato
+ - multi-source/greenhouses
+ - multi-source/nursery
+```
+
+Each matrix entry runs independently. If one site fails to publish, the others still succeed.
+
+## Selective publishing
+
+In a real setup, you might want to publish only the sites that changed. You can use path filters in your workflow:
+
+```yaml
+on:
+ push:
+ paths:
+ - 'multi-source/nursery/**'
+```
+
+This way, changes to the Nursery project only trigger a Nursery publish — the other five sites are unaffected.
+
+## Preview deployments
+
+The `preview-docs.yml` workflow generates preview URLs for pull requests, letting teams review changes before they go live. Each project in the matrix gets its own preview.
diff --git a/multi-source/seeds-sunflower/fern/assets/logo-dark.svg b/multi-source/seeds-sunflower/fern/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/seeds-sunflower/fern/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/seeds-sunflower/fern/assets/logo-light.svg b/multi-source/seeds-sunflower/fern/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/seeds-sunflower/fern/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/seeds-sunflower/fern/docs.yml b/multi-source/seeds-sunflower/fern/docs.yml
new file mode 100644
index 0000000..572ed12
--- /dev/null
+++ b/multi-source/seeds-sunflower/fern/docs.yml
@@ -0,0 +1,25 @@
+# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
+
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds/sunflower
+ multi-source: true
+
+title: Sunflower
+
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+ - type: minimal
+ text: Seeds
+ href: /seeds
+
+navigation:
+ - section: Sub-site config
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+ - page: Per-site navbar
+ path: ./pages/planting.mdx
diff --git a/multi-source/seeds-sunflower/fern/fern.config.json b/multi-source/seeds-sunflower/fern/fern.config.json
new file mode 100644
index 0000000..3635565
--- /dev/null
+++ b/multi-source/seeds-sunflower/fern/fern.config.json
@@ -0,0 +1,4 @@
+{
+ "organization": "fern-docs-examples",
+ "version": "5.3.0"
+}
diff --git a/multi-source/seeds-sunflower/fern/pages/overview.mdx b/multi-source/seeds-sunflower/fern/pages/overview.mdx
new file mode 100644
index 0000000..9769d8e
--- /dev/null
+++ b/multi-source/seeds-sunflower/fern/pages/overview.mdx
@@ -0,0 +1,36 @@
+---
+title: Sunflower sub-site
+subtitle: How simple a sub-site's docs.yml can be.
+---
+
+This is a sub-child site at `/seeds/sunflower`. Its entire configuration fits in a few lines — the `global-theme` handles all the branding, including the logo.
+
+## The complete docs.yml
+
+```yaml
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds/sunflower
+ multi-source: true
+
+title: Sunflower
+
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+ - type: minimal
+ text: Seeds
+ href: /seeds
+
+navigation:
+ - section: Sunflower seeds
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+ - page: Planting guide
+ path: ./pages/planting.mdx
+```
+
+That's it. The theme provides colors, CSS, and the logo. The local config only needs navbar links and page navigation. Each team manages their own pages and a minimal `docs.yml`.
diff --git a/multi-source/seeds-sunflower/fern/pages/planting.mdx b/multi-source/seeds-sunflower/fern/pages/planting.mdx
new file mode 100644
index 0000000..123bfca
--- /dev/null
+++ b/multi-source/seeds-sunflower/fern/pages/planting.mdx
@@ -0,0 +1,38 @@
+---
+title: Per-site navbar
+subtitle: Each sub-site controls its own header links.
+---
+
+Every sub-site in a multi-source setup defines its own `navbar-links`. This lets each team customize the header navigation for their audience.
+
+## Navbar links by site
+
+| Site | Header shows | Links to |
+| --- | --- | --- |
+| Homepage (`/`) | Multi-Source Docs | Seeds, Greenhouses, Nursery |
+| Seeds (`/seeds`) | Multi-Source Docs | Home, Sunflower, Tomato |
+| Sunflower (`/seeds/sunflower`) | Multi-Source Docs | Home, Seeds |
+| Tomato (`/seeds/tomato`) | Multi-Source Docs | Home, Seeds |
+| Greenhouses (`/greenhouses`) | Multi-Source Docs | Home |
+| Nursery (`/nursery`) | Multi-Source Docs | Home |
+
+## How it's configured
+
+Each site sets `navbar-links` in its own `docs.yml`:
+
+```yaml
+# On this Sunflower sub-site
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+ - type: minimal
+ text: Seeds
+ href: /seeds
+```
+
+The logo and `right-text` come from the global theme, so all sites show the same "Multi-Source Docs" branding automatically.
+
+
+Navbar links are **not** inherited from the global theme. They must be set per-site so each team can link to what matters for their users.
+
diff --git a/multi-source/seeds-tomato/fern/assets/logo-dark.svg b/multi-source/seeds-tomato/fern/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/seeds-tomato/fern/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/seeds-tomato/fern/assets/logo-light.svg b/multi-source/seeds-tomato/fern/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/seeds-tomato/fern/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/seeds-tomato/fern/docs.yml b/multi-source/seeds-tomato/fern/docs.yml
new file mode 100644
index 0000000..85af01f
--- /dev/null
+++ b/multi-source/seeds-tomato/fern/docs.yml
@@ -0,0 +1,25 @@
+# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
+
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds/tomato
+ multi-source: true
+
+title: Tomato
+
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+ - type: minimal
+ text: Seeds
+ href: /seeds
+
+navigation:
+ - section: Global theme
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+ - page: Theme merging
+ path: ./pages/transplanting.mdx
diff --git a/multi-source/seeds-tomato/fern/fern.config.json b/multi-source/seeds-tomato/fern/fern.config.json
new file mode 100644
index 0000000..3635565
--- /dev/null
+++ b/multi-source/seeds-tomato/fern/fern.config.json
@@ -0,0 +1,4 @@
+{
+ "organization": "fern-docs-examples",
+ "version": "5.3.0"
+}
diff --git a/multi-source/seeds-tomato/fern/pages/overview.mdx b/multi-source/seeds-tomato/fern/pages/overview.mdx
new file mode 100644
index 0000000..a684e26
--- /dev/null
+++ b/multi-source/seeds-tomato/fern/pages/overview.mdx
@@ -0,0 +1,38 @@
+---
+title: Global theme
+subtitle: How the shared theme is created and uploaded.
+---
+
+All six sites on this domain share a `global-theme` called `plantstore-theme`. It's defined once in the homepage project and uploaded to Fern's registry.
+
+## Uploading the theme
+
+The theme is exported from the homepage's `docs.yml` and uploaded with two commands:
+
+```bash
+# Export theme-eligible fields (colors, CSS) to a theme directory
+fern docs theme export
+
+# Upload to the registry with a name
+fern docs theme upload --name plantstore-theme
+```
+
+Every other site references it with a single line:
+
+```yaml
+global-theme: plantstore-theme
+```
+
+## What the theme includes
+
+The `plantstore-theme` provides:
+
+- **Colors** — light tan background (`#F5F0E8`), dark forest green accents (`#1B4332`), with dark mode variants
+- **CSS** — custom styles for card hover effects, sidebar typography, and heading letter-spacing
+- **Logo** — the shared leaf icon and "Multi-Source Docs" text
+
+The theme does **not** include navbar-links — those are set per-site so each team can customize their header navigation.
+
+
+View the full theme source in the [homepage project on GitHub](https://github.com/fern-api/docs-examples/tree/main/multi-source/homepage/fern).
+
diff --git a/multi-source/seeds-tomato/fern/pages/transplanting.mdx b/multi-source/seeds-tomato/fern/pages/transplanting.mdx
new file mode 100644
index 0000000..566566f
--- /dev/null
+++ b/multi-source/seeds-tomato/fern/pages/transplanting.mdx
@@ -0,0 +1,32 @@
+---
+title: Theme merging
+subtitle: How global theme fields merge with local config.
+---
+
+When a site uses `global-theme`, Fern merges the theme's fields into the local `docs.yml` at publish time. Understanding the merge behavior helps you decide what to put in the theme vs. what to keep local.
+
+## Merge rules
+
+| Field | Behavior |
+| --- | --- |
+| `colors` | Theme provides defaults; local values override per-key |
+| `css` | Theme CSS is applied; local CSS is appended after |
+| `logo` | Theme provides the default; local `logo` overrides it entirely |
+| `navbar-links` | Local links replace the theme's links entirely |
+| `navigation` | Always local — the theme never provides navigation |
+
+## Practical split
+
+For this example site, the split is:
+
+**In the theme** (shared by all six sites):
+- Color palette (background, accent, border, sidebar, header, card)
+- Custom CSS (card hover effects, sidebar font size, heading letter-spacing)
+- Logo (leaf icon + "Multi-Source Docs" text)
+
+**In each site's local config** (unique per team):
+- Navbar links (Home, parent site, sibling sites)
+- Navigation structure (pages and sections)
+- Title
+
+This split keeps branding consistent while letting each team own their content structure.
diff --git a/multi-source/seeds/fern/assets/logo-dark.svg b/multi-source/seeds/fern/assets/logo-dark.svg
new file mode 100644
index 0000000..7ca0e5e
--- /dev/null
+++ b/multi-source/seeds/fern/assets/logo-dark.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/seeds/fern/assets/logo-light.svg b/multi-source/seeds/fern/assets/logo-light.svg
new file mode 100644
index 0000000..356f3ae
--- /dev/null
+++ b/multi-source/seeds/fern/assets/logo-light.svg
@@ -0,0 +1,3 @@
+
diff --git a/multi-source/seeds/fern/docs.yml b/multi-source/seeds/fern/docs.yml
new file mode 100644
index 0000000..6d44d32
--- /dev/null
+++ b/multi-source/seeds/fern/docs.yml
@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json
+
+global-theme: plantstore-theme
+
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds
+ multi-source: true
+
+title: Seeds
+
+navbar-links:
+ - type: minimal
+ text: Home
+ href: /
+ - type: minimal
+ text: Sunflower
+ href: /seeds/sunflower
+ - type: minimal
+ text: Tomato
+ href: /seeds/tomato
+
+navigation:
+ - section: Nested multi-source
+ contents:
+ - page: Overview
+ path: ./pages/overview.mdx
+ - page: Search and Ask AI
+ path: ./pages/catalog.mdx
diff --git a/multi-source/seeds/fern/fern.config.json b/multi-source/seeds/fern/fern.config.json
new file mode 100644
index 0000000..3635565
--- /dev/null
+++ b/multi-source/seeds/fern/fern.config.json
@@ -0,0 +1,4 @@
+{
+ "organization": "fern-docs-examples",
+ "version": "5.3.0"
+}
diff --git a/multi-source/seeds/fern/pages/catalog.mdx b/multi-source/seeds/fern/pages/catalog.mdx
new file mode 100644
index 0000000..f6d78c3
--- /dev/null
+++ b/multi-source/seeds/fern/pages/catalog.mdx
@@ -0,0 +1,32 @@
+---
+title: Search and Ask AI
+subtitle: How search scopes hierarchically by sub-path.
+---
+
+Multi-source sites use **hierarchical search scoping**. When you search from a sub-path, results are filtered to content within that path and its children.
+
+## Try it yourself
+
+
+
+
+Go to [the homepage](/) and open the search bar. You'll see results from all six sub-sites — Seeds, Greenhouses, Nursery, and the nested Sunflower and Tomato sites.
+
+
+
+Now try the search bar on this page. Results are scoped to `/seeds` and its children (`/seeds/sunflower`, `/seeds/tomato`). You won't see Greenhouse or Nursery content.
+
+
+
+Navigate to [Sunflower](/seeds/sunflower) and search again. Results narrow further to only Sunflower content.
+
+
+
+
+## Ask AI works the same way
+
+The Ask AI feature follows the same hierarchical scoping. Ask a question from `/seeds` and the AI draws only from Seeds, Sunflower, and Tomato content. Ask from the homepage and it has access to everything.
+
+
+Search scoping is configured via `hierarchical` mode in the basepath settings. This is the default for multi-source sites.
+
diff --git a/multi-source/seeds/fern/pages/overview.mdx b/multi-source/seeds/fern/pages/overview.mdx
new file mode 100644
index 0000000..8e4de6e
--- /dev/null
+++ b/multi-source/seeds/fern/pages/overview.mdx
@@ -0,0 +1,38 @@
+---
+title: Seeds
+subtitle: A hub site with nested sub-children.
+---
+
+This site demonstrates **nested multi-source** — a parent hub at `/seeds` with two child sites at `/seeds/sunflower` and `/seeds/tomato`. Each is a separate `fern/` project that publishes independently.
+
+
+
+ A sub-child site at `/seeds/sunflower` with its own pages and navbar links.
+
+
+ Another sub-child at `/seeds/tomato` showing the global theme upload process.
+
+
+
+## How nested sub-children work
+
+The Seeds hub publishes to `/seeds`, while its children publish to deeper paths:
+
+```yaml
+# seeds/fern/docs.yml (this site)
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds
+ multi-source: true
+
+# seeds-sunflower/fern/docs.yml
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds/sunflower
+ multi-source: true
+
+# seeds-tomato/fern/docs.yml
+instances:
+ - url: multi-source.docs.buildwithfern.com/seeds/tomato
+ multi-source: true
+```
+
+Each project is fully independent — different teams can own different sub-paths and deploy on their own schedule.