News and updates¶

• ⭐️ We passed our 10,000th issue/pull request on GitHub. And it’s pretty much an equal split between the 5039 issues and 4872 pull requests now registered. Thanks to the whole community for building this together through code, issues, suggestions… and documentation!

• 🌪️ Follow up: Build times have gone rapidly down after last month’s introduction of parallel uploading of artifacts with rclone. Depending on the number of files in your build output, build times may have gone down several seconds or several minutes. For instance, a large project like Write the Docs has gone down from ~7 minutes to under 3 minutes. If you want to see the change for your project, have a look at your build times before and after February 8.

• 1️⃣️ We are going to have 1 primary marketing website in the future, while still running two different product for our Community & Business users. The first change that is now done is redirecting logged out users on https://readthedocs.com/ to about.readthedocs.com. We will soon be doing this for logged out users going to https://readthedocs.org/, excepting project-specific subpages.

• 🧹️ We are now able to delist unofficial projects from search engines. If you find an unofficial and unmaintained project, please see our policy on unofficial and unmaintained projects.

• 🐞 Custom 404s with Sphinx DirHTML builder are now supported.

• 🔒️ Vulnerability fixed: Serving content from pull requests previews on main docs domains.

• 🔒️ Vulnerability fixed: Path traversal: access to files from any project.

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

Upcoming¶

• 🪄️ The Django application that handles uncached requests on all our hosted documentation is called El Proxito. And that application is getting a major refactor, improving both speed and features. Most of the refactoring work is already merged and within the coming weeks, we will start to enable it gradually while monitoring if there are issues.

• 📚️ Documentation refactor underway: A regular reader of our user docs might notice that our navigation has been greatly changed and now contains only the 4 Diátaxis categories. The first work from our Diátaxis documentation refactor is now live and the general work has moved into shorter iterations. Once we have gathered all the final experience from the refactor, we will announce it together with practical inputs for how other documentation projects might approach such a refactor.

• 💬️ …If you are planning your own refactor of an existing documentation project, we’d love to hear what your questions and concerns are and address those future blog posts and talks.

• 🐞 Pull request builds should point to previews, not build pages. A fix will is ready in #10085.

• 🎬️ We’re slowly moving towards a public beta of our v2 dashboard experience. Here’s a screenshot of what’s to come…

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

Awesome project of the month¶

The Haskell Tool Stack is commonly known in the world of Haskell as simply Stack and is this month’s chosen entry from Awesome Read the Docs Projects 🕶️. See our chosen highlights from Stack’s documentation in the following Twitter thread:

The Haskell Tool Stack is a packaging tool for #haskell. Because their documentation is so awesome, it’s also their main website 💯

Stack’s website is maintained with GitHub, MkDocs, and Read the Docs: https://t.co/GaCTgxTUcm

Here is a 🤏 (small) 🧵 about why it’s awesome 🕶️ pic.twitter.com/wdAQ3NigHK

— Read the Docs (@readthedocs) March 7, 2023

Tip of the month¶

When you post links to your documentation on chat and social media, you will probably see a generic preview. Enter sphinxext-opengraph!

This Sphinx extension allows you to configure your own preview card, compatible with all major chat and social media platforms. A particular feature which we really enjoy is that the extension will detect and use the first illustration in a documentation page. If you want to see it in action, try sharing a link to this newsletter blog post (marketing unintended). Our user docs are also using sphinxext-opengraph.

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