# Share a Starlight Docs Site — A Preview Link Before You Deploy

Canonical: https://commareports.com/share-starlight-docs
Published: 2026-09-12

> Astro Starlight builds to dist/ with search, sidebar and dark mode. Publish the folder to Comma for a preview URL where reviewers can comment on the page instead of on a screenshot.

# 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

```bash
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](/html-report-broken-css).

## Publish dist/

Drag the folder into [the app](https://commareports.com/), or zip and POST it:

```bash
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](/share-html-folder).

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

### Related

- [Share an Astro site](/share-astro-site) · [Share a Mintlify docs site](/share-mintlify-docs)
- [Share a Nextra site](/share-nextra-site) · [Share an MkDocs site](/share-mkdocs-site)
- [Share a folder of HTML files](/share-html-folder) · [For technical writers](/for/technical-writers)