Versioning | Fern Documentation

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.

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

Add versions to your docs

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:

1 navigation: 
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. For more information on setting up multiple products, follow our product switching docs.

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

1 versions: 
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 the version dropdown in the order listed in versions. The first version in your versions list is your default version. This version uses unversioned paths like /docs/getting-started, while other versions use versioned paths like /docs/getting-started/v2.

Fern automatically handles version routing by redirecting broken versioned links to the default version and managing canonical URLs.

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

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

Customize version selector styling

You can directly customize the appearance of the version selector by targeting the fern-version-selector CSS class.

Common styling adjustments

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 }

The dropdown menu for the version selector can be customized using the fern-version-selector-radio-group CSS class.