Versions
Add a dropdown version selector for multiple doc versions
This feature is available only for the Team and Enterprise plans. To get started, reach out to support@buildwithfern.com.
Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can also share content.
For displaying version-specific content within a single page, use the <Versions> component. You can use site-wide versioning and the <Versions> component independently or together.
Create a versions folder inside of your fern folder. To specify the contents of each version, add a .yml file to the versions folder to define the navigational structure of that version. Make sure to include the navigation and tabs properties, if applicable.
Version-specific yml files:
Define a version in the top-level docs.yml by adding an item to the versions list and specifying the display-name and path.
Versions appear in a dropdown on your site in the order listed in docs.yml. The first version in your versions list is the default version and uses unversioned paths like example.com/getting-started. Other versions use versioned paths like example.com/v2/getting-started.
Fern automatically handles version routing by redirecting broken versioned links to the default version. Canonical URLs point to the unversioned path to consolidate SEO signals. To override this for version-specific pages, see SEO metadata.
You can optionally set the availability status for each version. Options are deprecated, ga, stable, and beta.
Version availability is distinct from section and page availability, with different options. If you want to set section and page availability, do so in your version-specific yml files.
These optional settings let you control how versions appear in URLs and who can access them.
By default, Fern generates URL slugs from the display-name by converting it to lowercase and replacing spaces with hyphens. For example, a version with display-name: v3 (Deprecated) would get the slug v-3-deprecated in the URL path.
To customize the URL slug for a version, use the slug property:
In this example, setting slug: v3 produces URLs like /docs/v3/getting-started.
Control which versions appear in each documentation instance by tagging them with audiences. This enables separate sites for different user groups (e.g., internal developers, beta testers, public customers).
Content is filtered based on audience tags:
Define audiences for instances and versions in docs.yml:
To conditionally render content within a page based on the current version, use the <If> component.
Search results can be scoped to the reader’s current version — either boosted in ranking or filtered by default — through the settings.search object in docs.yml.
Use custom CSS to style the version selector to match your brand.
You can directly customize the appearance of the version selector by targeting the fern-version-selector CSS class.
Adjusting positioning:
Use transform: translateY(Npx) to adjust the vertical positioning of the selectors. This ensures that the selectors match the line height of your logo for better visual alignment.
Enhancing visual prominence: You can modify the border radius and add borders to make the selectors more prominent and better integrated with your site’s design aesthetic.
The dropdown menu for the version selector can be customized using the fern-version-selector-radio-group CSS class.
