Read the Docs 2025 Vision: great support for all documentation tools
Photo by Matt Noble on Unsplash

Photo by Matt Noble on Unsplash

As we look forward to 2025, we took some time to reflect on where we've been and where we're going, and wanted to share that with you.

Our vision for Read the Docs is to be the best place to host software documentation using a docs-as-code approach. This means that we're building on top of Git, and providing features that make sense for software documentation.

Our product philosophy is to provide a great default experience but allow users to customize and extend as needed. This means that we provide a set of features that work for most projects, but then allow you to extend or replace them as needed.

Below is a breakdown of how that plays out with each of the major parts of Read the Docs.

Support for all documentation tools

We've been working to expand build support beyond Sphinx and MkDocs, and build Addons for powerful frontend features that work on any tool.

The major steps here have been:

  • Removing build magic: Removing the injection of data or configuration into your documentation builds. We used to have a full Sphinx extension that we injected, and a lot of configuration file manipulation for both Sphinx and MkDocs. This has been removed, which means builds should happen exactly as they do locally.
  • Adding build support for all tools: We built support into our build system for fully custom builds, which allows any build process that outputs HTML to be hosted on Read the Docs.
  • Adding frontend support for all tools: We rebuilt our flyout menu and the JavaScript that is injected into your documentation builds as a set of Read the Docs Addons. This enables granular configuration, and disabling of various frontend features via user settings.
  • Supporting custom integrations: We're exposing all the data that we use to build Addons to documentation users, who can build custom data integrations. This allows you to integrate the versions from the API into a version selector, offline formats into a download UI, and provide an integrated UX for your users.

The combination of all this work leads to a powerful place for Read the Docs in 2025. We can support any documentation tool, and then provide a powerful set of Addons to provide a great UX on top, and allow you to build custom integrations to make everything work together perfectly.

Our build system is more flexible than ever

All parts of Read the Docs have a default experience, but then allow you to customize and extend as needed.

With our build system, we recommend starting with build.jobs to get a simple build working:

  • Our build process defines a set of jobs that run in sequence to build your documentation.
  • You can extend the build process by adding pre and post jobs to run before and after the main build.
  • You can override the build.jobs to fully customize the build process.
  • If you don't want to use our build process at all, you can run a fully custom build with build.commands, allowing you to bring an existing build process to Read the Docs.

This gives users an on-ramp into a simple build process, but allows advanced users to fully customize their build process as needed.

Improved UX in our dashboard and docs pages

We've been working on a new dashboard that brings our site into the modern era. This has been fully rolled out to all users as the default, and we're continuing to improve it.

Addons is our approach to adding functionality to documentation pages. They give you a set of features that are enabled by default, but you can always choose to extend them or replace them fully.

We're excited about the Addons we've already built:

  • Visual diff to see changes between versions of your documentation in the rendered HTML. This builds on top of pull request previews to give you a full suite of tools for reviewing documentation changes.
  • Link previews to make browsing your docs easier for users, and improving the UX of link-heavy documentation like API references.
  • Flyout menu that provides users access to many Read the Docs features like search, versions, offline formats, and more.
  • Search as you type that is powered by Elasticsearch and allows searching multiple subprojects at once.
  • Traffic analytics to understand how your documentation is being used, and where you can improve it.
  • Notifications to alert users to out-of-date documentation, and other important information about their documentation builds.

We have some more interesting ideas for additional Addons, like a command palette to expose all of the features of Read the Docs in a single searchable interface.

Integrate our data for a better UX

With our custom event integration, you can always integrate the data provided by Read the Docs into your documentation.

Some neat examples of what folks have been building:

  • Version selectors that use the API to show the latest versions of your documentation.
  • Offline formats that use the API to show the latest PDF or Epub downloads.
  • Search integrations that use the API to power a custom search interface.

You can see an version selector integration example that shows how to use the API to build a custom version selector.

We're excited to see what you build with this data, and are always looking for feedback on how we can make it better.

Continuing to improve

This has been a long time coming, and we're excited to be coming into 2025 with a powerful set of features that work for all documentation tools. You can always reach out to us with feedback, and we're excited to see what you build!