How jupyter/nbconvert works
Project type and purpose
• This repository is the Jupyter “nbconvert” tool: an open-source library and CLI application that converts .ipynb Jupyter notebooks into static formats (HTML, LaTeX, PDF, Markdown, reStructuredText, scripts, slides, etc.) via Jinja templates.
• It provides both a jupyter nbconvert command-line entry point and a Python API, plus template files, plugin points (exporters, preprocessors, postprocessors, filters), and optional integration with external tools (e.g., Pandoc).
High-level file-structure analysis
• Top-level directories and files:
• nbconvert/ – core Python package
• share/templates/ – shipped Jinja template sets for each output format
• tests/ – unit & integration tests for export pipeline, filters, preprocessors, writers
• docs/ – Sphinx-based documentation and API examples
• CLI-related files: __main__.py, nbconvertapp.py, pyproject.toml, hatch_build.py
• Config & CI: .github/workflows/, .pre-commit-config.yaml, readthedocs.yaml
• Within nbconvert/ package:
• nbconvertapp.py – application entry, argument parsing, pipeline orchestration
• exporters/ – per-format exporter implementations (HTML, PDF, markdown, etc.)
• preprocessors/ – transformations applied before rendering (execution, clearing output, sanitization)
• postprocessors/ – operations after rendering (e.g., serving HTML, file cleanup)
• filters/ – granular content filters used by templating stage
• writers/ – final writers delivering output to stdout or files
• templates/ – built-in skeletons; overridden at runtime by share/templates/
• utils/ – common utilities (I/O, versioning, exceptions)
README insights
• Emphasizes the CLI usage: jupyter nbconvert --to <format> <notebook>
• Mentions Jinja templating and optional external dependency on Pandoc
a. Main components:
1) CLI / main application (nbconvertapp)
2) Notebook reader (JSON loader)
3) Preprocessor chain
4) Template renderer (Exporter + Jinja engine + Filters)
5) Postprocessor chain
6) Writer (file or stdout output)
7) Template store (share/templates / user templates)
8) External tools (Pandoc)
b. Relationships & data flow:
• User invokes CLI → nbconvertapp parses args → loads .ipynb JSON
→ passes NotebookNode into a sequence:
Preprocessors → Exporter.render() (uses Filters + Jinja templates + Resources)
→ yields rendered output → Postprocessors → Writer writes result
• Optionally, Exporter may shell out to Pandoc or other binaries
c. Architectural patterns / design principles:
• Pipeline pattern: ordered chains of preprocessors & postprocessors
• Plugin architecture: exporters, preprocessors, filters, writers are all pluggable via entry points
• Separation of concerns: parsing, transforming, templating, writing
• Configuration & extensibility: external templates override built-ins; custom preprocessors can be injected at runtime
d. Key technologies / frameworks:
• Python 3.x modules & entry-points (packaged via pyproject.toml / setuptools)
• Jinja2 templating engine
• JSON parsing (nbformat)
• Optional Pandoc integration
Final guidance
• Essential layers (CLI vs API, Pipeline vs I/O)
• Keep it focused on runtime conversion pipeline; omit dev/test folders unless illustrating CI/CD or docs build