Skip to navigation

Changelog

November 3, 2025

Tab variants

Create multiple content variations within a single tab using the new variants feature. This allows you to show different perspectives, user types, or implementation approaches for the same topic without creating separate tabs.

You can now define variants for tabs with different layouts, titles, subtitles, and icons. Each variant can have its own navigation structure, and you can explicitly set which variant should be the default.

docs.yml
navigation:
  - tab: guides
    variants:
      - title: For developers
        layout:
          - section: Getting started
            contents:
              - page: Quick start
                path: ./pages/dev-quickstart.mdx
      - title: For product managers
        default: true
        layout:
          - section: Getting started
            contents:
              - page: Overview
                path: ./pages/pm-overview.mdx
Read the docs

Custom icons across your navigation

You can use your own image files as icons throughout your docs.yml navigation config, including for navbar link, section, page, and product icons.

Icons support three formats:

  • Font Awesome icons: Use icon names like fa-solid fa-seedling or fa-regular fa-leaf. Pro and Brand icons from Font Awesome are supported.
  • Custom image files: Use relative paths to custom image files (e.g., ./assets/icons/plant-icon.svg). Paths are relative to the YAML file where the icon is referenced (e.g., docs.yml).
  • Inline SVG: Provide an SVG string wrapped in quotes.
Sidebar icons in docs.yml
navigation:
  - section: Home
    icon: fa-regular fa-home  # Font Awesome icon
    contents:
      - page: Introduction
        icon: ./assets/icons/intro-icon.svg  # Custom image file
        path: ./pages/intro.mdx
      - page: Custom Features
        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
        path: ./pages/custom.mdx
  - api: API Reference
    icon: fa-regular fa-puzzle
Read the docs

You can now configure products to link to external URLs (separate applications, third-party documentation, or other external resources) instead of documentation within your site.

External products appear in the product switcher alongside internal products but navigate users to the specified URL when selected. Unlike internal products, external products are defined directly in docs.yml using href—no standalone product .yml file is needed.

To define an external product, add an item to the products list in docs.yml with an href instead of a path:

docs.yml
products:
  - display-name: API Documentation
    path: ./products/api-docs.yml
    icon: fa-solid fa-book
    slug: api-docs
    subtitle: Complete API reference
  - display-name: Dashboard # External product
    href: https://dashboard.example.com
    icon: fa-solid fa-chart-line
    subtitle: Analytics and insights
Read the docs