Multi-source docs
Multi-source docs
Let multiple teams publish to the same docs site from their own repositories.
Multi-source docs
This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.
Multi-source documentation publishes a single docs site to a custom domain, split into multiple sub-paths. Each sub-path is sourced from its own repository, so teams ship updates independently while a shared global theme keeps branding consistent across the site.
Each repository declares a unique basepath under the shared domain in its docs.yml. Running fern generate --docs from that repository updates only its sub-path — every other sub-path stays untouched.
Three pieces of configuration make this work:
multi-source: true set on the instance in each repository’s docs.yml, with url and custom-domain ending in the same basepath.docs.yml.For example, NVIDIA’s docs are split across multiple independent repositories, each publishing to its own sub-path on docs.nvidia.com:
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), and any combination of sub-paths works, including just two.
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:
See 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:
global-theme: my-org-theme.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:
Each repository publishes independently:
Only the sub-path owned by that repository is updated. Every other sub-path is unaffected.
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:
/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)./subpath only return results from /subpath and below. Use when each sub-path covers a distinct product and users expect scoped results.
Browse the live site at multi-source.docs.buildwithfern.com and the source at fern-api/docs-examples/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:
The unit is one fern/ folder per sub-path, not one repository per sub-path. A repo-per-sub-path layout (often one per team) is the most common shape, but multiple fern/ folders in a single repo work too.
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.
The homepage home.mdx can use cards to direct users to each team’s docs:
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 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 for the full list of fields.