API Reference

Module: jupyter_export_html_style

The main module providing nbconvert integration for styled HTML export.

Classes

StylePreprocessor

class StylePreprocessor

A nbconvert preprocessor that extracts and processes style metadata from notebook cells.

This preprocessor examines each cell in a notebook for style-related metadata and prepares it for use in HTML export. Styles can be specified as either dictionaries or CSS strings.

style_metadata_key: str = "style": The metadata key to look for cell styles. Default is “style”. Can be configured via nbconvert configuration.

preprocess(nb, resources)

Preprocess the entire notebook.

Extracts notebook-level style metadata (style and stylesheet) from the notebook metadata and stores them in resources for later use in HTML generation.

Parameters:

nb (NotebookNode) – The notebook to preprocess
resources (dict) – Additional resources used in the conversion process

Returns:

Tuple of processed notebook and updated resources

Return type:

tuple(NotebookNode, dict)

preprocess_cell(cell, resources, index)

Preprocess a single cell.

Extracts style metadata from cells including: - style: CSS styles for the entire cell container - input-style: CSS styles for the cell’s input area - output-style: CSS styles for the cell’s output area

Parameters:

cell (NotebookNode) – The cell to preprocess
resources (dict) – Additional resources used in the conversion process
index (int) – The index of the cell in the notebook

Returns:

Tuple of processed cell and updated resources

Return type:

tuple(NotebookNode, dict)

StyledHTMLExporter

class StyledHTMLExporter

An HTML exporter that supports cell-level and notebook-level style customization.

This exporter extends the standard nbconvert HTMLExporter to include custom styles defined in cell and notebook metadata. It automatically registers the StylePreprocessor and injects collected styles into the output HTML.

Supported Features:

Cell-level styles via style metadata
Input area styling via input-style metadata
Output area styling via output-style metadata
Notebook-level styles via notebook metadata style key
External stylesheets via notebook metadata stylesheet key

template_name: str = "classic": Name of the template to use for HTML generation. Default is “classic”.

from_notebook_node(nb, resources=None, **kw)

Convert a notebook node to HTML with style support.

Processes the notebook with the StylePreprocessor and injects all collected styles (cell-level and notebook-level) into the HTML output before the closing </head> tag.

Parameters:

nb (NotebookNode) – The notebook to convert
resources (dict, optional) – Additional resources used in the conversion process
kw (dict) – Additional keyword arguments

Returns:

Tuple of HTML output and updated resources

Return type:

tuple(str, dict)

_generate_style_block(styles)

Generate a CSS style block from collected cell styles.

Converts style dictionaries and strings into CSS rules that target specific cell, input, and output elements by their IDs.

Parameters:: styles (dict) – Dictionary mapping cell IDs to style definitions
Returns:: CSS style block as HTML string
Return type:: str

_generate_notebook_style_block(notebook_styles)

Generate style and stylesheet blocks from notebook-level metadata.

Creates HTML link tags for external stylesheets and inline style tags for custom CSS. Supports both single stylesheet strings and lists of stylesheets.

Parameters:: notebook_styles (dict) – Dictionary containing ‘style’ and/or ‘stylesheet’ keys
Returns:: HTML containing style and/or link elements
Return type:: str

StyledWebPDFExporter

class StyledWebPDFExporter

A PDF exporter that supports cell-level and notebook-level style customization.

This exporter extends StyledHTMLExporter to generate PDF files via HTML using Playwright and Chromium. It preserves all custom styles, embedded images, and formatting when converting to PDF.

Supported Features:

All features from StyledHTMLExporter (cell styles, notebook styles, embedded images)
PDF generation with Playwright and Chromium
Configurable pagination
Single-page or multi-page output
Container-friendly operation

template_name: str = "webpdf": Name of the template to use for HTML generation before PDF conversion.

paginate: bool = True: Split the notebook into multiple pages. Set to False for a single long page.

allow_chromium_download: bool = False: Whether to allow downloading Chromium if no suitable version is found.

disable_sandbox: bool = False: Disable Chromium security sandbox. Required for container environments but reduces security. Use with caution.

from_notebook_node(nb, resources=None, **kw)

Convert a notebook node to PDF with style support.

First generates HTML using StyledHTMLExporter (including all custom styles), then converts the HTML to PDF using Playwright and Chromium.

Parameters:

nb (NotebookNode) – The notebook to convert
resources (dict, optional) – Additional resources used in the conversion process
kw (dict) – Additional keyword arguments

Returns:

Tuple of PDF data and updated resources

Return type:

tuple(bytes, dict)

Raises:

RuntimeError – If Playwright is not installed or Chromium is not found

run_playwright(html)

Run Playwright to convert HTML to PDF.

Launches Chromium, loads the HTML content, and generates a PDF with the specified settings (pagination, page size, etc.).

Parameters:: html (str) – The HTML content to convert to PDF
Returns:: PDF data as bytes
Return type:: bytes
Raises:: RuntimeError – If Playwright is not installed or Chromium is not found

Module-Level Attributes

__version__: str = "0.1.0": The version of the jupyter_export_html_style package.

Usage Examples

Using StylePreprocessor Standalone

from jupyter_export_html_style import StylePreprocessor
from nbformat import read

# Load a notebook
with open('notebook.ipynb', 'r') as f:
    nb = read(f, as_version=4)

