# jupyter/nbconvert-examples architecture

> Architecture diagram of the GitHub repository jupyter/nbconvert-examples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jupyter/nbconvert-examples
- Repository: https://github.com/jupyter/nbconvert-examples

## Overview

##### Project type and purpose
- This repository is an “examples” project for Jupyter nbconvert. It’s not a deployed service or full-stack app, but a catalog of usage scenarios showing how to extend and customize the nbconvert pipeline (filters, preprocessors, templates, output formats, Sphinx integration, etc.).
- The README simply says “Examples that illustrate how nbconvert can be used,” confirming its role as sample code rather than a single monolithic application.

##### File structure
- Top-level elements:
- basic/
- citations/
- custom_filter/
- custom_latex_cell_style/
- custom_preprocessor/
- custom_template/
- hr_cell_style/
- images/
- latex_cell_style/
- notebook_cell_style/
- pdf/
- sphinx_class/
- Each directory encapsulates one scenario: it contains an ipython_nbconvert_config.py (to register custom code), one or more .tpl/.tplx templates or .py filter/preprocessor classes, and a test notebook.
- There are no “backend” or “frontend” sub-projects, but rather multiple plugin-style components that hook into the single nbconvert engine.

##### README for additional insights
- The README is minimal and does not spell out architecture; it simply labels the repo as “nbconvert-examples.” The detailed insight comes from the directory names and their contents.

##### Elements
- Clear labels for each pipeline stage and extension type.
- Orange for external tools (LaTeX, Sphinx)
- Purple for final outputs (HTML, PDF, etc.)

##### Putting it all together
- Beneath or alongside, group example folders to show that each scenario demonstrates one or more extension points.

## Diagram (Mermaid)

```mermaid
flowchart LR
    %% Jupyter Notebook Sources
    subgraph "Jupyter Notebook Sources"
        direction TB
        NB1["basic/notebook1.ipynb"]:::notebook
        NB2["basic/notebook2.ipynb"]:::notebook
        CIT1["citations/Tutorial.ipynb"]:::notebook
        CFNB["custom_filter/notebook1.ipynb"]:::notebook
        CPNB["custom_preprocessor/notebook1.ipynb"]:::notebook
        PTNB["pdf/notebook.ipynb"]:::notebook
        SCNB["sphinx_class/notebook1.ipynb"]:::notebook
    end

    %% nbconvert Core Pipeline
    subgraph "nbconvert Core Pipeline"
        direction TB
        NL["NotebookLoader"]:::core
        PRE["Preprocessor Stage"]:::core
        FIL["Filter Stage"]:::core
        TMP["Template Engine"]:::core
        WRI["Writer"]:::core
    end

    %% Outputs
    subgraph "Output Formats"
        direction TB
        HTML["HTML"]:::output
        LATEX["LaTeX"]:::output
        PDF["PDF"]:::output
        SPHINX["Sphinx-ready"]:::output
    end

    %% External Tools
    subgraph "External Tools"
        direction TB
        TEX["LaTeX Toolchain"]:::external
        SPHERE["Sphinx Builder"]:::external
    end

    %% Connections
    NB1 --> NL
    NB2 --> NL
    CIT1 --> NL
    CFNB --> NL
    CPNB --> NL
    PTNB --> NL
    SCNB --> NL

    NL --> PRE
    PRE --> FIL
    FIL --> TMP
    TMP --> WRI

    WRI --> HTML
    WRI --> LATEX
    WRI --> PDF
    WRI --> SPHINX

    LATEX --> TEX
    SPHINX --> SPHERE

    %% Extension Points Attachments
    CFNF["null_highlight_filter.py"]:::extension
    CF_CFG["custom_filter/ipython_nbconvert_config.py"]:::extension
    CFNF --> FIL
    CF_CFG --> FIL

    CP_PP["cheese_preprocessor.py"]:::extension
    CP_CFG["custom_preprocessor/ipython_nbconvert_config.py"]:::extension
    CP_PP --> PRE
    CP_CFG --> PRE

    CIT_TPL["citations/citations.tplx"]:::extension
    CIT_TPL --> TMP

    SC_PP["sphinx_class/sphinx_preprocessor.py"]:::extension
    SC_CFG["sphinx_class/ipython_nbconvert_config.py"]:::extension
    SC_PP --> PRE
    SC_CFG --> PRE

    SC_TPLA["sphinx_class/latex_sphinx_article.tplx"]:::extension
    SC_TPLR["sphinx_class/latex_sphinx_report.tplx"]:::extension
    SC_TPLA --> TMP
    SC_TPLR --> TMP

    %% Click Events
    click NB1 "https://github.com/jupyter/nbconvert-examples/blob/master/basic/notebook1.ipynb"
    click NB2 "https://github.com/jupyter/nbconvert-examples/blob/master/basic/notebook2.ipynb"
    click CIT1 "https://github.com/jupyter/nbconvert-examples/blob/master/citations/Tutorial.ipynb"
    click CFNB "https://github.com/jupyter/nbconvert-examples/blob/master/custom_filter/notebook1.ipynb"
    click CPNB "https://github.com/jupyter/nbconvert-examples/blob/master/custom_preprocessor/notebook1.ipynb"
    click PTNB "https://github.com/jupyter/nbconvert-examples/blob/master/pdf/notebook.ipynb"
    click SCNB "https://github.com/jupyter/nbconvert-examples/blob/master/sphinx_class/notebook1.ipynb"

    click CFNF "https://github.com/jupyter/nbconvert-examples/blob/master/custom_filter/null_highlight_filter.py"
    click CF_CFG "https://github.com/jupyter/nbconvert-examples/blob/master/custom_filter/ipython_nbconvert_config.py"
    click CP_PP "https://github.com/jupyter/nbconvert-examples/blob/master/custom_preprocessor/cheese_preprocessor.py"
    click CP_CFG "https://github.com/jupyter/nbconvert-examples/blob/master/custom_preprocessor/ipython_nbconvert_config.py"
    click CIT_TPL "https://github.com/jupyter/nbconvert-examples/blob/master/citations/citations.tplx"
    click SC_PP "https://github.com/jupyter/nbconvert-examples/blob/master/sphinx_class/sphinx_preprocessor.py"
    click SC_CFG "https://github.com/jupyter/nbconvert-examples/blob/master/sphinx_class/ipython_nbconvert_config.py"
    click SC_TPLA "https://github.com/jupyter/nbconvert-examples/blob/master/sphinx_class/latex_sphinx_article.tplx"
    click SC_TPLR "https://github.com/jupyter/nbconvert-examples/blob/master/sphinx_class/latex_sphinx_report.tplx"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef extension fill:#ABEBC6,stroke:#229954,color:#1B2631
    classDef external fill:#F5CBA7,stroke:#B9770E,color:#1B2631
    classDef output fill:#D2B4DE,stroke:#6C3483,color:#1B2631
    classDef notebook fill:#F9E79F,stroke:#B7950B,color:#1B2631
```
