nbconvert Documentation

Filters are Python callables that take an input (typically text) and produce a text output. They are used within Jinja templates to perform specific transformations on cell content or metadata.

Example of a filter usage in an HTML template:

{{- output.text | ansi2html -}}

In this example, ansi2html is a filter transforming text output on stdout into HTML.

External exporters can expose custom options using the traitlets configurable API. You can configure these options using standard Jupyter configuration methods:

1. Configuration files: Use the syntax c.MyExporter.config_option=value.
2. Command line flags: Use the syntax --MyExporter.config_option=value.

Note that the specific configuration options available depend on the implementation of the exporter library itself.

When executing notebooks that contain Jupyter Widgets, their state can be stored in the notebook metadata to allow for proper rendering in tools like nbviewer or HTML exports.

• To disable storing widget state, set store_widget_state=False (via CLI or Python).
• Note that widget rendering is not performed in a browser during execution; only default states or states modified by user code are captured.
• If widget results are not visible after execution, you may need to 'Trust' the notebook in the Jupyter UI.

The nbconvert documentation is built using Sphinx. The following files and directories manage the build process and content:

• conf.py: The Sphinx build configuration file.
• source/: The directory containing the documentation source files.
• source/api/: The directory containing source files for the automatically generated API documentation.
• autogen_config.py: A script used to generate .rst files from .ipynb source files.
• index.rst: The main landing page for the Sphinx documentation.

Use the jupyter nbconvert command to convert .ipynb notebook files into various static formats using Jinja templates.

Supported output formats include:

• HTML
• LaTeX
• PDF
• Reveal JS
• Markdown (md)
• ReStructured Text (rst)
• executable script

The basic command structure is: jupyter nbconvert --to <output format> <input notebook>

$ jupyter nbconvert --to <output format> <input notebook>

Before starting a release, you can remove all non-tracked files from the repository using git clean. This ensures that stale builds or temporary files do not interfere with the new release. Note that this command will ask for confirmation before proceeding.

git clean -xfdi

To install nbconvert in editable mode for development, you must first ensure pandoc is installed on your system.

Prerequisite: Install Pandoc

• Ubuntu/Debian: sudo apt-get install pandoc
• macOS (Homebrew): brew install pandoc

Development Installation Steps

1. Clone the repository.
2. Install the package in editable mode using pip install -e ..

Running Tests After a development install, you can run the test suite by installing the test dependencies and using pytest:

1. pip install nbconvert[test]
2. py.test --pyargs nbconvert

git clone https://github.com/jupyter/nbconvert.git
cd nbconvert
pip install -e .

# To run tests:
pip install nbconvert[test]
py.test --pyargs nbconvert

To allow users to call your custom exporter by a short name instead of a fully qualified Python path, register it as a named entry point in your package's setup.py using the nbconvert.exporters group.

Example setup.py configuration:

setup(
    # ...
    entry_points={
        "nbconvert.exporters": [
            "simple = mymodule:SimpleExporter",
            "detail = mymodule:DetailExporter",
        ],
    }
)

Once installed, the exporter can be invoked via:

jupyter nbconvert --to detail mynotebook.ipynb