How do I share a Docusaurus build without deploying it?

Run `npm run build` and drop the `build/` folder into Comma. `index.html` becomes the report body and the routes, JS bundles, CSS and images upload alongside it, so the site runs at a URL with no hosting and no deploy preview to configure.

Does client-side routing work in the published build?

In-page navigation works because Docusaurus hydrates and takes over routing after load. Deep-linking straight to a nested route is the case to watch — publish the entry page and navigate from there, which is how a review of a docs change works anyway.

Why not just use a Netlify or Vercel deploy preview?

Use one if you already have it. This is for the cases where you don't: a docs change from someone without deploy rights, a repo with no preview pipeline, or a build you want reviewed privately before the site is public. It also takes anchored comments, which a deploy preview does not.

Can reviewers comment on the docs?

Yes — select the paragraph and leave a thread. It stays anchored to that passage across rebuilds, so 'this example is out of date' lands on the example rather than in a PR conversation that gets resolved and forgotten.

Can I set baseUrl correctly for the published copy?

Build with `baseUrl: '/'` for the copy you publish. Relative asset references are rewritten to the uploaded copies on upload, so a root-relative build is the one that resolves cleanly.

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

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:

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

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 and publishing from 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.

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.

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 →