# Share an mdBook — Publish book/ Without a Static Host

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

> mdbook build writes book/ with a search index it loads at runtime. Publish the folder to Comma for a URL where navigation, search and themes work.

# 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

```bash
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](https://commareports.com/):

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

```bash
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](/docs/api) 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](/comment-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](/docs/sharing).

## 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 →](https://commareports.com/)**

### Related

- [Share rustdoc](/share-rustdoc) · [Share a Rust coverage report](/share-rust-coverage-report)
- [Share an MkDocs site](/share-mkdocs-site) · [Share a VitePress site](/share-vitepress-site)
- [Share Sphinx docs](/share-sphinx-docs) · [Commenting on HTML](/comment-on-html)