How do I preview an Antora site without deploying it?

Run `antora antora-playbook.yml` and drop the resulting `build/site/` directory into Comma. `index.html` becomes the report body and the component pages, UI bundle and search index upload alongside it, so the assembled site works at a URL.

Why is previewing an Antora change harder than other docs tools?

Because the unit of publication is the whole site, assembled from several content repositories at specific branches. A contributor editing one AsciiDoc file in one repo cannot see their change in context without running the full playbook, which needs every source repo reachable.

Does the site's search work at the published URL?

If you build with a search extension that bundles a client-side index — Lunr is the common choice — yes, since Comma renders report HTML with scripts enabled inside a sandboxed iframe. Search backends that call an external service will not resolve from the sandbox.

Can reviewers comment on the built pages?

Yes. Select the paragraph and leave an anchored thread; it stays attached across rebuilds. That is a better fit for docs review than a pull request comment, because the reviewer sees the assembled page rather than AsciiDoc source.

Is an Antora site too big to publish?

It can be. A report holds 500 assets and a multi-component site with several versions exceeds that. Build a playbook scoped to the component under review — which is faster anyway — rather than the full production site.

Share an Antora docs site

Antora's strength is also what makes it awkward to review: the unit of publication is the whole site, assembled from several content repositories at particular branches, through one playbook.

Which means a contributor who edits one AsciiDoc page in one repo cannot see their change in context without running the full build — and the full build needs every source repo reachable, at the right refs, on their machine.

So Antora changes get reviewed as AsciiDoc diffs in a pull request, which is where the broken cross-reference, the partial include and the nav entry pointing at a page that moved all survive untouched.

Build it

npx antora antora-playbook.yml
# → build/site/index.html

build/site/
├── index.html
├── component/version/page.html   # one page per topic, per version
├── _/                            # the UI bundle: css, js, fonts
└── search-index.js               # if a search extension is configured

Drop the folder in

Drag build/site/ (or a zip) into Comma:

index.html becomes the report body — the page carrying the comment layer.
Component pages, the _/ UI bundle and the search index upload alongside it, with relative references rewritten to the uploaded copies.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the nav tree, the version selector and a Lunr-style client-side search keep working.

A search backend that calls an external service won't resolve from the sandbox — client-side indexes are the ones that survive.

Scope the playbook for review builds

This is the practical bit. A production Antora site with several components across several versions runs past the 500-asset limit without effort.

Keep a second playbook for previews:

content:
  sources:
    - url: ./ # just the repo being changed
      branches: HEAD
      start_path: docs

That builds in seconds instead of minutes, publishes comfortably, and shows the contributor exactly the pages they touched. The full-site build stays where it belongs — in the deploy pipeline.

From CI, a preview per branch

npx antora preview-playbook.yml

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html build/site/index.html \
        --arg title "Docs preview — $(git rev-parse --abbrev-ref HEAD)" \
        '{title: $title, html: $html}')"

The API is JSON-only, so the component pages and UI bundle go up through POST /api/v1/reports/$REPORT_ID/assets as base64 — one call per file, worth scripting once. See the API reference and publishing from CI.

What a built preview catches that a diff doesn't

Specific to Antora, and specific to why this is worth the setup:

Broken xrefs across components. The syntax is valid; the target moved to another repo. Only the assembled build knows.
Includes that resolved to nothing because the partial lives at a different start_path.
Nav entries pointing at pages that no longer exist, which render as a dead sidebar link and nothing else.
Version-selector surprises when a page exists in one version and not the next.

None of these appear in an AsciiDoc diff. All of them appear immediately in the built site.

Review on the page

Once the preview has a URL, review happens on the rendered page rather than on source. Select the paragraph, leave a thread, and it stays anchored there across rebuilds — so "this procedure is missing the prerequisite" lands on the procedure. See commenting on HTML.

For a technical writer reviewing an engineer's contribution, that is a considerably better instrument than commenting on AsciiDoc markup.

Who can see it

Per report: private, your team, any signed-in user with the link, or public. A pre-release docs build gets a link-only URL for reviewers. Domain-gating, password gates and expiring links are Enterprise. See sharing & access control.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total — scope the preview playbook accordingly.
Scripts run, sandboxed — no same-origin access.
60 requests/minute per token.

Try it

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

Publish a docs preview →