Configuration

Versioning

Learn how to add versioning to your Fern documentation. Configure multiple doc versions, customize version selectors, and manage version-specific content.

View as Markdown

Versioning is available on all plans: up to 3 versions on Basic, 10 versions on Pro, or unlimited on Enterprise. Contact support@buildwithfern.com for more information.

A dropdown of the available versions

Each version of your docs can contain its own distinct tabs, sections, pages, and API references. Versions can share content, as well.

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.

Add versions to your docs

1

Define your versions

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.

$fern/
>  ├─ fern.config.json
>  ├─ generators.yml
>  ├─ docs.yml
>  ├─ pages/
>    ├─ ...
>  └─ versions/
>    ├─ latest/pages/...
>    ├─ latest.yml
>    ├─ v2/pages/...
>    └─ v2.yml

Version-specific yml files:

1navigation: 
2  - section: Introduction
3    contents: 
4      - page: My Page
5        path: ./latest/pages/my-page.mdx  # relative path to the file
6      - page: Shared Resource
7        path: ../shared-pages/shared-resource.mdx
8  - api: API Reference
You can also have multiple products, some versioned and some unversioned.
2

Add your version configuration

Define a version in the top-level docs.yml by adding an item to the versions list and specifying the display-name and path.

docs.yml
1versions: 
2  - display-name: Latest          # shown in the dropdown
3    path: ./versions/latest.yml   # relative path to the version file
4  - display-name: V2
5    path: ./versions/v2.yml
Default versions

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.

3

Indicate availability

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.

docs.yml
1versions: 
2  - display-name: Latest          
3    path: ./versions/latest.yml   
4    availability: beta
5  - display-name: v2
6    path: ./versions/v2.yml
7    availability: stable
4

Remove extra navigation from docs.yml

If your docs.yml file includes a navigation field or a tabs field, be sure to remove. Those fields should now belong in the version-specific .yml files.

Customize version behavior

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:

docs.yml
1versions:
2  - display-name: v4 (Latest)
3    path: ./versions/latest.yml
4    availability: stable
5  - display-name: v3 (Deprecated)
6    path: ./versions/v3.yml
7    slug: v3
8    availability: deprecated
9  - display-name: v2
10    path: ./versions/v2.yml
11    slug: v2
12    availability: deprecated

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:

  • Match: Content with an audience matching the instance audience is included
  • No match: Content with a non-matching audience is excluded
  • No audience: Content without an audience tag is included by default

Define audiences for instances and versions in docs.yml:

docs.yml
1instances:
2  - url: internal.docs.buildwithfern.com
3    audiences:
4      - internal # Only shows content tagged with 'internal'
5  - url: public.docs.buildwithfern.com
6    audiences:
7      - public # Only shows content tagged with 'public'
8versions:
9  - display-name: v3
10    path: ./versions/v3.yml
11    audiences:
12      - public # This version only appears on the public instance
13  - display-name: v2 (Internal)
14    path: ./versions/v2.yml
15    audiences:
16      - internal # This version only appears on the internal instance

You can hide specific versions from navigation, search, and indexing while keeping them accessible via direct URL by setting hidden: true. This is useful for deprecating previous versions or maintaining internal-only versions without removing them entirely.

docs.yml
1versions:
2  - display-name: v3
3    path: ./versions/v3.yml
4  - display-name: v2
5    path: ./versions/v2.yml
6  - display-name: v1 (Legacy)
7    path: ./versions/v1.yml
8    hidden: true
The default version (the first version in your versions list) can’t be hidden.

Customize version styling

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.

1.fern-version-selector {
2  transform: translateY(1px);
3  border-radius: 1000px;
4  border: 1px solid var(--border);
5}