> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Versions

> Configure versioned documentation in Fern, including the version dropdown, per-version navigation, and sharing content across versions.

Versions add a dropdown to your docs for multiple releases of the same content. Each version can contain its own tabs, sections, pages, and API references, and versions can share content.

![A dropdown of the available versions](/learn/_fern-img/c5556f047120033a424c0705520f9e197a925f1e1711fc2527bd94e22c9dde28.webp)

> **Note**
>
> For displaying version-specific content within a single page, use the [`<Versions>` component](/learn/docs/writing-content/components/versions). You can use site-wide versioning and the `<Versions>` component independently or together.

## 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.

```bash {7-11}
fern/
  ├─ fern.config.json
  ├─ generators.yml
  ├─ docs.yml
  ├─ pages/
    ├─ ...
  └─ versions/
    ├─ latest/pages/...
    ├─ latest.yml
    ├─ v2/pages/...
    └─ v2.yml
```

Version-specific `yml` files:

#### latest.yml

```yaml
navigation: 
  - section: Introduction
    contents: 
      - page: My Page
        path: ./latest/pages/my-page.mdx  # relative path to the file
      - page: Shared Resource
        path: ../shared-pages/shared-resource.mdx
  - api: API Reference
```

#### v2.yml

```yaml
tabs: 
  api: 
    title: API Reference
    icon: puzzle
  help:
    title: Help Center
    icon: home
    
 navigation:
  - tab: api
     contents:
        - section: Introduction
           contents: 
              - page: My Page
                path: ./v2/pages/my-page.mdx # relative path to the file
              - page: Shared Resource
                path: ../shared-pages/shared-resource.mdx
        - api: API Reference
   - tab: help
      contents: 
         - section: Help Center
           contents: 
              - page: Contact Us
                 path: contact-us.mdx
```

> **Note**
>
> You can also have [multiple products, some versioned and some unversioned](/learn/docs/configuration/products).

#### 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

```yaml
versions: 
  - display-name: Latest          # shown in the dropdown
    path: ./versions/latest.yml   # relative path to the version file
  - display-name: V2
    path: ./versions/v2.yml
```

`path` points at a version file in your working tree. A version whose content lives at a git [branch, tag, or commit](#build-a-version-from-a-git-ref) can name a `ref` instead.

> **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](/learn/docs/seo/redirects) 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](/learn/docs/seo/setting-seo-metadata#canonical-url).

#### 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](/learn/docs/configuration/navigation#availability), with different options. If you want to set section and page availability, do so in your version-specific `yml` files.

#### docs.yml

```yaml {4}
versions: 
  - display-name: Latest          
    path: ./versions/latest.yml   
    availability: beta
  - display-name: v2
    path: ./versions/v2.yml
    availability: stable
```

#### 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 where each version's content comes from, how versions appear in URLs, and who can access them.

#### Build a version from a git ref

Instead of a `path` into your working tree, a version entry can name a `ref`: a git branch, tag, or commit SHA. On publish, Fern resolves the ref to a commit, checks out the repository at that commit, and builds that version's pages, navigation, assets, and API references from it, composed with the current branch's theme, shell, and `versions` metadata.

#### docs.yml

```yaml {5,8}
versions:
  - display-name: Latest
    path: ./versions/latest.yml   # built from the working tree
  - display-name: v2
    ref: release/v2               # built from the branch release/v2
  - display-name: v1
    ref: v1.0.0                   # built from the tag v1.0.0
    availability: deprecated
```

A version entry sets either `ref` or `path`, never both; `fern check` reports an entry that sets both as a configuration error.

Use a `ref` for a version of your docs that no longer receives content updates, such as a past release. Keep actively maintained versions on `path` in your working tree. `fern docs dev` previews working-tree versions only, so ref-backed content can't be previewed or edited locally: changing it means committing to the ref (or cutting a new tag) and republishing.

Tags and commit SHAs are immutable, so a published version stays byte-for-byte stable. Branch refs resolve to whatever commit the remote branch points at when you publish, which means a republish can change already-published content.

If the ref's own `docs.yml` is versioned, Fern builds its default version and ignores the rest; otherwise it builds the ref's top-level `navigation`. Publishing a ref-backed version requires git, access to the remote, and a `fern` folder at the same path at that ref. [Library reference](/learn/docs/api-references/library-reference) sections are skipped with a warning when their generated MDX is missing at the ref, so a version that predates a library still publishes.

#### Change version slugs

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

```yaml {7,11}
versions:
  - display-name: v4 (Latest)
    path: ./versions/latest.yml
    availability: stable
  - display-name: v3 (Deprecated)
    path: ./versions/v3.yml
    slug: v3
    availability: deprecated
  - display-name: v2
    path: ./versions/v2.yml
    slug: v2
    availability: deprecated
```

In this example, setting `slug: v3` produces URLs like `/docs/v3/getting-started`.

#### Add instance audiences

Control which versions appear in each [documentation instance](/learn/docs/configuration/site-level-settings#instances-configuration) 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

```yaml maxLines=10
instances:
  - url: internal.docs.buildwithfern.com
    audiences:
      - internal # Only shows content tagged with 'internal'
  - url: public.docs.buildwithfern.com
    audiences:
      - public # Only shows content tagged with 'public'
versions:
  - display-name: v3
    path: ./versions/v3.yml
    audiences:
      - public # This version only appears on the public instance
  - display-name: v2 (Internal)
    path: ./versions/v2.yml
    audiences:
      - internal # This version only appears on the internal instance
```

#### Hide versions from navigation

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

```yaml {8}
versions:
  - display-name: v3
    path: ./versions/v3.yml
  - display-name: v2
    path: ./versions/v2.yml
  - display-name: v1 (Legacy)
    path: ./versions/v1.yml
    hidden: true
```

> **Info**
>
> The default version (the first version in your `versions` list) can't be hidden.

#### Conditionally render content

To conditionally render content within a page based on the current version, use the [`<If>` component](/learn/docs/writing-content/components/if#by-version), which matches a version by its display name, slug, or id.

**`Markdown`**

```jsx Markdown
<If versions={["v2"]}>
  This content only appears in version v2.
</If>
```

#### Scope search by version

Search results can be [scoped to the reader's current version](/learn/docs/customization/search#scope-search-by-product-or-version) — either boosted in ranking or filtered by default — through the `settings.search` object in `docs.yml`.

## Customize version styling

Use custom CSS to style the version selector to match your brand.

#### Selector styling

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.

```css
.fern-version-selector {
  transform: translateY(1px);
  border-radius: 1000px;
  border: 1px solid var(--border);
}
```

#### Dropdown styling

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

![Example of a styled version selector](/learn/_fern-files/fern.docs.buildwithfern.com/87e75cfbffe35481c63f365598f3e000047cf84ea83c9a269efdd5bb24ece774/products/docs/pages/navigation/assets/webflow-version-selector.avif)

> Add a dropdown version selector for multiple doc versions