# Share a Docusaurus Build — Review the Docs Before They Ship

Canonical: https://commareports.com/share-docusaurus-site
Published: 2026-08-29

> npm run build gives you a build/ folder and a hosting decision. Publish it as a link instead: the real site at a URL, comments anchored to the paragraph that is wrong, no deploy preview needed.

# Share a Docusaurus build

`npm run build` produces a real site in `build/`. Getting anyone to look
at it before it is deployed is the hard part.

The standard answer is a deploy preview, which is excellent when you have
one. Plenty of docs changes don't: the contribution from someone without
deploy rights, the repo whose preview pipeline was never set up, the
rewrite you want three people to read before it becomes the public site.

The fallback is `npm run serve` on your laptop and a screen share.

## Build it

```bash
npm run build     # → build/
```

```
build/
├── index.html
├── docs/…/index.html      # one page per route
├── assets/js/  assets/css/
└── img/  sitemap.xml
```

## Drop the folder in

Drag `build/` (or a zip of it) into [Comma](https://commareports.com/):

- `index.html` becomes the **report body** — the page carrying the comment
  layer.
- The route pages, JS bundles, CSS and images upload alongside it, and
  relative references are rewritten to the uploaded copies.
- Scripts run inside a sandboxed iframe (`allow-scripts`, no
  `allow-same-origin`), so Docusaurus hydrates: the sidebar, the theme
  toggle, tabs and in-page navigation all work.

Build with `baseUrl: '/'` for the copy you publish — a root-relative build
is the one whose references resolve cleanly after rewriting.

## From CI, for a per-branch preview

```bash
npm run build

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/index.html \
        --arg title "Docs — $(git rev-parse --abbrev-ref HEAD)" \
        '{title: $title, html: $html}')"
```

The API is JSON-only, so the route pages and bundles 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](/docs/ci).

## Why review the built site, not the markdown diff

A markdown diff shows you the words changed. It does not show you:

- The admonition that renders as a wall of grey because the nesting is off.
- The code tabs where one language block is missing.
- The 900-word page that is unreadable at the width the theme gives it.
- The link that resolves in the source tree and 404s in the build.

Those are visible in the built site and invisible in the PR — which is why
docs review that only happens on the diff keeps shipping them.

Once the build has a URL, review happens **on the rendered page**. Select
the stale example, leave a thread, and it stays anchored there across
rebuilds. See [commenting on HTML](/comment-on-html).

## Who can see it

Per report: private, your team, anyone signed in at your domain, or anyone
with the link. A pre-launch docs rewrite gets a link-only URL for the
reviewers and nothing more. See
[sharing & access control](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** Assets: 25 MB per file, **250 MB and 500 files
  total**. A large docs site exceeds 500 files easily — publish the
  section under review rather than the whole build, which is also a
  kinder thing to hand a reviewer.
- **Deep links** into nested routes are the case to watch; publish the
  entry page and navigate from there.
- **60 requests/minute per token.**

## Try it

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

**[Publish a docs build →](https://commareports.com/)**

### Related

- [Share a MkDocs site](/share-mkdocs-site) · [Share Sphinx docs](/share-sphinx-docs)
- [Share TypeDoc output](/share-typedoc) · [Share OpenAPI docs](/share-openapi-docs)
- [Share a Storybook build](/share-storybook-static)
- [Vercel alternatives](/alternatives/vercel-alternatives) · [GitHub Pages alternatives](/alternatives/github-pages-alternatives)