A framework for building print media with nbconvert.

Background

Jupyter Notebooks are widely used for reports via nbconvert, but most development work has been on enabling building interactive websites. The goal of nbprint is to focus on print-oriented workflows, e.g. PDF, by leveraging new developments in nbconvert and the pagedjs print-oriented layout library.

For a deeper dive, see the documentation.

Quickstart

nbprint provides an nbconvert template and a configuration framework. The simplest example can be run with defaults by calling the nbprint executable on an existing notebook:

nbprint examples/basic.ipynb

This CLI supports configuration-driven customization with hydra syntax:

nbprint examples/basic.ipynb +nbprint.name=test ++nbprint.outputs.target=pdf

# First cell is papermill-style parameters
nbprint examples/parameters.ipynb +nbprint.parameters.a=test

# Overlay a config group, e.g. title and table of contents
nbprint examples/basic.ipynb nbprint/content/frontmatter=nbprint/title_toc

        graph TB
    subgraph author["authoring"]
        nb("notebook<br>(.ipynb)")
        yaml[/"YAML config<br>(hydra)"/]
    end

    subgraph build["build time — Python"]
        nbc{"nbconvert"}
        nbct[/"nbprint template<br>(Jinja2)"/]
        html@{ shape: doc, label: "standalone html<br>+ embedded JS/CSS" }
    end

    subgraph browser["render time — browser"]
        direction TB
        init["1 · initialize<br>decode images"]
        proc["2 · process<br>reparent DOM · hoist styles"]
        pre["3 · preprocess<br>measure · scale · split"]
        esm["4 · cell render()<br>await trackRender barrier"]
        pjs[/"5 · paged.js<br>paginate"/]
        post["6 · postvalidate<br>drop blanks · warn overflow"]
    end

    out@{ shape: doc, label: "final output<br>(html · pdf via webpdf)" }

    nb e1@--> nbc
    yaml --> nbc
    nbct --> nbc
    e1@{animate: true}

    nbc e2@--> html
    e2@{animate: true}

    html --> init
    init --> proc --> pre --> esm --> pjs --> post

    post e3@--> out
    e3@{animate: true}

    classDef browserPhase fill:#eef,stroke:#557,color:#000
    class init,proc,pre,esm,pjs,post browserPhase
    

nbprint splits work across three stages. Authoring happens in the notebook (plus optional YAML overrides via hydra). At build time, nbconvert runs the nbprint Jinja2 template to emit a single self-contained HTML file with all JS, CSS, and data embedded. At render time, the browser does the heavy lifting: reparenting the DOM by parent-id, hoisting global styles, running a preprocessing pass that measures and scales oversized content, awaiting every cell’s render() function through a lifecycle barrier so pagination only starts after the DOM is stable, then handing off to paged.js for layout, and finally running a postvalidation pass that drops blank pages and surfaces overflow warnings. PDF output is produced by rendering the same HTML with nbconvert --to webpdf (headless Chromium); there is no separate PDF codepath.

For more information, see the architecture documentation.

Configuration

See the configuration framework documentation for more information on building pure YAML-based report workflows with hydra.

Installation

Install with pip:

pip install nbprint

Install with conda

conda install nbprint -c conda-forge

Development

Warning: This project is under active development, so all APIs are subject to change!

License

This software is licensed under the Apache 2.0 license. See the LICENSE file for details.

Note

This library was generated using copier from the Base Python Project Template repository.