# Previewing Docs for Every Pull Request vs Publishing Only from the Main Branch

## Quick answer

If docs are generated from a spec, every pull request should produce a preview build that reviewers can open before the change merges. Publishing only from the main branch means reviewers either approve a documentation change sight unseen or build locally, and most will simply approve. A per-pull-request preview makes the rendered result, including tables, code blocks, and the try-it console, part of the review and catches broken markup and bad examples before they reach production. Treat the preview as a standard CI artifact tied to the pull request, and keep the production publish strictly on the main branch so the two paths never blur.

## What a preview workflow gives you

When a spec change is pushed, CI builds the docs and posts a unique URL that reflects that exact branch.

Reviewers click a link and see the rendered page as it would appear, rather than reading raw YAML or Markdown and imagining the result. Each new commit rebuilds the preview, so the link always matches the latest state of the branch.

## Why review needs the rendered output

Source text and rendered documentation are different artifacts. A spec can be valid while the generated output has a broken table, a code block that overflows, a duplicated heading anchor, or an example that renders incorrectly. None of that is obvious from the source diff. Without a preview, these defects survive review and are discovered only after the main branch publish, when fixing them means another production change. The preview moves that discovery left, into the same place the change is already being reviewed.

| Review concern | Source diff only | Preview build |
| --- | --- | --- |
| Rendered tables and code blocks | Hard to judge | Visible directly |
| Broken internal links or anchors | Not obvious | Clickable and checked |
| Try-it console behavior | Cannot be exercised | Runnable in the preview |
| Layout and overflow | Invisible | Rendered as in production |
| Spec correctness | Good | Good, plus the output |

## Versioned docs and multi-API previews

Previewing gets more valuable, and a little more complex, when the docs cover multiple API versions or several services in one repository. A pull request that changes a shared component or a style rule can affect every version that reuses it, so the preview should let reviewers switch between the affected versions rather than showing only the default one. In a monorepo, scope the build to the services the branch actually touches so the preview stays fast and the output makes the blast radius obvious. The practical risk here is a change that is correct for the newest API but silently breaks an older supported version, which a single-version preview would never reveal. Build the preview against the same version matrix the production publish uses, and have the CI link check run across each version. When a pull request only touches one service, the preview can still render the others unchanged, which helps reviewers confirm the shared layout did not regress. Treating the preview as a faithful, version-aware copy of production is what lets it catch these cross-version problems before the merge.

## Keeping preview and production separate

The two paths should be explicit and non-overlapping. Preview builds are keyed to the branch and can be replaced or discarded as the pull request evolves; production is published only when the merge lands on the main branch. Use a separate preview host or a clearly namespaced path, and avoid indexing preview URLs so they do not leak into search or compete with the canonical docs. Automated cleanup of previews after the branch is merged keeps the preview store from accumulating stale content.

## Automating checks inside the preview build

The same CI job that builds the preview can run the mechanical validation a human would otherwise do manually. Check that every internal link resolves, run the linter against the spec, and optionally crawl the preview to confirm there are no broken anchors or missing assets. Because the preview is a real rendered site, a script can assert the expected pages exist and the navigation works. The human reviewer then focuses on whether the content is accurate and the examples are good, while the tooling owns the structural checks.

## Handling the review expectation

A preview URL only helps if reviewers actually open it. Make the expectation explicit in the pull request template: the preview link is a required part of reviewing a docs change, and approval implies the rendered output was checked. For substantial changes, ask the author to point to the specific pages affected so reviewers do not have to guess. When the spec and generated output live in the same repository, the diff and the preview together give both the exact change and its rendered result, which is a much stronger review than either alone.

## FAQ

### Does every tiny change need a full preview build?

The build can run for every docs change automatically, since CI does the work, but reviewers can spend less attention on trivial edits. Keeping the workflow uniform avoids special-casing and guarantees the preview exists whenever a change genuinely needs it.

### Should preview sites be publicly accessible?

That depends on the project. For open-source docs a public preview is convenient; for private content, place previews behind authentication. In either case, keep them out of search indexes and clearly separate from production.

### What happens to old previews after merge?

Automate their cleanup once the branch is merged or deleted, so the preview host reflects only open work. The production publish on merge becomes the authoritative version.

### Can't reviewers just build the docs locally?

They can, but most will not, and local environments differ from CI. A hosted preview removes that friction and guarantees everyone sees the same rendered result, which is why it should be a CI responsibility rather than a manual step.

This is part of the [Powerduck vs Redocly: OpenAPI Docs and Linting](https://www.powerduck.com/blog/powerduck-vs-redocly/) — start there for the full picture of a docs pipeline that is reviewed before it ships.