How do I get a preview link for a docs branch?

Publish the built site from CI on each push to the docs branch, updating the same report. Reviewers open a URL that always shows the current build instead of checking out the branch and running the static site generator.

Why not just have reviewers read the markdown diff?

Because subject-matter experts review meaning, not syntax, and a diff hides the rendered result — the admonition that didn't render, the table that wrapped, the code sample that lost its highlighting. They need the page as a reader will see it.

Can reviewers comment on a specific paragraph?

Yes. Comments anchor to the block they're about, so 'this flag was removed in 3.2' stays attached to that sentence rather than arriving as a list of page-and-paragraph references.

Does search still work in a published docs build?

Client-side search that ships as part of the build — MkDocs Material, Docusaurus, VitePress — works, because scripts run in a sandboxed iframe and the index is part of the published folder. Search that calls an external service depends on that service allowing the origin.

Do I have to publish the whole site?

Publish the whole output directory when links between pages matter. For a single new page under review, publishing just that page is often the faster review.

Reviews that happen before the merge

Docs review has a structural problem: the people whose approval matters — the engineer who built the feature, the support lead who will field the tickets, the PM who named it — will not check out a branch and run mkdocs serve. So they review the published site, after it ships, by sending you a list of corrections.

The fix isn't process. It's giving them a URL.

Publish the build, per branch

Add a step to the docs pipeline that publishes the built site and updates the same report each push, so the preview link in the PR description is always current:

mkdocs build
curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$DOCS_PREVIEW_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @site.json

Publish the whole output folder — docs sites are the clearest case for it, since cross-page links, the search index, the stylesheet and the fonts all live beside the entry file. See share an HTML folder.

Per-generator detail: MkDocs · Sphinx · Docusaurus · VitePress · Antora · mdBook · Jupyter Book · Bookdown · Quarto · Hugo · Jekyll · Eleventy · AsciiDoc · Pandoc.

API reference builds: OpenAPI · Redoc · Swagger UI · Javadoc · JSDoc · TypeDoc · rustdoc · Doxygen · Dokka · phpDocumentor · YARD · pkgdown.

Anchored comments are the whole point

A reviewer's most valuable contribution is a correction attached to a sentence: "this flag was removed in 3.2", "this order is wrong, you have to authenticate first", "nobody calls it that internally".

Sent as an email, that becomes a scavenger hunt. Left as an anchored comment, it's a queue you work through with the text in front of you. See commenting on HTML.

Reviewers need no account, no editor, no local toolchain, and they are never billed — which is what makes it realistic to ask three SMEs instead of one.

Revisions are the review round

Each redraft is a revision at the same URL. The PR link doesn't change, the reviewer refreshes, and the history shows what moved between rounds — useful when someone asks whether their week-one comment was ever addressed.

If a docs agent is drafting, it can read the open threads and revise against them directly — see letting an agent respond to comments.

Worth knowing

Start private. Unreleased feature docs are an embargo problem before they're a review problem — see sharing & access control.
Search behaviour. Bundled client-side search (MkDocs Material, Docusaurus, VitePress) works. Hosted search that calls an external service depends on that service's origin rules.
Limits. Entry HTML 5 MB; assets 25 MB per file, 250 MB and 500 files per report. A large API reference with per-symbol pages is the usual file-count offender — publish the section under review rather than the entire build.
Keep the real docs site. This is a review surface, not a replacement for publishing.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Start free →