marimo-book

Build clean, searchable static books from marimo notebooks and Markdown files.

marimo-book is a Jupyter-Book-style static site generator built specifically for marimo .py notebooks. It produces polished multi-page sites with:

Anywidgets that render statically — interactive Canvas/Three.js/Plotly widgets without a marimo kernel
Static reactivity for discrete sliders (mo.ui.slider with explicit steps) — pre-rendered lookup tables, no kernel
WASM render mode per chapter — opt into Pyodide-driven full reactivity for chapters that need it
Material for MkDocs theming — full-text search, dark mode, code-copy, breadcrumbs, responsive layout
Launch buttons per chapter — molab / GitHub / download .py
Incremental build cache — content-hashed; only changed chapters re-render
GitHub Pages deploy workflow scaffolded by marimo-book new

Status

Alpha (0.1.x). Used in production by at least one real course (dartbrains.org). The book.yml schema is stable for v0.1; pin a minor version (marimo-book>=0.1.5,<0.2) until 1.0. Major changes always go through a new minor version.

Install

pip install marimo-book

Requires Python 3.11+. Optional extras for opt-in features:

pip install 'marimo-book[social]'      # OpenGraph card generation (libcairo)
pip install 'marimo-book[linkcheck]'   # external-link verification (htmlproofer)
pip install 'marimo-book[pdf]'         # single-PDF export (WeasyPrint)

mkdocs-autorefs (cross-page heading references) ships in the base install — flip cross_references: true in book.yml to enable.

Quickstart

# Scaffold a new book
marimo-book new mybook
cd mybook

# Live-reload dev server (http://127.0.0.1:8000/)
marimo-book serve

# One-shot static build (emits ./_site/)
marimo-book build

# Validate book.yml + content without building
marimo-book check

# Remove build artifacts
marimo-book clean

Deploy to GitHub Pages by pushing the scaffolded workflow (.github/workflows/deploy.yml) to the default branch on a repo with Pages enabled.

How it works

Two-stage build, by design:

content/*.md + *.py + book.yml
  → marimo-book preprocessor
  → _site_src/docs/*.md  +  _site_src/mkdocs.yml
  → mkdocs build (Material theme)
  → _site/

The preprocessor is not a mkdocs plugin — it emits plain Markdown + inline HTML. This keeps the shell swappable: Material today, zensical (Material's Rust successor) tomorrow, or a hand-rolled Jinja shell as a last-resort fallback.

For each marimo .py it runs marimo export ipynb --include-outputs and translates the cells into Markdown + inline HTML — embedding Plotly figures, anywidget mounts, and matplotlib renders directly. For WASM-mode chapters, it routes through marimo's MarimoIslandGenerator and ships marimo's runtime + Pyodide bundle.

`book.yml` minimal example

title: My Book
description: A static site from marimo notebooks + Markdown.
authors:
  - name: Your Name
repo: https://github.com/you/yourbook

theme:
  palette:
    primary: "#1976D2"

launch_buttons:
  molab: true
  github: true
  download: true

# Static reactivity for discrete mo.ui widgets
precompute:
  enabled: true

toc:
  - file: content/intro.md
  - section: Chapters
    children:
      - file: content/chapter1.py
      - file: content/chapter2.py
        mode: wasm           # this one runs in Pyodide for full reactivity

See marimo-book new for the full starter template, and the book.yml reference for every field.

Notebook dependencies

book.yml picks one of two modes:

env (default): re-use the active venv. Pin notebook deps in your book root's pyproject.toml. Fast.
sandbox: pass --sandbox to marimo export. Each notebook declares its own deps via PEP 723 inline metadata; marimo provisions per-notebook envs via uv. Slower on first run; portable.

Override per invocation with --sandbox / --no-sandbox on build or serve.

Build cache

A content-addressed cache at {book_root}/.marimo_book_cache/ skips re-rendering chapters whose source + book.yml-relevant fields haven't changed. Typical incremental rebuilds drop from 100+ s to ~3 s on real-world books. Reset with marimo-book clean or override per invocation with marimo-book build --rebuild. CI runners get warm cache reuse via actions/cache@v4.

Broken-link checking

marimo-book build --strict fails on broken in-tree links and anchors (use this on CI). For external URL and image src validation, opt into htmlproofer:

# book.yml
check_external_links: true

pip install 'marimo-book[linkcheck]'
marimo-book build --strict

External link checking hits the live web (~1–3 s per link), so we recommend gating it behind a release-cutting workflow rather than running on every PR.

License

MIT

Metadata

Release files for marimo-book 0.1.31

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for marimo-book 0.1.31
File	Size	Uploaded
marimo_book-0.1.31.tar.gz	330.5 kB	Sep 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for marimo-book 0.1.31
File	Interpreter	ABI	Platform	Reset
marimo_book-0.1.31-py3-none-any.whl 153.0 kB Sep 11, 2026	Python 3	none	any	Details

Total release size: 483.5 kB

Release files / marimo_book-0.1.31.tar.gz

Download URL	marimo_book-0.1.31.tar.gz
Size	330.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`0054c47e417bda6f92c5298d53d507d4772420b632a0d730a3c1301a51373fc7`
BLAKE2b-256 checksum How to use checksums	`2717a23b19c0862a0cb59d1d24aaa674e029e485c4bca3850260cf67a8e14b88`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ljchang/marimo-book
Publishing commit: github.com/ljchang/marimo-book/tree/0705d12850543d37e9494467bdd90b2416671473

Workflow

Publishing configuration: github.com/ljchang/marimo-book/blob/0705d12850543d37e9494467bdd90b2416671473/.github/workflows/publish.yml
Publishing logs: github.com/ljchang/marimo-book/actions/runs/34650485656/attempts/1

Artifact

Subject: marimo_book-0.1.31.tar.gz
SHA-256 checksum: 0054c47e417bda6f92c5298d53d507d4772420b632a0d730a3c1301a51373fc7 Verifying attestations

Release files / marimo_book-0.1.31-py3-none-any.whl

Download URL	marimo_book-0.1.31-py3-none-any.whl
Size	153.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`394233e6a00014b4af3b29e51afce0f2bccedcb10245e63fc650346fa42e0359`
BLAKE2b-256 checksum How to use checksums	`653ffe639788c0e86bf7359450889afac47742d2abeda73d337b3ee960bb4ac6`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ljchang/marimo-book
Publishing commit: github.com/ljchang/marimo-book/tree/0705d12850543d37e9494467bdd90b2416671473

Workflow

Publishing configuration: github.com/ljchang/marimo-book/blob/0705d12850543d37e9494467bdd90b2416671473/.github/workflows/publish.yml
Publishing logs: github.com/ljchang/marimo-book/actions/runs/34650485656/attempts/1

Artifact

Subject: marimo_book-0.1.31-py3-none-any.whl
SHA-256 checksum: 394233e6a00014b4af3b29e51afce0f2bccedcb10245e63fc650346fa42e0359 Verifying attestations