How do I share an mdBook without hosting it?

Run `mdbook build`, then drag `book/` into Comma. `index.html` becomes the report body and the chapter pages, theme CSS, JS and search index upload alongside it with references rewritten.

Why doesn't mdBook's search work when I open the file directly?

The search index loads as a separate request at page load, and browsers block that from `file://` origins — so the box is there and finds nothing. Served over HTTP the request succeeds.

Can I share a draft chapter for review?

Yes. Build the branch, publish to a private report, and share it with named reviewers. Nothing goes to the live book until you merge.

How do I keep one link across builds?

PATCH the same report id from CI. The URL stays stable and each build appends a revision, so a reviewer's link never goes stale and edits are diffable.

Do the theme toggle and keyboard navigation work?

Yes. Report HTML renders with scripts enabled inside a sandboxed iframe, so the theme picker, the sidebar and the arrow-key chapter navigation behave.

Share an mdBook

mdBook is what the Rust ecosystem writes long-form documentation in, and mdbook build gives you book/ — chapter pages, a sidebar, a theme picker, and full-text search. The search is the part that breaks when you hand somebody the folder: the index loads as a separate request, and a file:// origin refuses it. The box renders, types, and finds nothing.

Build

mdbook build          # → book/

For a draft review, build the branch you are on — nothing needs to be merged or deployed first.

Publish the folder

Drag book/ (or a zip of it) into the app:

index.html becomes the report body.
Chapter pages, css/, FontAwesome/, highlight.js, and the search index upload as assets, and their references are rewritten to the uploaded copies — including the search request that fails at file://.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so search, the theme toggle and keyboard navigation work.

From CI

mdbook build

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 book/index.html \
        --arg title "Book — $GITHUB_REF_NAME" '{title: $title, html: $html}')"

PATCH one report id per book: a stable URL, a revision per build. See the API docs for uploading the rest of the folder as assets.

What review adds

Long-form docs get reviewed as prose, and prose review needs to happen on the rendered page:

Anchored threads on the paragraph — an edit attached to the sentence instead of a source line number. See commenting on HTML.
Revisions, so an editing pass is visible as a diff between builds.
Access per report — private for an unreleased chapter, opened up when it ships. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A very long book with per-chapter images can approach the file cap.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish a docs preview →