Flyout menu

When you use a Read the Docs site, there is a flyout menu embedded on all the documentation pages. The flyout menu is a way to expose the functionality of Read the Docs on the page, without having to have the documentation theme integrate it directly.

Tip

The flyout menu is a default implementation that works for every site. You can access the full data used to construct the flyout, and use that to integrate the data directly into your documentation theme for a nicer user experience. See the Custom event integration for more information.

Addons flyout menu

The Read the Docs Addons flyout provides a place for a number of Read the Docs features:

  • A version switcher that shows users all of the active versions they have access to.

  • A translation switcher that shows all the documentation languages provided.

  • A list of offline formats for the current version, including HTML & PDF downloads.

  • Links to the Read the Docs dashboard for the project.

  • A search bar that gives users access to the Server side search of the current version.

_images/flyout-addons.png

The opened flyout menu

Customizing the flyout menu

In your dashboard, you can configure flyout menu options in Settings > Addons > Flyout Menu.

Version sorting

The primary customization currently is the ability to sort versions. You can sort by:

  • SemVer (Read the Docs) - Default. Read the Docs custom implementation of semver.org.

  • Python Packaging - Sort by Python packaging sorting.

  • CalVer - Sort by calendar date.

  • Alphabetically - Only useful if you aren’t using numeric versions.

  • Or you can define a custom pattern

You can also choose whether latest and stable should be sorted first, as those are special versions that Read the Docs uses.

Position

The flyout can be configured in the dashboard with the following positions:

  • Default (from theme or Read the Docs) - Default. If the theme author defines a specific position for the flyout, that position will be used. Otherwise, the default position from Read the Docs will be used: Bottom right.

  • Bottom left - Show the flyout at the bottom left.

  • Bottom right - Show the flyout at the bottom right.

  • Top left - Show the flyout at the top left.

  • Top right - Show the flyout at the top right.

Note

If you are a theme author and want to define a default flyout position for your theme, you can explicitly define the flyout web component with the position attribute in your HTML:

<readthedocs-flyout position="bottom-left"></readthedocs-flyout>

Available positions: bottom-left, bottom-right, top-left and top-right.

Custom event integration

Read the Docs Addons exposes all the data used to construct the flyout menu via a JavaScript CustomEvent. If you’d like to integrate the data, you can use the Integrate the Read the Docs version menu into your site navigation example as a starting point.

Warning

We have not formally documented the API response returned from the Addons API, but you can view the JSON data returned there as a starting point. Once we document it, we will commit to supporting that version of the API response going forward.