Stop Merging Docs Blind: Read the Docs Pull Request Previews

Here's a familiar review moment: a contributor opens a pull request that edits three pages in your docs/ folder. The diff shows a new cross-reference, a tweaked code block, and a restructured heading. You can read the Markdown or reStructuredText, but you cannot see whether that cross-reference actually resolves, whether the code block renders with the right syntax highlighting, or whether the heading change broke a table of contents. So you do what most teams do — skim, approve, and find out after merge when the published site has a broken link.

Read the Docs has a feature that closes this gap: it can build and host a full rendered preview of your documentation for every pull request, and post the result back as a status check on GitHub, GitLab, or Bitbucket. The reviewer's job changes from "imagine what this renders like" to "click Details and read it."

What a preview build actually is

When the feature is enabled, each pull request gets its own isolated build on Read the Docs. The output is hosted at a build-specific URL that is separate from your public latest and stable versions. Unmerged content never appears on your live docs site — previews are unlisted and reachable only through the link attached to the status check.

Every push to the open pull request triggers a fresh build, so the preview always reflects the current state of the branch. When the check turns green, the docs built successfully; when it turns red, the build log is one click away, which is where you catch things like a malformed Sphinx directive or an MkDocs nav entry pointing at a file that no longer exists.

Turning it on

There are two pieces. First, your repository needs a .readthedocs.yaml configuration file at its root — this is standard for any Read the Docs project and works for both Sphinx and MkDocs. A minimal MkDocs example:

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

mkdocs:
  configuration: mkdocs.yml

Second, in the Read the Docs dashboard, open your project's settings and enable the option to build pull requests. That's the whole setup — there is no CI workflow to write, because Read the Docs receives the webhook events from your Git host and handles the builds itself.

One assumption to note: exact menu names and plan availability change over time, and pull request builds have historically differed between the community and commercial offerings. Confirm the option exists on your plan in the project settings before relying on it.

A worked example: the broken reference that never shipped

Say a contributor renames docs/tutorial/getting-started.md to docs/tutorial/quickstart.md and updates the obvious links. In the diff, everything looks fine. But the pull request build goes red, and the build log shows a warning-as-error: another page, docs/faq.md, still linked to the old path. Without the preview build, that broken link ships to production and sits there until a reader reports it. With it, the contributor pushes one more commit, the check goes green, and the reviewer clicks Details on the status check to read the rendered tutorial exactly as it will appear after merge — formatting, admonitions, navigation and all.

This is the real value: documentation review shifts left. Broken links, malformed directives, and formatting regressions surface at review time, when fixing them costs one commit, instead of after deploy, when it costs a follow-up PR and a red-faced changelog entry.

The trade-offs worth knowing

Build minutes and latency. Every push to an open pull request consumes a build. On plans with limited build minutes, a busy repository with frequent doc edits can burn through quota faster than expected. Large documentation sets also mean each preview takes minutes to render, so the feedback loop is slower than a unit test run. Check your plan's current limits before enabling this on a high-traffic repo.

Preview URLs are unlisted, not secret. The preview link can be forwarded to anyone. Never put credentials, unreleased internal details, or embargoed information in documentation that gets built in previews.

Green does not mean correct. A successful build proves the docs render, not that the content is accurate. The preview helps reviewers judge readability and catch structural errors; it does not replace actually reading the words.

How to verify it works

Set it up on a test branch first. Open a pull request that makes a trivial docs change — add a sentence to one page. Then confirm three things: a Read the Docs status check appears on the pull request, the Details link opens a rendered preview showing your new sentence, and your public latest documentation does not show the change. Push a second commit and confirm the check re-runs and the preview updates. If all four hold, you can trust the check in real reviews.

If your team reviews documentation changes by reading raw diffs today, enabling pull request builds is one of the cheapest review-quality upgrades available: a config file you probably already have, one dashboard setting, and no CI plumbing. Turn it on for one repository, run it for a sprint, and count how many red checks catch something a diff review would have missed.