A framework for building print media with nbconvert.

Background

Jupyter Notebooks are widely used for reports via nbconvert, but most development work has focused on 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. To see what nbprint produces, browse the gallery of rendered examples.

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. You author a notebook, optionally with YAML overrides via hydra. At build time, nbconvert runs the nbprint Jinja2 template and writes a single self-contained HTML file with all JS, CSS, and data embedded. At render time, the browser lays out the pages. It reparents the DOM by parent id, hoists global styles, measures and scales oversized content, and waits for every cell’s render() function through a lifecycle barrier, so pagination starts only after the DOM is stable. paged.js then paginates the document, and a final validation pass drops blank pages and warns about overflow. PDF output comes from rendering the same HTML with nbconvert --to webpdf (headless Chromium), so there is no separate PDF code path.

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.