marimo-book 0.1.0a1__tar.gz

marimo_book-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Format check
+        run: ruff format --check src/ tests/
+      - name: Test
+        run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install build backend
+        run: python -m pip install build
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Verify wheel contents
+        run: |
+          python -c "
+          import zipfile, pathlib
+          wheel = next(pathlib.Path('dist').glob('marimo_book-*.whl'))
+          with zipfile.ZipFile(wheel) as z:
+              names = z.namelist()
+          required = [
+              'marimo_book/cli.py',
+              'marimo_book/preprocessor.py',
+              'marimo_book/assets/marimo_book.js',
+              'marimo_book/assets/scaffold/book.yml',
+              'marimo_book/assets/scaffold/.gitignore',
+              'marimo_book/assets/scaffold/.github/workflows/deploy.yml',
+          ]
+          missing = [f for f in required if f not in names]
+          if missing:
+              raise SystemExit(f'wheel missing files: {missing}')
+          print(f'wheel OK ({len(names)} entries)')
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7
+
+  docs:
+    # Validates that the self-hosted docs book still builds — catches
+    # regressions before they land on main. The real deploy happens in
+    # docs.yml on push to main.
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install marimo-book with linkcheck extra
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[linkcheck]'
+      - name: Build docs --strict
+        run: marimo-book build -b docs/book.yml --strict

marimo_book-0.1.0a1/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Build and deploy docs
+
+# Self-host marimo-book's own docs (built with marimo-book) on GitHub
+# Pages. Triggered on pushes to main that touch the docs tree or the
+# package source (so tool changes also re-render the docs immediately).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install marimo-book (editable)
+        run: pip install -e '.[linkcheck]'
+      - name: Build docs
+        run: marimo-book build -b docs/book.yml --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

marimo_book-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+# Publishes on any tag matching v*.
+# Uses PyPI's Trusted Publisher setup (OIDC — no API token needed) — you
+# must first register this repo + workflow on PyPI:
+# https://docs.pypi.org/trusted-publishers/
+#
+# Project name on PyPI: marimo-book
+# Owner / repo:        ljchang/marimo-book
+# Workflow name:       publish.yml
+# Environment name:    pypi-publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write  # required for PyPI Trusted Publisher
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-publish
+      url: https://pypi.org/p/marimo-book
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        # No `with:` block needed — trusted publishing pulls creds from
+        # PyPI's OIDC handshake with GitHub.

marimo_book-0.1.0a1/.gitignore

@@ -0,0 +1,48 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Type checkers
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+
+# marimo-book build artifacts
+_site/
+_site_src/
+.marimo_book_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# uv
+uv.lock
+.python-version
+__marimo__/

