nb2wb 0.2.0

Write in Jupyter Notebooks. Publish anywhere.

nb2wb

Write in notebooks. Publish anywhere.

nb2wb converts Jupyter Notebooks and other notebook-style content into publishable HTML for Substack, Medium, and X Articles.

Supported inputs:

• Jupyter notebooks (.ipynb)
• Quarto documents (.qmd)
• Markdown documents (.md)
• in-memory Jupyter notebook payloads (dict / NotebookNode)

Documentation

• Detailed docs (Read the Docs): https://nb2wb.readthedocs.io/
• Docs source in this repo: docs/index.md

Brief Feature Tour

1. Load notebook content from file or in-memory payload.
2. Optionally execute code cells (--execute / execute=True).
3. Render markdown, math, code, and outputs into platform-safe HTML fragments.
4. Convert display math, code, and (optionally) tables to images for high-fidelity publishing.
5. Sanitize rich HTML/SVG output and enforce server-side safety limits.
6. Wrap output for your target platform (substack, medium, x).

Installation

pip install nb2wb

Development install:

git clone https://github.com/the-palindrome/nb2wb.git
cd nb2wb
pip install -e ".[dev]"

Quick Start (CLI)

nb2wb notebook.ipynb
nb2wb notebook.ipynb -t medium
nb2wb notebook.ipynb -t x
nb2wb notebook.ipynb -o article.html
nb2wb notebook.ipynb --open
nb2wb notebook.ipynb --serve
nb2wb report.qmd --execute

Quick Start (Python API)

import nb2wb

# Path input via loader helper
payload = nb2wb.load_input_payload("notebook.ipynb")
html = nb2wb.convert(
    payload,
    target="substack",
    config={"latex": {"try_usetex": True}},
)

# In-memory payload input (JSON / JSONB parsed notebook)
html = nb2wb.convert(
    notebook_payload,
    target="substack",
    execute=False,
)

nb2wb.convert() is content-only; use load_input_payload() (or typed loaders) for filesystem inputs.

Security at a Glance

nb2wb uses a mandatory server-safe conversion pipeline:

• strict HTML/SVG sanitization
• CSS URL sanitization
• SSRF-safe image fetching
• path traversal protection for local files
• notebook size/resource safety limits
• fail-closed behavior for unsafe/unresolvable image sources

Important: enabling execution runs notebook code. Treat execute=True workloads as untrusted code and isolate them appropriately.

Configuration

Use YAML file in CLI:

nb2wb notebook.ipynb -c config.yaml

Or pass dict/object/path in API:

html = nb2wb.convert(notebook_payload, config={"safety": {"max_cells": 1500}})

Read More

• Feature Tour
• Getting Started
• CLI Reference
• Python API
• Input Formats
• Configuration
• Platforms
• Security Model
• FastAPI/API Integration
• Troubleshooting
• For Maintainers

Development

Run tests:

pytest

Build docs locally:

pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html

License

MIT