Read the Docs — Documentation Hosting and Build Platform

Introduction

Read the Docs is an open-source platform that builds and hosts documentation from version-controlled repositories. It automates the workflow of turning reStructuredText or Markdown source files into a searchable, versioned documentation site, and has hosted docs for thousands of open-source projects.

What Read the Docs Does

• Builds documentation automatically on every commit via webhook integration
• Hosts multiple versions of docs (stable, latest, per-branch, per-tag)
• Provides full-text search across all documentation pages
• Generates PDF, EPUB, and HTML downloads from the same source
• Supports Sphinx, MkDocs, and custom build commands

Architecture Overview

Read the Docs is a Django web application backed by PostgreSQL and Elasticsearch. When a webhook fires, a Celery worker clones the repository, installs dependencies in an isolated environment, and runs the configured build tool. The output is stored and served behind a CDN. Each project gets a subdomain (project.readthedocs.io) with HTTPS by default.

Self-Hosting & Configuration

• Deploy the community edition using Docker Compose from the official repository
• Configure the Django settings for your database, Redis, and storage backend
• Connect to GitHub, GitLab, or Bitbucket for webhook-triggered builds
• Add a .readthedocs.yaml file to your repo to pin the Python version and build tools
• Set up custom domains with automatic SSL certificate provisioning

Key Features

• Automatic version management tied to branches and tags in your VCS
• Pull request preview builds so reviewers can see doc changes before merge
• Analytics dashboard showing page views and search queries
• Localization support for multilingual documentation
• Embed API for pulling rendered documentation into external sites

Comparison with Similar Tools

• GitHub Pages — static hosting without built-in versioning or search
• Netlify / Vercel — general-purpose hosting; Read the Docs specializes in documentation workflows
• GitBook — commercial with a free tier; Read the Docs is fully open source and self-hostable
• Docusaurus — a static site generator, not a hosting platform

FAQ

Q: Is the hosted service at readthedocs.org free? A: Yes, free for open-source projects. A commercial product (Read the Docs for Business) adds private repos and priority support.

Q: Can I self-host Read the Docs? A: Yes. The community edition is open source under the MIT license and can be deployed with Docker.

Q: Does it support MkDocs in addition to Sphinx? A: Yes. Both Sphinx and MkDocs are supported as first-class build tools.

Q: How does versioning work? A: Each Git branch or tag can be activated as a documentation version, accessible at its own URL path.

Sources

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