marimo_book-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to `marimo-book` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0a1] — 2026-04-24
+
+First alpha release. Usable end-to-end for single-book sites.
+
+### Added
+
+**CLI** (`marimo-book ...`)
+
+- `new <dir>` — scaffold a new book (book.yml, content/, .gitignore,
+  .github/workflows/deploy.yml, README). `--force` to write into
+  non-empty directories.
+- `build` — preprocess + emit static site to `_site/`. `--strict` fails
+  on warnings; `--clean` blows away prior build artifacts first.
+- `serve` — dev server with live reload. Runs an initial build, spawns
+  `mkdocs serve`, and a watchdog observer rebuilds on changes to
+  `content/` or `book.yml`.
+- `check` — validate `book.yml` + referenced files without building.
+- `clean` — remove `_site/`, `_site_src/`, `.marimo_book_cache/`.
+
+**Config** (`book.yml`)
+
+- Pydantic v2 schema with readable errors for unknown keys.
+- Discriminated-union TOC (`file:` / `url:` / `section:` + `children:`).
+- Author metadata, branding (logo, favicon, palette, fonts), launch
+  buttons, bibliography paths, analytics (Plausible / Google), per-page
+  render defaults, per-widget-class default state.
+- Top-level `shell:` reserved for future `zensical` / `jinja` targets.
+
+**Preprocessor transforms**
+
+- `marimo_export` — `.py` → Markdown + inline HTML via
+  `marimo export ipynb --include-outputs`. Handles hide_code, mime bundles
+  (text/html, text/markdown, image/png|jpeg|svg+xml, text/plain,
+  streams, errors), and first-setup-cell elision.
+- `callouts` — `<marimo-callout-output>` → Material admonition with the
+  kind mapped (info/note/success/tip/warning/danger/failure/neutral).
+- `anywidgets` — `<marimo-anywidget>` → `<div class="marimo-book-anywidget">`
+  mount; AST-walks cell source to extract literal widget kwargs; merges
+  with `book.yml` `widget_defaults`. Strips
+  `<marimo-ui-element>` / `<marimo-slider>` / etc. wrappers around
+  kernel-dependent controls that have no static analog.
+- `md_roles` — `{download}\`label <path>\`` → `[label](path)`;
+  `:::{glossary}` fence stripping.
+- `link_rewrites` — `.ipynb` cross-refs → `.md` (when target exists);
+  `../images/` → `images/` in both Markdown links and HTML attrs.
+
+**Shell generator**
+
+- `book.yml` → `mkdocs.yml` with Material theme, standard pymdownx
+  extensions (arithmatex, admonition, blocks, details, highlight,
+  superfences, tabbed, tasklist), sensible nav feature flags, and an
+  `extra.css` derived from the book's palette.
+
+**Runtime shim** (`assets/marimo_book.js`)
+
+- Minimal anywidget-compatible model loader. At page load, finds every
+  `.marimo-book-anywidget` mount, decodes the inlined ES module from
+  `data-js-url`, and calls `module.default.render({model, el})` with a
+  seeded model. Works with Material's instant-navigation via
+  `document$.subscribe`.
+
+### Verified
+
+- Full test suite: 46 passing across config, transforms, CLI, and watcher.
+- End-to-end dartbrains build (34 TOC entries, 20 marimo notebooks):
+  0 preprocessor errors, 2 cosmetic mkdocs warnings (both broken-link
+  issues in dartbrains source content, not tool bugs).
+- Widget-heavy chapter (MR_Physics.py, 9 anywidgets) renders and animates
+  in a browser without marimo's frontend runtime.
+
+### Known limitations
+
+- No WASM / hybrid render modes yet (static only).
+- No dependency-graph-aware incremental cache; every rebuild is a full
+  rebuild.
+- MyST cross-refs with `{ref}`, `{numref}`, `{eq}`, `{cite}`, etc. are
+  stripped through unchanged (no usage in any book we've migrated yet).
+- Material for MkDocs is entering maintenance mode in ~12 months;
+  `marimo-book` is explicitly designed to port to [zensical](https://zensical.org)
+  when it stabilises (same `mkdocs.yml`, different build command).

marimo_book-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

marimo_book-0.1.0a1/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: marimo-book
+Version: 0.1.0a1
+Summary: Build clean, searchable static books from marimo notebooks and markdown
+Project-URL: Homepage, https://github.com/ljchang/marimo-book
+Project-URL: Repository, https://github.com/ljchang/marimo-book
+Project-URL: Issues, https://github.com/ljchang/marimo-book/issues
+Author-email: Luke Chang <luke.j.chang@dartmouth.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: book,documentation,marimo,mkdocs,notebook,static-site
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: jinja2>=3.1
+Requires-Dist: lxml>=5.0
+Requires-Dist: marimo<0.24,>=0.23
+Requires-Dist: mkdocs-material>=9.5
+Requires-Dist: mkdocs>=1.6
+Requires-Dist: nbformat>=5.0
+Requires-Dist: pybtex>=0.24
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pymdown-extensions>=10.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: linkcheck
+Requires-Dist: mkdocs-htmlproofer-plugin>=1.3; extra == 'linkcheck'
+Description-Content-Type: text/markdown
+
+# marimo-book
+
+Build clean, searchable static books from [marimo](https://marimo.io)
+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:
+
+- **Collapsible sidebar** and chapter-aware navigation
+- **Fast full-text search** across prose *and* baked cell outputs
+- **Admonitions, math, figures, tables** with Material for MkDocs defaults
+- **Anywidgets that render statically** (no marimo kernel required)
+- **Launch buttons** per-chapter for molab / GitHub / download `.py`
+- **Dark-mode toggle** that persists across navigation
+- **GitHub Pages deploy workflow** scaffolded in for you
+
+## Status
+
+**Alpha** (v0.1.0a1, April 2026). `marimo-book` is usable end-to-end and is
+actively building a real course site ([dartbrains](https://github.com/ljchang/dartbrains)),
+but the `book.yml` schema may still change before v1.0. Pin the exact version
+in your project until we signal stability.
+
+## Install
+
+```bash
+pip install marimo-book
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```bash
+# Scaffold a new book
+marimo-book new mybook
+cd mybook
+
+# Live-reload dev server (http://127.0.0.1:8000/)
+marimo-book serve
+#
+# Note on macOS: mkdocs's browser auto-reload is flaky on some
+# macOS setups. If the browser doesn't refresh automatically after a
+# save, hard-refresh (Cmd-R). The preprocessor + rebuild are
+# reliable; only the browser push is affected.
+
+# 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 `main` 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/
+```
+
+1. The preprocessor reads `book.yml` and walks the TOC. For each `.md` it
+   applies small content transforms (MyST `:::{glossary}` fence stripping,
+   `{download}` role rewrite, `../images/` path fixups, `.ipynb` →
+   `.md` cross-ref rewriting). For each marimo `.py` it runs
+   `marimo export ipynb --include-outputs` and converts the cells into
+   Markdown + inline HTML, translating marimo custom elements
+   (`<marimo-callout-output>`, `<marimo-anywidget>`) into their static
+   analogs.
+2. Material for MkDocs (or later, zensical — which reuses `mkdocs.yml`
+   verbatim) builds the final HTML.
+
+The preprocessor is **not** a mkdocs plugin — it emits plain Markdown +
+inline HTML. This keeps the shell swappable: Material today, zensical
+tomorrow, or a hand-rolled Jinja shell as a last-resort fallback.
+
+## `book.yml`
+
+```yaml
+title: My Book
+description: A static site from marimo notebooks + Markdown.
+authors:
+  - name: Your Name
+    orcid: 0000-0000-0000-0000       # optional
+repo: https://github.com/you/yourbook
+branch: main
+
+theme:
+  palette:
+    primary: "#1976D2"
+    accent:  "#FF9800"
+
+launch_buttons:
+  molab: true          # "Open in molab" button on every .py page
+  github: true         # "View on GitHub"
+  download: true       # "Download .py source"
+
+# Per-widget default state for anywidgets whose JS needs initial model
+# values to render on first paint. Literal kwargs from the cell override
+# these; unset keys fall through to the widget's own JS defaults.
+widget_defaults:
+  CompassWidget:
+    b0: 3.0
+
+toc:
+  - file: content/intro.md
+  - section: Part I
+    children:
+      - file: content/chapter1.py
+      - file: content/chapter2.py
+  - section: Part II
+    children:
+      - file: content/chapter3.py
+      - url: https://example.org/external-reading
+        title: External Reading
+```
+
+See `marimo-book new` for a full starter template with comments on every
+field.
+
+## What's supported in v0.1
+
+**Material for MkDocs handles natively (free):**
+
+- Full-text search, dark mode, keyboard shortcuts, code-copy buttons,
+  collapsible sidebar, breadcrumbs, next/previous navigation,
+  admonitions (`!!! note` / `!!! tip` / `!!! warning` / etc.), math,
+  responsive theme, edit-this-page link, analytics, top-of-page banner
+
+**Preprocessor adds:**
+
+- `book.yml` → `mkdocs.yml` generation (TOC, theme, palette, fonts,
+  extensions, plugins all derived)
+- `.py` → rendered Markdown + inlined anywidget / callout / image outputs
+- Static rehydration of anywidgets via a small JS shim
+  (`marimo_book.js`, loaded via `extra_javascript`)
+- Launch-button row per chapter (molab / GitHub / download)
+- MyST `{download}\`label <path>\`` → `[label](path)`
+- `:::{glossary}` fence stripping (definition lists pass through natively)
+- `[text](Foo.ipynb)` → `[text](Foo.md)` cross-ref rewrite when `Foo.md`
+  exists in the staged tree
+- `../images/` → `images/` relative-path fixup when `content/` is flattened
+- First-code-cell hiding (the setup-imports convention) — opt out via
+  `defaults.hide_first_code_cell: false`
+
+## Notebook dependencies
+
+Notebooks need their imports satisfied at build time (marimo re-executes
+every cell to capture outputs). `marimo-book` supports two modes; pick
+in `book.yml`:
+
+```yaml
+dependencies:
+  mode: env       # default — reuse the active venv
+  # mode: sandbox # per-notebook PEP 723 isolation via uv
+```
+
+**`env` mode** (default). Whatever Python env runs `marimo-book` provides
+the deps. The typical consumer has a `pyproject.toml` at the book root
+listing notebook dependencies (`numpy`, `pandas`, your domain package,
+etc.), installs with `pip install -e .` or `uv pip install -e .`, and
+runs `marimo-book` from that env. Fast, straightforward, good when all
+notebooks share the same stack.
+
+**`sandbox` mode.** Passes `--sandbox` to `marimo export`. Each notebook
+must declare its own deps via PEP 723 inline script metadata:
+
+```python
+# /// script
+# dependencies = [
+#     "marimo>=0.23",
+#     "numpy>=2.0",
+#     "pandas>=2.0",
+# ]
+# ///
+
+import marimo
+# ...
+```
+
+At build time, marimo uses `uv run --isolated` to provision a fresh env
+per notebook. ~5–10 s on first run, cached after. Notebooks become
+portable — copy a `.py` into any repo with `uv` installed and it just
+works. The book root doesn't need a `pyproject.toml`.
+
+**Override per invocation:**
+
+```bash
+marimo-book build --sandbox    # force sandbox regardless of book.yml
+marimo-book build --no-sandbox # force env mode
+marimo-book serve --sandbox    # slower iteration, but reproducible
+```
+
+Use `env` for local dev loops and `sandbox` on CI where reproducibility
+matters more than rebuild speed.
+
+## Broken-link checking
+
+`mkdocs build --strict` (use `marimo-book build --strict`) already fails on
+broken **in-tree** links and anchors. For external URLs and image `src`
+attributes, opt into the `htmlproofer` plugin:
+
+```yaml
+# book.yml
+check_external_links: true
+```
+
+```bash
+pip install 'marimo-book[linkcheck]'
+marimo-book build --strict
+```
+
+External link checking hits the live web, so it's slow (~1–3 s per link).
+Keep it off on CI unless you're cutting a release.
+
+**Not in v0.1 (planned):**
+
+- WASM / hybrid render modes — static only in v0.1; architecture already
+  supports the branch
+- Dependency-graph-aware incremental build cache
+- BibTeX citations with hover-cards (no book needs them yet)
+- PDF / EPUB export — opt-in via `mkdocs-with-pdf` if needed
+
+## License
+
+[MIT](LICENSE)