# Share a VuePress Site — A Docs Preview Without a Deploy

Canonical: https://commareports.com/share-vuepress-site
Published: 2026-09-15

> vuepress build writes .vuepress/dist, which needs a server to browse. Publish the folder to Comma for a per-branch docs preview with comments on the rendered page.

# Share a VuePress site

VuePress builds a static site and the natural next thought is "static means I
can just open it". It doesn't. `vuepress build` emits a `dist/` folder that
expects to be served from a root: the asset URLs are absolute, and the
client-side router needs a server to hand it `index.html` for paths that have
no file behind them.

Double-click `index.html` and you get an unstyled page, or nothing.

## Build it

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

## Publish the folder

Drag `docs/.vuepress/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 search work.

From CI, per branch:

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

One id per branch. Nothing to provision, nothing to tear down when the branch
is deleted.

## Why review on the build and not the diff

Documentation changes are copy changes, and copy review needs the rendered
page — the heading hierarchy, the code block in context, the callout that
looked fine in markdown and is shouting in the theme.

- **Anchored threads** on the paragraph. See
  [commenting on HTML](/comment-on-html).
- **Revisions**, so the second draft can be compared with the first.
- **Access per report** — private, team, domain-gated, or named reviewers,
  which matters when the docs are not public yet. 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 VitePress site](/share-vitepress-site) · [Share a Docsify site](/share-docsify-site)
- [Share a Docusaurus site](/share-docusaurus-site) · [Share a MkDocs site](/share-mkdocs-site)
- [Share an HTML folder](/share-html-folder) · [Publish from CI](/docs/ci)