# Product switching

> Learn how to configure product switching in Fern Docs. Set up multiple products with custom navigation, versioning, and styling options.

<Warning title="Pro and Enterprise feature">
  This feature is available only for the [Pro and Enterprise plans](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).
</Warning>

<Frame>
  <video autoPlay muted loop>
    <source src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/5ca5372224d387625cdc038a95538d3c41072a80b5fc300341269310de1a7656/products/docs/pages/navigation/product-switcher.mp4" type="video/mp4" />
  </video>
</Frame>

<Card href="https://developers.webflow.com/data/docs/getting-started-apps">
  <div>
    <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/1df547c9906e9bd327f5a321856c7789385fde5b1d6c5a68c6df156248b9d242/products/docs/pages/navigation/logos/webflow-light.svg" alt="Webflow" width="24px" height="24px" class="logo-icon dark:hidden" />

    <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/cab46bc333407cc57d2b2ffb06dc414b606cfdeb2edca2bae97732fe0900a7c0/products/docs/pages/navigation/logos/webflow-dark.svg" alt="Webflow" width="24px" height="24px" class="logo-icon hidden dark:block" />

    <div>
      View Webflow's Product Switcher
    </div>
  </div>
</Card>

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

<Steps toc={true}>
  <Step title="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.

    <Info title="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).
    </Info>

    <Files>
      <Folder name="fern" defaultOpen>
        <File name="fern.config.json" />

        <File name="generators.yml" />

        <File name="docs.yml" highlighted comment="Site-level contents and navigation" />

        <Folder name="products" defaultOpen>
          <File name="product-a.yml" highlighted comment="Contents and navigation for Product A" />

          <File name="product-b.yml" highlighted comment="Contents and navigation for Product B" />
        </Folder>
      </Folder>
    </Files>

    <Note>
      No separate yml file needed for external products
    </Note>

    <CodeBlocks>
      <CodeBlock title="products/product-a.yml">
        ```yaml
        navigation: 
          - section: Introduction
            contents:
              - page: Shared Resource
                path: ../pages/shared-resource.mdx
          - api: API Reference
        ```
      </CodeBlock>

      <CodeBlock title="products/product-b.yml">
        ```yaml
        tabs: 
          api: 
            title: API Reference
            icon: puzzle
          help:
            title: Help Center
            icon: home
            
        navigation:
          - tab: api
            layout:
              - section: Introduction
                contents: 
                  - page: My Page
                    path: ./latest/pages/my-page.mdx # relative path to the file
                  - page: Shared Resource
                    path: ../pages/shared-resource.mdx
              - api: API Reference
          - tab: help
            layout: 
              - section: Help Center
                contents: 
                  - page: Contact Us
                    path: contact-us.mdx
        ```
      </CodeBlock>
    </CodeBlocks>
  </Step>

  <Step title="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.

    <Note title="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>"`).
    </Note>

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

    <CodeBlock title="docs.yml">
      ```yaml {2-3, 8-9, 14-15}
      products:
        - display-name: Product A
          path: ./products/product-a.yml
          icon: fa-solid fa-leaf # Font Awesome icon
          slug: product-a # optional
          subtitle: Product A subtitle # optional

        - display-name: Product B
          path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
          icon: ./assets/icons/product-b-icon.svg  # Custom image file
          slug: product-b # optional
          subtitle: Product B subtitle # optional
        
        - display-name: Product C 
          href: https://dashboard.example.com # External product
          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
          subtitle: Product C subtitle
          target: _blank # Link opens in a new tab
      ```
    </CodeBlock>
  </Step>

  <Step title="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.

    <Note>
      External products don't support `navigation` and `tabs` fields.
    </Note>
  </Step>
</Steps>

### Add a site-level landing page

You can add a landing page that appears at the root of your documentation site, independent of any product. This is useful when you want users to see an introductory page before selecting a product.

Configure the `landing-page` property in your `docs.yml`:

<CodeBlock title="docs.yml">
  ```yaml
  landing-page:
    page: Welcome
    path: ./pages/welcome.mdx
    slug: /welcome # optional

  products:
    - display-name: Product A
      path: ./products/product-a.yml
    - display-name: Product B
      path: ./products/product-b.yml
  ```
</CodeBlock>

The landing page is not linked to any product and will be accessible at the root URL (or the specified slug) of your documentation site.

<Note>
  For detailed configuration options, see the [landing page configuration reference](/learn/docs/configuration/site-level-settings#landing-page-configuration).
</Note>

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

<Note>
  For standalone versioning without products, see our 

  [Versioning guide](/docs/configuration/versions)

  .
</Note>

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

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />

    <File name="generators.yml" />

    <File name="docs.yml" />

    <Folder name="pages" />

    <Folder name="products" defaultOpen>
      <File name="product-a.yml" highlighted comment="basic unversioned product" />

      <Folder name="product-b" defaultOpen comment="versioned product">
        <File name="product-b.yml" />

        <Folder name="versions" highlighted defaultOpen>
          <Folder name="latest">
            <File name="latest.yml" />

            <Folder name="pages" />
          </Folder>

          <Folder name="v2">
            <File name="v2.yml" highlighted />

            <Folder name="pages" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

<Steps>
  <Step title="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:

    <CodeBlocks>
      <CodeBlock title="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
        ```
      </CodeBlock>

      <CodeBlock title="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
        ```
      </CodeBlock>
    </CodeBlocks>
  </Step>

  <Step title="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:

    <CodeBlock title="docs.yml">
      ```yaml {2, 8, 12-16}
      products:
        - display-name: Product A # unversioned
          path: ./products/product-a.yml 
          icon: fa-solid fa-leaf # optional
          slug: product-a # optional
          subtitle: Product A subtitle # optional
        - display-name: Product B # versioned
          path: ./products/product-b/versions/latest/latest.yml # <-- default showing latest
          image: ./images/product-b.png # optional
          slug: product-b # optional
          subtitle: Product B subtitle # optional
          versions: 
            - display-name: Latest
              path: ./products/product-b/versions/latest/latest.yml # relative path to the version file
            - display-name: V2
              path: ./products/product-b/versions/v2/v2.yml # relative path to the version file
      ```
    </CodeBlock>

    <Note title="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](/docs/seo/redirects) broken versioned links to the default version and managing canonical URLs.
    </Note>
  </Step>

  <Step title="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#section-and-page-availability), with different options. If you want to set section and page availability, do so in your version-specific `yml` files.

    <CodeBlock title="docs.yml">
      ```yaml {4}
      versions: 
        - display-name: Latest          
          path: ./products/product-b/versions/latest/latest.yml 
          availability: beta
        - display-name: V2
          path: ./products/product-b/versions/v2/v2.yml
          availability: stable
      ```
    </CodeBlock>
  </Step>

  <Step title="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.
  </Step>
</Steps>

### Add instance audiences

Control which versions and/or products appear in each [documentation instance](/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, products, and versions in `docs.yml`:

<CodeBlock title="docs.yml">
  ```yaml
  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'
  products:
    - display-name: Platform API
      path: ./products/platform-api.yml
      audiences:
        - public
        - internal # This product appears on both instances
      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
    - display-name: Admin Tools
      path: ./products/admin-tools.yml
      audiences:
        - internal # This product only appears on the internal instance
  ```
</CodeBlock>

<Accordion title="Combining with API Reference audiences">
  Instance audiences work alongside [API Reference audiences](/docs/api-references/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.
</Accordion>

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

<Frame>
  <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/bab6437fa01dd360adede2a1a7b0ce42f67ca77c5842a6a0cc9dc8cee89507c1/products/docs/pages/navigation/webflow-dropdown-selector.avif" alt="Example of a styled product selector" />
</Frame>

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

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

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

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

<Tabs>
  <Tab title="Product Selector">
    <Frame>
      <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/a4e2347d8f009928653c75e33270751fa6808494755c8d74835a886533f4c240/products/docs/pages/navigation/webflow-product-selector.avif" alt="Example of a styled product selector" />
    </Frame>

    ### Common Styling Adjustments

    **Enable a grid layout for the dropdown:**

    ```css
    .fern-product-selector-radio-group {
      display: grid;
      grid-template-columns: repeat(2, 1fr);
      gap: 8px;
    }  
    ```
  </Tab>

  <Tab title="Version Selector">
    <Frame>
      <img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/87e75cfbffe35481c63f365598f3e000047cf84ea83c9a269efdd5bb24ece774/products/docs/pages/navigation/webflow-version-selector.avif" alt="Example of a styled version selector" />
    </Frame>
  </Tab>
</Tabs>