Configuration

Product switching

Allow users to seamlessly navigate between different products you offer.
Pro and Enterprise feature

This feature is available only for the Pro and Enterprise plans. To get started, reach out to support@buildwithfern.com.

Webflow
View Webflow’s Product Switcher

Each product can contain its own distinct versions, tabs, sections, pages, and API references. Products can share content as well.

Products can be internal (hosted on your site) or external (linking to external URLs).

Add products to your docs

1

Define your products

Create a products folder inside of your fern folder. To specify a product’s contents and navigational structure, add a .yml file to the products folder for each product. Make sure to include the navigation and tabs properties, if applicable.

External products

You can also define external products, which link to external URLs (separate applications, third-party documentation, or other external resources) instead of documentation within your site. They appear in the product switcher but navigate users to the specified URL when selected. Define external products directly in docs.yml (no product-specific .yml file is needed).

$fern/
>  ├─ fern.config.json
>  ├─ generators.yml
>  ├─ docs.yml # Site-level contents and navigation
>  └─ products/
>    ├─ ...
>    ├─ product-a.yml # Contents and navigation for Product A
>    └─ product-b.yml # Contents and navigation for Product B
>    # No separate yml file needed for external products
1navigation: 
2  - section: Introduction
3    contents:
4      - page: Shared Resource
5        path: ../pages/shared-resource.mdx
6  - api: API Reference
2

Add your product configuration

To define a product, add an item to the products list in docs.yml, specifying the display-name and either path (for internal products) or href (for external products).

For both internal and external products, image, icon, and subtitle are optional parameters. If you provide both an image and an icon, the image will take precedence. Internal products additionally support the optional slug and versions parameters.

Product icons

Icons can be in three formats:

  • Font Awesome icons: Use icon names like fa-solid fa-rocket. Pro and Brand Icons from Font Awesome are supported.
  • Custom image files: Use relative paths to image files (e.g., ./assets/icons/my-icon.svg or ../assets/icons/my-icon.png). Paths are relative to the docs.yml file.
  • Inline SVG: Provide an SVG string wrapped in quotes (e.g., "<svg>...</svg>").

The below example is a docs.yml configuration for a site with two internal products (Product A and Product B) and one external product (Product C).

docs.yml
1products:
2  - display-name: Product A
3    path: ./products/product-a.yml
4    icon: fa-solid fa-leaf # Font Awesome icon
5    slug: product-a # optional
6    subtitle: Product A subtitle # optional
7
8  - display-name: Product B
9    path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
10    icon: ./assets/icons/product-b-icon.svg  # Custom image file
11    slug: product-b # optional
12    subtitle: Product B subtitle # optional
13  
14  - display-name: Product C 
15    href: https://dashboard.example.com # External product
16    icon: "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'><path d='M12 2L2 7v10c0 5.55 3.84 10.74 9 12 5.16-1.26 9-6.45 9-12V7l-10-5z'/></svg>"  # Inline SVG
17    subtitle: Product C subtitle
3

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 product-specific .yml files.

External products don’t support navigation and tabs fields.

Add versioning to your products

You can optionally add versions to your internal products. Versioned and unversioned products can live next to each other in your site. Versions are not supported for external products.

For standalone versioning without products, see our Versioning guide.

In the below example, Product A is unversioned and Product B is versioned:

$fern/
>  ├─ fern.config.json
>  ├─ generators.yml
>  ├─ docs.yml
>  ├─ pages/
>    ├─ ...
>  └─ products/
>    ├── product-a.yml # basic unversioned product
>    └── product-b/ # versioned product
>        ├─ product-b.yml
>        └─ versions/
>          ├─ latest/
>          │  ├─ latest.yml
>          │  └─ pages/...
>          └─ v2/
>            ├─ v2.yml
>            └─ pages/...
1

Define your versions

Create a versions folder inside of folder of the product you want to version.

Each version of a single product has its own yml file. 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:

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

The top-level doc.yml configuration for a Fern Docs website containing two products, one unversioned and one versioned, might look something like this:

docs.yml
1products:
2  - display-name: Product A # unversioned
3    path: ./products/product-a.yml 
4    icon: fa-solid fa-leaf # optional
5    slug: product-a # optional
6    subtitle: Product A subtitle # optional
7  - display-name: Product B # versioned
8    path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
9    image: ./images/product-b.png # optional
10    slug: product-b # optional
11    subtitle: Product B subtitle # optional
12    versions: 
13      - display-name: Latest
14        path: ./products/product-b/versions/latest/latest.yml # relative path to the version file
15      - display-name: V2
16        path: ./products/product-b/versions/v2/v2.yml # relative path to the version file
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.

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: ./products/product-b/versions/latest/latest.yml 
4    availability: beta
5  - display-name: V2
6    path: ./products/product-b/versions/v2/v2.yml
7    availability: stable
4

Remove extra navigation

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

Add instance audiences

Control which versions and/or products 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, products, 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'
8products:
9  - display-name: Platform API
10    path: ./products/platform-api.yml
11    audiences:
12      - public
13      - internal # This product appears on both instances
14    versions:
15      - display-name: v3
16        path: ./versions/v3.yml
17        audiences:
18          - public # This version only appears on the public instance
19      - display-name: v2 (Internal)
20        path: ./versions/v2.yml
21        audiences:
22          - internal # This version only appears on the internal instance
23  - display-name: Admin Tools
24    path: ./products/admin-tools.yml
25    audiences:
26      - internal # This product only appears on the internal instance

Instance audiences work alongside API Reference audiences, which filter endpoints and schemas within your API documentation. You can use both features together:

  • Instance audiences - Control which products and versions appear in each instance
  • API Reference audiences - Control which endpoints and schemas appear within API References

For example, you might have a public instance that includes only public products. Within those products, the API Reference should be marked as public so it is filtered to show only public endpoints.

Customize selector styling

You can directly customize the appearance of the product and version selectors by targeting their CSS classes:

  • fern-product-selector - Controls the styling of the product selector
  • fern-version-selector - Controls the styling of the version selector
Example of a styled product selector

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-product-selector {
2  transform: translateY(2px);
3  border-radius: 8px;
4  border: 1px solid var(--border);
5}
6
7.fern-version-selector {
8  transform: translateY(1px);
9  border-radius: 1000px;
10  border: 1px solid var(--border);
11}

Customize dropdown styling

The dropdown menus for product and version selectors can be customized using these specific CSS classes:

  • fern-product-selector-radio-group - Controls the styling of the product dropdown
  • fern-version-selector-radio-group - Controls the styling of the version dropdown
Example of a styled product selector

Common Styling Adjustments

Enable a grid layout for the dropdown:

1.fern-product-selector-radio-group {
2  display: grid;
3  grid-template-columns: repeat(2, 1fr);
4  gap: 8px;
5}