# Share a VitePress Build — Docs Preview at a Link

Canonical: https://commareports.com/share-vitepress-site
Published: 2026-08-31

> vitepress build writes an SPA under .vitepress/dist. Publish it to Comma for a preview URL where the sidebar, search and theme toggle all work.

# Share a VitePress build

VitePress builds a single-page app: `docs/.vitepress/dist/` with an
`index.html`, a client router and hashed bundles under `assets/`. Open the
`index.html` from disk and you get a blank page, because those bundle
references start with `/` and at a `file://` origin that means your
filesystem root.

`vitepress preview` fixes it for the person who ran the build. Docs reviews
involve other people.

## Build

```bash
npx vitepress build docs      # → docs/.vitepress/dist/
```

If the docs deploy under a subpath, declare it so the emitted references match:

```js
// docs/.vitepress/config.ts
export default { base: "/docs/" };
```

## Publish dist/

Drag `docs/.vitepress/dist/` (or a zip of it) into
[the app](https://commareports.com/):

- `index.html` becomes the **report body**.
- The `assets/` bundles, fonts, images and the local search index upload as
  assets, and their references are rewritten to the uploaded copies.
- Scripts run inside a sandboxed iframe (`allow-scripts`, no
  `allow-same-origin`), so the sidebar, the theme toggle and local search work.

A docs preview URL with no deploy and nothing to tear down.

## Per-branch previews

```bash
npx vitepress build docs

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 docs/.vitepress/dist/index.html \
        --arg title "Docs preview — $GITHUB_HEAD_REF" \
        '{title: $title, html: $html}')"
```

One report id per branch. PATCH on every push and the reviewer's link always
shows the current build, with earlier builds kept as revisions.

## What review adds

Docs review is copy review, and copy review needs to happen on the rendered
page — not on the markdown diff, where nobody can see the heading hierarchy or
the code sample in context.

- **Anchored threads** on the paragraph. See
  [commenting on HTML](/comment-on-html).
- **Revisions**, so the edit round-trip is verifiable.
- **Access per report** — private, team, domain-gated, or named reviewers.
  See the [sharing model](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** Assets: 25 MB per file, 250 MB and 500 files total.
  A large docs site can approach the 500-file cap — publish the section under
  review rather than the whole site.
- **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 an mdBook](/share-mdbook)
- [Share an MkDocs site](/share-mkdocs-site) · [Share Sphinx docs](/share-sphinx-docs)
- [Share an Astro build](/share-astro-site) · [Commenting on HTML](/comment-on-html)