# Share a Jupyter Book — Publish the Built Site as a Link

Canonical: https://commareports.com/share-jupyter-book
Published: 2026-08-30

> jupyter-book build produces _build/html and then asks you to deploy it. Publish it in one drag instead: the whole book at a URL, search working, and comments anchored to the paragraph.

# Share a Jupyter Book

Jupyter Book turns a folder of notebooks and markdown into a real
publication — chapters, cross-references, citations, executed outputs.
`jupyter-book build .` produces `_build/html/`, and then the docs hand you
a deployment problem: set up `ghp-import`, or a Pages action, or Netlify.

For a book that should be public and permanent, do that. For the ones that
shouldn't — a draft under review, an internal methods document, a
deliverable for a client — the deployment step is out of proportion to the
need, and it is where most books quietly stop.

## Build it

```bash
jupyter-book build .
# → _build/html/index.html
```

```
_build/html/
├── index.html
├── chapters/…/analysis.html    # one page per notebook or md file
├── _static/                    # css, js, the search index
├── _images/                    # figures from executed cells
└── searchindex.js
```

## Drop the folder in

Drag `_build/html/` (or a zip of it) into
[Comma](https://commareports.com/):

- `index.html` becomes the **report body** — the page carrying the comment
  layer.
- Chapter pages, `_static/`, `_images/` and the search index upload
  alongside it, with relative references rewritten to the uploaded copies.
- Scripts run inside a sandboxed iframe (`allow-scripts`, no
  `allow-same-origin`), so search, the sidebar, the collapsible code cells
  and the copy-button all work.

One URL, no Pages workflow, no bucket.

## What survives and what doesn't

Worth being precise, because "interactive notebook" covers two very
different things:

- **Survives:** matplotlib and seaborn figures, Plotly / Bokeh / Altair
  output embedded at build time, rendered dataframes, MyST directives,
  citations and cross-references. These are all baked into the HTML.
- **Doesn't:** anything needing a live Python kernel — ipywidgets bound to
  callbacks, `interact` sliders. That's a property of static HTML, not of
  where you host it; the same book on Pages behaves identically.

If a chapter needs a kernel, link out to Binder or Colab from it, which is
what Jupyter Book's launch buttons already do.

## From CI, for a per-branch draft

```bash
jupyter-book 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 _build/html/index.html \
        --arg title "Methods — $(git rev-parse --abbrev-ref HEAD)" \
        '{title: $title, html: $html}')"
```

The API is JSON-only, so the chapter pages and figures go up through
`POST /api/v1/reports/$REPORT_ID/assets` as base64 — one call per file,
worth scripting once. See the [API reference](/docs/api) and
[publishing from CI](/ci).

`PATCH`ing a saved id keeps one URL with a revision per build, so a book
that regenerates when the data updates always has one current address.

## Review on the prose, not in email

A book is written to be argued with, and the arguments are specific:
this assumption, that figure, this cohort definition. In the normal flow
they arrive as an email listing "section 3.2, paragraph 4."

Published, they land **on the paragraph**. Select it, leave a thread, and
it stays anchored across rebuilds — so the objection and the sentence it
concerns stay together. See [commenting on HTML](/comment-on-html).

## Who can see it

Per report: private, your team, any signed-in user with the link, or
public. A draft gets a link-only URL for the reviewers; an internal
methods document gets a team report. Domain-gating, password gates and
expiring links are Enterprise. See
[sharing & access control](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** Assets: 25 MB per file, **250 MB and 500 files
  total**. A long book with many executed figures can approach the file
  count — publish the section under review rather than the whole book.
- **Scripts run, sandboxed** — no same-origin access.
- **60 requests/minute per token.**

## Try it

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

**[Publish a book →](https://commareports.com/)**

### Related

- [Share a Jupyter notebook](/share-jupyter-notebook-html) · [with Jupyter](/with/jupyter)
- [Share Sphinx docs](/share-sphinx-docs) · [Share a MkDocs site](/share-mkdocs-site)
- [Share an RMarkdown report](/share-rmarkdown-report) · [with Quarto](/with/quarto)
- [nbviewer alternatives](/alternatives/nbviewer-alternatives)