How do I share a Starlight build without deploying it?

Run `npx astro build` and publish `dist/` as a bundle. You get an HTTPS URL with the sidebar, search and every sub-page working, and no deploy to production.

Does Starlight's search work in the preview?

Yes. Pagefind's index is written into dist/ at build time and served from the same origin as the pages, so search resolves.

Why does opening dist/index.html directly look broken?

Starlight references its assets absolutely under `/_astro/`, which at a `file://` origin resolves against your filesystem root. Over HTTP with the bundle uploaded, the paths resolve.

Can each docs PR get its own link?

Use one report id per branch and PATCH it on every push. The PR keeps a stable URL that always shows the current build, with earlier builds kept as revisions.

Can a writer comment on a specific paragraph?

Yes — threads anchor to the selected text on the rendered page, which is the whole point for docs review.

Share a Starlight docs site

Starlight gives you a docs site that is genuinely pleasant on the first build: sidebar, search, dark mode, code tabs. Then you need a technical writer, a PM and one engineer to read a six-page section before it ships — and the only copies are localhost:4321 and production.

Build

npx astro build
# → dist/

Opening dist/index.html from Finder shows unstyled markup: Starlight references its bundles absolutely under /_astro/…, and at a file:// origin that resolves against your filesystem root, not against dist/. This is the same failure as a shared report with no CSS.

Publish dist/

Drag the folder into the app, or zip and POST it:

cd dist && zip -qr ../docs.zip . && cd ..

curl -fsS -X POST https://commareports.com/api/v1/reports \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -F "title=Docs — $(git rev-parse --abbrev-ref HEAD)" \
  -F "visibility=team" \
  -F "bundle=@docs.zip"

cd into dist first. Zipping the parent nests everything a level deeper, so there is no index.html at the archive root and the entry point 404s — see sharing a folder of HTML files.

Why a review link beats a staging deploy

Anchored threads — "this step is out of order" sits on the paragraph, not in a doc of numbered nits. See commenting on HTML.
Revisions at one URL — PATCH the same id per branch and the link in the PR never goes stale.
Access per report — private, team-only, domain-gated, or an unlisted link for an external reviewer. See the sharing model.
No production risk — unreleased docs stay out of your sitemap and out of search, which a staging subdomain frequently does not.

Limits

Assets: 25 MB per file, 250 MB and 500 files per report. A large docs site with many images and a Pagefind index can reach the file count; prune dist/ of source maps before zipping.
Entry HTML: 5 MB.
60 requests/minute per token.

Try it

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

Publish a docs preview →