# Share an Antora Docs Site — Preview a Multi-Repo Build

Canonical: https://commareports.com/share-antora-docs
Published: 2026-08-31

> Antora assembles docs from many repos into one site, which means nobody can preview their change without running the whole build. Publish build/site as a link and review the assembled result.

# 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

```bash
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](https://commareports.com/):

- `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:

```yaml
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

```bash
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](/docs/api) and
[publishing from CI](/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](/comment-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](/docs/sharing).

## 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 →](https://commareports.com/)**

### Related

- [Share a Docusaurus site](/share-docusaurus-site) · [Share a MkDocs site](/share-mkdocs-site)
- [Share Sphinx docs](/share-sphinx-docs) · [Share OpenAPI docs](/share-openapi-docs)
- [Share Javadoc](/share-javadoc) · [Share a Maven site report](/share-maven-site-report)
- [GitHub Pages alternatives](/alternatives/github-pages-alternatives)