Read the Docs newsletter - April 2023

News and updates

  • 📚️ Over the past ~6 months, we gradually refactored our user documentation to align with the Diátaxis Framework. The results are now manifested in the structure of the navigation sidebar and the landing page on

  • 📊️ All of our websites now use Plausible for analytics.

  • ⚙️ Added a new build variable READTHEDOCS_CANONICAL_URL that’s useful for projects that need the canonical base URL while building. View docs.

  • ⚙️ Added new build variables READTHEDOCS_GIT_CLONE_URL, READTHEDOCS_GIT_IDENTIFIER, and READTHEDOCS_GIT_COMMIT_HASH for projects that need to access Git data while building. View docs.

  • 🔒️ Fixed vulnerability: Cache poisoning: serving arbitrary content on documentation sites

You can always see the latest changes to our platforms in our Read the Docs Changelog.

A screenshot of our current documentation after the refactor

A screenshot of how our user documentation looks in April 2023.

Upcoming features

  • 📚️ We are still doing changes in our user documentation structure and content: Once the last parts of the plan are implemented, we are ready to share a bigger announcement.

  • ⚡️ A lot of work is happening these days on big front-end features. In the last newsletter, we mentioned the new Dashboard and the migration to What’s new is that we’ve also started building a generic JavaScript client accompanied with APIs that will give additional features to any documentation project or static site built and served on the Read the Docs platform.

    The first proof-of-concept for the new API and JavaScript library has been test-driven. It is capable of displaying a menu matching our current flyout menu and integrated server side search.

    The new library is useful for any documentation framework or static site generator to allow for full control of the new flyout menu, integrated search and general access to API data. See the screenshot further down where the integrated search in action on the documentation framework Docusaurus.

    We plan to be rolling this out gradually for Sphinx and MkDocs projects that are currently running their own set of build.commands. Once that happens, we’ll be back with news on the blog and documentation about how you can configure it.

A screenshot of the upcoming search dialogue running on Docusaurus

Our proof-of-concept for the JavaScript client is going well! In the screenshot, you can see how the generic Read the Docs search indexing works and how a generic search dialog gives the documentation project additional super powers ⚡️

Want to follow along with our development progress? View our full Roadmap 📍️

Awesome project of the month has integrated 15 Sphinx projects in the same website experience and written their own theme. So they rightly deserve to be this month’s addition to Awesome Read the Docs Projects 🕶️. See the highlights in the following Twitter thread or Mastodon thread:

Questions? Comments? Ideas for the next newsletter? Contact us!