# Create and configure preprocessor
preprocessor = StylePreprocessor()
preprocessor.style_metadata_key = "custom_style"

# Process the notebook
processed_nb, resources = preprocessor.preprocess(nb, {})

Using StyledHTMLExporter

from jupyter_export_html_style import StyledHTMLExporter

# Create exporter
exporter = StyledHTMLExporter()
exporter.template_name = "classic"

# Export notebook
(body, resources) = exporter.from_filename('notebook.ipynb')

# Save to file
with open('output.html', 'w') as f:
    f.write(body)

Creating Notebooks with Input/Output Styles

from jupyter_export_html_style import StyledHTMLExporter
from nbformat.v4 import new_code_cell, new_notebook
import nbformat

# Create cells with input and output styles
cells = []

cell1 = new_code_cell("x = 42\nprint(x)")
cell1.metadata['input-style'] = {
    'background-color': '#f5f5f5',
    'border-left': '4px solid #2196f3'
}
cell1.metadata['output-style'] = {
    'background-color': '#e8f5e9',
    'font-family': 'monospace'
}
cells.append(cell1)

# Create notebook
nb = new_notebook(cells=cells)

# Add notebook-level styles
nb.metadata['style'] = """
body {
    font-family: 'Segoe UI', sans-serif;
    max-width: 1200px;
}
"""
nb.metadata['stylesheet'] = 'https://fonts.googleapis.com/css2?family=Segoe+UI'

# Export
exporter = StyledHTMLExporter()
output, resources = exporter.from_notebook_node(nb)

# Save
with open('styled_output.html', 'w') as f:
    f.write(output)

Processing Cell-Level Styles

from jupyter_export_html_style import StylePreprocessor
import nbformat
from nbformat.v4 import new_code_cell, new_notebook

# Create a notebook with various style types
cell1 = new_code_cell("# Cell with all style types")
cell1.metadata['style'] = {'margin': '20px'}
cell1.metadata['input-style'] = {'color': 'blue'}
cell1.metadata['output-style'] = {'border': '1px solid green'}

nb = new_notebook(cells=[cell1])

# Process with preprocessor
preprocessor = StylePreprocessor()
processed_nb, resources = preprocessor.preprocess(nb, {})

# Check collected styles
print(f"Collected styles: {resources['styles']}")
# Output: {'cell-0': {'margin': '20px'}, 
#          'cell-0-input': {'color': 'blue'},
#          'cell-0-output': {'border': '1px solid green'}}

Configuration via Traitlets

from jupyter_export_html_style import StyledHTMLExporter
from traitlets.config import Config

# Create configuration
config = Config()
config.StylePreprocessor.style_metadata_key = "cell_style"
config.StyledHTMLExporter.template_name = "lab"

# Create exporter with config
exporter = StyledHTMLExporter(config=config)

Using StyledWebPDFExporter

from jupyter_export_html_style import StyledWebPDFExporter

# Create exporter with default settings
exporter = StyledWebPDFExporter()

# Export notebook to PDF
(pdf_data, resources) = exporter.from_filename('notebook.ipynb')

# Save to file
with open('output.pdf', 'wb') as f:
    f.write(pdf_data)

PDF Export with Custom Options

from jupyter_export_html_style import StyledWebPDFExporter

# Create exporter with custom settings
exporter = StyledWebPDFExporter(
    paginate=False,  # Single long page
    allow_chromium_download=True,  # Auto-download Chromium if needed
    disable_sandbox=False  # Keep sandbox enabled (default)
)

# Export notebook to PDF
(pdf_data, resources) = exporter.from_filename('styled_notebook.ipynb')

# Save to file
with open('styled_output.pdf', 'wb') as f:
    f.write(pdf_data)

PDF Export in Container Environments

from jupyter_export_html_style import StyledWebPDFExporter

# For Docker/Kubernetes, disable sandbox
exporter = StyledWebPDFExporter(
    disable_sandbox=True  # Required in most containers
)

# Export notebook to PDF
(pdf_data, resources) = exporter.from_filename('notebook.ipynb')

# Save to file
with open('output.pdf', 'wb') as f:
    f.write(pdf_data)

Entry Points

The package registers the following nbconvert entry points:

Preprocessors

style: Points to jupyter_export_html_style.preprocessor:StylePreprocessor

Exporters

styled_html: Points to jupyter_export_html_style.exporters.html:StyledHTMLExporter
styled_webpdf: Points to jupyter_export_html_style.exporters.webpdf:StyledWebPDFExporter
styled_slides: Points to jupyter_export_html_style.exporters.slides:StyledSlidesExporter

These can be used directly with nbconvert command line:

# Export to styled HTML
jupyter nbconvert --to styled_html notebook.ipynb

# Export to styled PDF
jupyter nbconvert --to styled_webpdf notebook.ipynb

API Reference

Module: jupyter_export_html_style

Classes

StylePreprocessor

StyledHTMLExporter

StyledWebPDFExporter

Module-Level Attributes

Usage Examples

Using StylePreprocessor Standalone

Using StyledHTMLExporter

Creating Notebooks with Input/Output Styles

Processing Cell-Level Styles

Configuration via Traitlets

Using StyledWebPDFExporter

PDF Export with Custom Options

PDF Export in Container Environments

Entry Points

Preprocessors

Exporters

See Also