Multi-source docs

Create a control repository for the global theme

The control repository is a dedicated Fern project that holds your global theme — the shared logo, colors, fonts, layout, and site-level settings that every source repository inherits. Define those settings in its docs.yml, then export and upload the theme:

$
fern docs theme export
$
fern docs theme upload --name my-org-theme

See Global themes for the full setup guide and the list of fields the theme controls.

Configure each repository

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:

1
global-theme: my-org-theme
2
3
instances:
4
  - url: example.docs.buildwithfern.com/product-a
5
    custom-domain: docs.example.com/product-a
6
    multi-source: true

Publish from each repository

Each repository publishes independently:

$
fern generate --docs

Only the sub-path owned by that repository is updated. Every other sub-path is unaffected.

Configure domain settings in the Dashboard

Open the Fern Dashboard 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.

Configure the following:

• 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 and search work across sub-paths. Two modes are available:
  • Hierarchical — searches under /subpath only return results from /subpath and below. Use 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 when the sub-paths are parts of a single product and users benefit from cross-cutting results.