Why does my VuePress build look broken when opened from disk?

The build assumes a server root. Opened via `file://`, absolute asset paths resolve against the filesystem root and the client-side router cannot match routes, so styles and navigation fail.

What do I publish — the folder or the file?

The folder. `.vuepress/dist/index.html` is the entry; the `assets/` bundles, fonts and the search index need to travel with it.

Does client-side routing work at the URL?

Scripts run inside a sandboxed iframe, so the router and the theme behave. Deep links to a sub-path are the exception — share the entry URL and let the reader navigate from there.

Can I do this per pull request?

Yes — one report id per branch, PATCHed on each push. The reviewer's link always shows the current build, with earlier builds kept as revisions.

Is this a replacement for hosting the docs?

No. It is a replacement for the preview deploy — the throwaway environment you provision so somebody can read a change before it merges.

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

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

Publish the folder

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

From CI, per branch:

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.
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.

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 →