Read the Docs is a documentation hosting platform that automatically builds and hosts docs from your Git repo, most commonly Sphinx or MkDocs projects. You connect a repository, and every time you push a commit, it builds the docs and publishes them with versioning, search, and a CDN in front. It has been the default home for Python and open-source documentation for over a decade. This review covers what it is, how it works, what it costs, and where it fits.
If you already know you want to switch, our Read the Docs alternatives post lists specific replacements. This piece is the other half of that: a straight review of what Read the Docs actually does, who it suits, and its real limitations. Along the way it links out to related reading on Sphinx documentation, documentation hosting options, and MkDocs Material so you can go deeper where you need to.
What is Read the Docs?
Read the Docs is a build-and-host service for technical documentation. You write your docs as source files in a Git repository, usually with Sphinx and reStructuredText or with MkDocs and Markdown. Read the Docs watches that repository, runs the build for you on its own servers, and serves the resulting HTML at a public URL. You do not manage a build server or a web host yourself.
The project started in 2010 as a weekend hackathon idea and grew into core infrastructure for the Python ecosystem. Today it hosts documentation for tens of thousands of open-source projects. If you have read Python library docs in the last decade, there is a strong chance they were served by Read the Docs.
The key idea is separation of concerns. You own the content and the source format. Read the Docs owns the build pipeline, hosting, versioning, and search. That trade works well when your team is comfortable writing docs as code and wants the publishing side handled.
Who is it for?
The core audience is developers and open-source maintainers who keep documentation next to their code. If your docs live in a docs/ folder and build with Sphinx or MkDocs, Read the Docs is close to purpose-built for you. Python projects especially, since Sphinx originated in the Python world and the two fit together cleanly.
It is a weaker match for non-technical teams. A founder who wants a branded help center without touching a build config or learning reStructuredText will find the setup heavy. That gap is where managed platforms come in, which we cover in the alternatives section below.
How does Read the Docs work?
The workflow is built around your Git provider. Once you connect an account, the flow looks like this:
- Import a repository. You point Read the Docs at a GitHub, GitLab, or Bitbucket repo containing your docs source.
- Add a config file. A
.readthedocs.yamlfile at the repo root tells the platform which builder to use, the Python version, and where your config lives. - Push a commit. Every push to a tracked branch triggers an automatic build. Read the Docs installs your dependencies, runs Sphinx or MkDocs, and publishes the output.
- Get versioned URLs. Each branch and tag can map to its own version of the docs, so
stable,latest, and older releases stay live side by side. - Preview pull requests. When enabled, opening a PR builds a temporary preview so reviewers see the rendered docs before merging.
That build-on-commit loop is the heart of the product. You never manually deploy. The .readthedocs.yaml file is where most first-time setup pain shows up, which we get to in the limitations section.
Read the Docs vs a managed docs platform
Read the Docs handles building and hosting well, but you still author every page yourself in Sphinx or MkDocs. A managed platform takes on the content and branding side too. Here is how the two approaches compare.
| Read the Docs | Managed docs platform (e.g. Docsio) | |
|---|---|---|
| What it does | Builds and hosts docs from your Git repo | Generates, hosts, and edits a full docs site |
| Authoring | You write Sphinx/reST or MkDocs/Markdown | AI generates a first draft from your URL or files |
| Versioning | Per branch and tag, built in | Doc versioning on paid plans |
| Hosting | CDN hosting, custom domains, SSL | Hosted with SSL and custom domains included |
| Setup effort | Git connect plus a .readthedocs.yaml config | Paste a URL, no build files |
| Best for | Developers who write docs as code | Founders and small teams who want a site made for them |
The split is about where the work sits. Read the Docs assumes you are happy writing and maintaining source files, and it takes the publishing off your plate. A managed platform assumes you want the content produced and the site branded without a toolchain to learn.
Key features
For a service with a free open-source tier, the feature set is deep. The ones that matter most day to day:
- Automatic builds. Push a commit, get a fresh build. No manual deploy step.
- Versioned documentation. Publish multiple versions from branches and tags with a version selector in the navigation.
- Full-text search. Built-in search across your docs, indexed on every build.
- Pull request previews. Reviewers see rendered docs on a temporary URL before a merge.
- Custom domains with SSL. Point your own domain at the docs and get an HTTPS certificate.
- Addons. A newer layer that adds features like a docs-aware search interface, flyout menus, notifications, and analytics without changing your theme.
- CDN hosting. Pages are served through a content delivery network, so load times stay fast for a global audience.
Every plan, free and paid, includes the build, versioning, search, PR preview, and CDN hosting basics. The paid tiers add private repositories, more concurrent builds, and longer retention rather than gating the core experience.
Community vs Business pricing
Read the Docs runs two offerings, and the split is clean.
Read the Docs Community is free forever for publicly hosted open-source projects. The catch is that it displays ads (via EthicalAds, its own privacy-friendly network) and your docs are public. For an open-source library, this is the standard choice and costs nothing.
Read the Docs for Business is the paid product for private documentation. Plans start at $50 per month, with $150 and $250 per month tiers above that. Paid plans remove ads, allow private repositories, add SSO on higher tiers, and raise build concurrency and retention windows. There is a 30-day free trial with no automatic charge. Above the standard tiers, an Enterprise plan starts from around $10,000 per year and adds SAML SSO, dedicated builders, and a support SLA.
So the money question is simple. Open source and fine with public docs plus ads, use Community for free. Private repos, no ads, or SSO, you are on Business starting at $50 per month.
Pros
What Read the Docs does well, it does very well:
- Zero-maintenance hosting. Once it is wired up, docs publish themselves on every commit. No servers to babysit.
- Versioning that just works. Multi-version docs are hard to build by hand. Here they come free with branches and tags.
- Free for open source. A genuinely capable free tier that has earned trust across the Python community.
- Git-native workflow. Docs live in the same repo and PR flow as code, so reviews and history stay together.
- Fast, global delivery. CDN hosting and full-text search out of the box, no extra configuration.
Cons and limitations
The honest drawbacks are worth knowing before you commit:
- You still author everything yourself. Read the Docs builds and hosts, but it does not write your docs. You produce every page in Sphinx or MkDocs.
- reStructuredText has a learning curve. Sphinx's default markup is more involved than Markdown, and new contributors often stumble on it.
.readthedocs.yamlcan be fiddly. Build config trips people up. A missing dependency or wrong Python version means a red build, and debugging remote builds is slower than local ones.- Design is constrained. You get themes and some customization, but a bespoke, heavily branded marketing-grade site is not what this is for.
- Ads on the free tier. Community docs carry EthicalAds unless you move to a paid plan.
None of these are dealbreakers for a developer team writing docs as code. They are friction for anyone who wanted a finished, branded site without a build pipeline.
Who should use Read the Docs (and who shouldn't)
Use it if you are a developer or open-source maintainer whose docs already live in Git and build with Sphinx or MkDocs. The free Community tier is hard to beat for public projects, and the Business tier is reasonable for private team docs that follow the same docs-as-code pattern.
Skip it if you are a SaaS founder or small team that wants a docs site produced for you, branded to your product, and live without learning reStructuredText or wrestling a YAML build file. That is a different job than Read the Docs is built to do, and forcing it there means more setup than the result is worth.
Best alternatives
If Read the Docs is not the right shape, a few directions are worth a look. For a wider survey, the Read the Docs alternatives roundup goes tool by tool.
- Docusaurus. A React-based static site generator with versioning, search, and MDX. More flexible and more brandable, at the cost of a Node toolchain. See our Docusaurus alternatives rundown for how it compares.
- MkDocs with Material. The Markdown-first path that many teams prefer over Sphinx. Read the Docs builds MkDocs projects too, so this is often a swap of authoring format rather than host. Our MkDocs Material review covers it.
- GitHub Pages. Free static hosting straight from a repo, with more manual setup. The GitHub Pages for documentation guide walks through it.
- Docsio. A managed platform for teams who do not want to write and maintain docs by hand. You paste your product URL, and AI documentation generation drafts a full branded site from your existing content. It is hosted with SSL and custom domains, with no Sphinx and no build files to manage. Pro sites are $60 per month with unlimited AI editing. For a founder who wants docs shipped this week, that solves the content and hosting problem together rather than only the hosting half.
For the audience that wants a site generated and hosted for them, a managed platform is the closer fit. For a developer team writing docs as code, Read the Docs remains one of the strongest options available.
The verdict
Read the Docs earned its position for good reason. The build-on-commit workflow, free open-source hosting, and built-in versioning solve real problems that are tedious to solve by hand. In 2026 it is still the default answer for Python and open-source documentation, and the Business tier is a fair deal for private team docs.
The one thing to keep clear is what it does not do. It hosts and builds, but you write every word yourself in a docs-as-code toolchain. If that matches how your team works, Read the Docs is excellent. If you wanted the docs produced and branded for you, look at a managed platform instead. You can start a Docsio project and have a site live before you would have finished configuring a builder.
Frequently asked questions
What is Read the Docs?
Read the Docs is a platform that automatically builds and hosts documentation from a Git repository. You connect a repo, push commits, and it builds your Sphinx or MkDocs docs and serves them with versioning, full-text search, pull request previews, and CDN hosting, so you never run a build server yourself.
Is Read the Docs free?
Read the Docs Community is free forever for publicly hosted open-source projects, though it shows ads. Read the Docs for Business, which adds private repositories, no ads, and SSO, starts at $50 per month across three tiers, with a 30-day free trial and no automatic charge when it ends.
Does Read the Docs use Sphinx or MkDocs?
Both. Sphinx with reStructuredText is the most common setup and where Read the Docs has the deepest roots, but MkDocs with Markdown is fully supported too. You choose the builder in your .readthedocs.yaml config file. The platform builds and hosts either one the same way.
What is the best Read the Docs alternative?
It depends on your team. Developers writing docs as code often move to Docusaurus or MkDocs with Material. Founders and small teams who want a branded site generated and hosted for them, without Sphinx or build files, are a better fit for a managed platform like Docsio that drafts the site from an existing URL.