How do I share a VitePress build?

Run `npx vitepress build docs`, then drag `docs/.vitepress/dist/` into Comma. `index.html` becomes the report body and the `assets/` bundles upload alongside it with references rewritten.

Why doesn't the built site work from the filesystem?

VitePress ships a client-side router and references its bundles absolutely under `/assets/`. At a `file://` origin those paths resolve against your filesystem root, so the page loads blank. Served over HTTP with the assets alongside, it works.

Does the local search still work?

Yes when the search index ships with the build — it uploads as an asset with the rest of `dist/` and its reference is rewritten. Algolia-backed search depends on the external service and is unaffected either way.

Can I preview docs for an unmerged branch?

Yes. One report id per branch, PATCHed on each push, gives every docs PR a stable private preview link without a deploy or a preview environment.

Can reviewers comment on the docs copy?

Yes. Anchored threads sit on the paragraph, so an edit request lands on the sentence rather than being described in a PR comment by line number of the source markdown.

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

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

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

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

Publish dist/

Drag docs/.vitepress/dist/ (or a zip of it) into the app:

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

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.
Revisions, so the edit round-trip is verifiable.
Access per report — private, team, domain-gated, or named reviewers. See the sharing model.

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 →