```{toctree}
---
maxdepth: 2
hidden: true
---
docs/src/background.md
docs/src/gallery.md
docs/src/architecture.md
docs/src/configuration.md
docs/src/api.md
```
A framework for building print media with [`nbconvert`](https://nbconvert.readthedocs.io).
[](https://github.com/nbprint/nbprint/actions/workflows/build.yaml)
[](https://app.codecov.io/gh/nbprint/nbprint/tree/main)
[](https://github.com/nbprint/nbprint/issues)
[](https://github.com/nbprint/nbprint)
[](https://pypi.python.org/pypi/nbprint)
## Background
Jupyter Notebooks are widely used for reports via [`nbconvert`](https://nbconvert.readthedocs.io/en/latest/), 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`](https://pagedjs.org) print-oriented layout library.
For a deeper dive, see [the documentation](https://nbprint.github.io/nbprint/index.html). To see what nbprint produces, browse the [gallery](https://nbprint.github.io/nbprint/docs/src/gallery.html) of rendered examples.
## Quickstart
`nbprint` provides an `nbconvert` template and a [configuration framework](https://nbprint.github.io/nbprint/docs/src/configuration.html).
The simplest example can be run with defaults by calling the `nbprint` executable on an existing notebook:
```bash
nbprint examples/basic.ipynb
```
This CLI supports configuration-driven customization with [hydra](https://hydra.cc) syntax:
```bash
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
```
```mermaid
graph TB
subgraph author["authoring"]
nb("notebook
(.ipynb)")
yaml[/"YAML config
(hydra)"/]
end
subgraph build["build time — Python"]
nbc{"nbconvert"}
nbct[/"nbprint template
(Jinja2)"/]
html@{ shape: doc, label: "standalone html
+ embedded JS/CSS" }
end
subgraph browser["render time — browser"]
direction TB
init["1 · initialize
decode images"]
proc["2 · process
reparent DOM · hoist styles"]
pre["3 · preprocess
measure · scale · split"]
esm["4 · cell render()
await trackRender barrier"]
pjs[/"5 · paged.js
paginate"/]
post["6 · postvalidate
drop blanks · warn overflow"]
end
out@{ shape: doc, label: "final output
(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](https://hydra.cc). 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](https://nbprint.github.io/nbprint/docs/src/architecture.html#render-lifecycle), so pagination starts only after the DOM is stable. [`paged.js`](https://pagedjs.org) 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](https://nbprint.github.io/nbprint/docs/src/architecture.html).
### Configuration
See the [configuration framework documentation](https://nbprint.github.io/nbprint/docs/src/configuration.html) for more information on building pure YAML-based report workflows with `hydra`.
## Installation
Install with `pip`:
```bash
pip install nbprint
```
Install with `conda`
```bash
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](LICENSE) file for details.
> [!NOTE]
> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).