Skip to content
View on GitHub

Deploying

marimo-book build produces a _site/ directory containing a self-contained static site: index.html, CSS, JS, your images/ and other asset directories. Any static host will serve it.

marimo-book new scaffolds a ready-to-use workflow at .github/workflows/deploy.yml that deploys on every push to main. Steps:

  1. Enable GitHub Pages on your repo: Settings → Pages → Source: GitHub Actions.
  2. Push a commit to main.
  3. First deploy takes ~1–2 minutes. Subsequent deploys are incremental.

The scaffolded workflow does the minimum — it assumes env mode dependencies. If your notebooks need extra packages, uncomment the "Install notebook dependencies" step:

- name: Install notebook dependencies
  run: pip install -r requirements.txt

Or if you're using sandbox mode, add a uv install step and pass --sandbox to the build:

- uses: astral-sh/setup-uv@v3
- run: pip install marimo-book
- run: marimo-book build --sandbox --strict

Custom domain

Put your domain in a CNAME file at the repo root. GitHub Pages picks it up automatically. Add a DNS CNAME record (or A records for an apex domain) pointing at <your-username>.github.io.

Netlify

Build command: pip install marimo-book && marimo-book build --strict

Publish directory: _site

Python version: set via runtime.txt or Netlify's environment variable PYTHON_VERSION=3.13.

Cloudflare Pages

Same as Netlify — build command and publish directory. Cloudflare Pages auto-detects pyproject.toml if present.

Self-host

marimo-book build --strict
# Serve _site/ with any static server:
python -m http.server 8080 --directory _site
# or caddy file-server -listen :8080 -root _site
# or nginx, s3 sync to a bucket + CloudFront, etc.

Strict mode for releases

Always build with --strict for publishes:

marimo-book build --strict

This makes broken internal links, missing files, and unresolved anchors fail the build instead of emitting warnings. Add --check-external-links + pip install 'marimo-book[linkcheck]' if you want external URLs validated too — see Publishing → Broken-link checking.