Addons flyout menu beta¶
We are happy to announce that a new flyout menu is now available as part of the ongoing beta test for our latest project, Read the Docs Addons.
After much hard work, we are excited to begin testing this feature with more projects. We have previously been testing other documentation features as part of this ongoing beta, but the flyout menu is by far the most prominent feature yet.
What are Addons?¶
Addons is a new project that aims to bring all of our features to new documentation tools and replace features that currently only support Sphinx or MkDocs.
Along with the flyout menu, we are also currently testing many other features as part of this beta period:
Non-latest version warning banner
Pull request warning banner
Search as you type
Sponsorship via EthicalAds
We redesigned everything from the ground up in order to address limitations of our current features:
- Supporting new documentaiton tools is difficult
Right now, we only support Sphinx and MkDocs and are injecting our hosting features like our flyout menu at build time, using custom extensions for each tool. In order to support new documentation tools, we must maintain a new extension for each tool we want to support.
- Features aren’t supported by all documentation tools
Maintaining multiple extensions has also lead to differences in the features each tool supports, as we have to rely on the integrations available in each tool.
- Customization is difficult
We also can not offer easy customization of features like our flyout menu due how they are injected into hosted documentation.
Eventually, all documentation tools will use this same library, including Sphinx and MkDocs, and all tools will have the same access to our documentation features.
How to use Addons¶
We decided to limit beta testing to projects using the
build.commands configuration key 1.
These projects did not have any of our documentation features,
like our flyout menu or search,
as our documentation tool extensions do not execute for these projects.
If you are using this configuration option,
your project is already using the new Addons library.
Projects participating will get new documentation features as they become available.
If you have any feedback or would like to opt out of the beta, contact us.
What has changed¶
On the technical implementation, everything has changed. This is a full rewrite of these features so there is a lot to mention here, but there are two main points to highlight:
readthedocs-addons.js, at serving time via Cloudflare Workers. This allows us to support any documentation tool (e.g. Docusaurus, Pelican, Docsify, etc) without having to create a specific extensions for it. This helps with our goal of making our platform documentation tool agnostic.
- The flyout is rendered using a JSON API call
You can read more on build customization and how to use
build.commandsto control the entire build process here: https://docs.readthedocs.io/en/latest/build-customization.html
Subscribe to our mailing list
Sign up for our blog and we'll send you news and updates about Sphinx and Read the Docs on a regular basis.
You have successfully joined our subscriber list.
- 05 September - Read the Docs newsletter - September 2023
- 24 August - Enabling latest versions for Sphinx & Mkdocs builds
- 09 August - Use build.os instead of build.image on your configuration file
- 08 August - Drop support for “Use system packages”
- 03 August - Read the Docs newsletter - August 2023