Read the Docs — Documentation Hosting for Open Source

Introduction

Read the Docs is a documentation hosting platform that automatically builds and publishes documentation from your version control repository. It supports Sphinx (reStructuredText) and MkDocs (Markdown), provides versioned documentation tied to branches and tags, and serves millions of documentation pages for open-source projects at no cost.

What Read the Docs Does

• Automatically builds documentation on every commit or pull request
• Hosts versioned docs tied to Git branches and tags
• Provides full-text search across documentation pages
• Supports custom domains with free SSL certificates
• Generates PDF, ePub, and HTML downloads from the same source

Architecture Overview

Read the Docs watches your repository for changes via webhooks. On each push, it spins up a build environment that installs your project dependencies and runs Sphinx or MkDocs to produce HTML output. Built documentation is served from a CDN with version-aware URL routing (e.g., /en/latest/, /en/v2.0/). The platform is itself open source and can be self-hosted, though most projects use the managed service.

Self-Hosting & Configuration

• Create a .readthedocs.yaml in your repository root for build configuration
• Specify Python version, OS, and build commands in the config file
• Connect your GitHub, GitLab, or Bitbucket repository through the web dashboard
• Configure custom domains via DNS CNAME records
• Self-host using the readthedocs.org codebase with Docker for private documentation

Key Features

• Versioned documentation from Git branches and tags with a version switcher
• Pull request previews for reviewing documentation changes before merge
• Built-in full-text search powered by Elasticsearch
• Traffic analytics to see which pages get the most visits
• Supports Sphinx extensions, MkDocs plugins, and custom themes

Comparison with Similar Tools

• GitHub Pages — Static hosting only, no built-in versioning or search
• Netlify — General static hosting, no documentation-specific features
• GitBook — Commercial documentation platform, SaaS model
• Docusaurus — React-based static generator, self-hosted deployment
• Mintlify — Modern documentation hosting, commercial with free tier

FAQ

Q: Is Read the Docs free? A: Yes, for open-source projects. A paid plan (Read the Docs for Business) is available for private repositories and additional features.

Q: Can I use Markdown instead of reStructuredText? A: Yes. Use MkDocs as your documentation tool, or use MyST-Parser with Sphinx to write Markdown that compiles through Sphinx.

Q: How does versioning work? A: Each branch or tag in your repository can be activated as a documentation version. Readers switch between versions using a dropdown in the docs.

Q: Can I self-host Read the Docs? A: Yes. The platform is open source and can be deployed on your own infrastructure using the official repository and Docker.

Sources

• https://github.com/readthedocs/readthedocs.org
• https://docs.readthedocs.io/