Add multi-source docs example

.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

.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

.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

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

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

multi-source/greenhouses/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+  "organization": "fern-docs-examples",
+  "version": "5.3.0"
+}

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
+
+<Steps>
+
+<Step title="Define branding in your docs.yml">
+Set colors and CSS in the project that will own the theme (typically the homepage or a shared config project).
+</Step>
+
+<Step title="Export the theme">
+Run `fern docs theme export` to extract theme-eligible fields into a `theme/` directory.
+</Step>
+
+<Step title="Upload to the registry">
+Run `fern docs theme upload --name plantstore-theme` to save it under a name your org can reference.
+</Step>
+
+<Step title="Reference from other sites">
+Each sub-site adds `global-theme: plantstore-theme` to their `docs.yml`. The CLI fetches and applies it at publish time.
+</Step>
+
+</Steps>

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);
+}
+```
+
+<Tip>
+Toggle dark mode to see both color schemes in action. The theme defines separate values for light and dark modes.
+</Tip>

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

multi-source/homepage/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+  "organization": "fern-docs-examples",
+  "version": "5.3.0"
+}

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.
+
+<Accordion title="Project structure">
+```
+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
+```
+</Accordion>
+
+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.
+
+<CardGroup>
+  <Card title="Seeds" icon="fa-regular fa-seedling" href="/seeds">
+    A hub with nested sub-children at `/seeds/sunflower` and `/seeds/tomato`.
+  </Card>
+  <Card title="Greenhouses" icon="fa-regular fa-warehouse" href="/greenhouses">
+    Unified theming via `global-theme` — shared colors, CSS, and typography.
+  </Card>
+  <Card title="Nursery" icon="fa-regular fa-leaf" href="/nursery">
+    Independent publishing — each team deploys on their own schedule.
+  </Card>
+</CardGroup>
+
+## 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

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);
+}

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);
+}

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