Exporters

See also

Configuration options
Configurable options for the nbconvert application
nbconvert.exporters.export(exporter, nb, **kw)

Export a notebook object using specific exporter class.

Parameters:
  • exporter (Exporter class or instance) – Class or instance of the exporter that should be used. If the method initializes its own instance of the class, it is ASSUMED that the class type provided exposes a constructor (__init__) with the same signature as the base Exporter class.
  • nb (NotebookNode) – The notebook to export.
  • config (config (optional, keyword arg)) – User configuration instance.
  • resources (dict (optional, keyword arg)) – Resources used in the conversion process.
Returns:

output : str

The resulting converted notebook.

resources : dictionary

Dictionary of resources used prior to and during the conversion process.

Return type:

tuple

nbconvert.exporters.get_exporter(name)

Given an exporter name or import path, return a class ready to be instantiated

Raises ValueError if exporter is not found

nbconvert.exporters.get_export_names()

Return a list of the currently supported export targets

Exporters can be found in external packages by registering them as an nbconvert.exporter entrypoint.

Exporter base classes

class nbconvert.exporters.Exporter(config=None, **kw)

Class containing methods that sequentially run a list of preprocessors on a NotebookNode object and then return the modified NotebookNode object and accompanying resources dict.

__init__(config=None, **kw)

Public constructor

Parameters:
  • config (Config) – User configuration instance.
  • **kw – Additional keyword arguments passed to parent __init__
from_notebook_node(nb, resources=None, **kw)

Convert a notebook from a notebook node instance.

Parameters:
  • nb (NotebookNode) – Notebook node (dict-like with attr-access)
  • resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
  • **kw – Ignored
from_filename(filename, resources=None, **kw)

Convert a notebook from a notebook file.

Parameters:
  • filename (str) – Full filename of the notebook file to open and convert.
  • resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
  • **kw – Ignored
from_file(file_stream, resources=None, **kw)

Convert a notebook from a notebook file.

Parameters:
  • file_stream (file-like object) – Notebook file-like object to convert.
  • resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
  • **kw – Ignored
register_preprocessor(preprocessor, enabled=False)

Register a preprocessor. Preprocessors are classes that act upon the notebook before it is passed into the Jinja templating engine. preprocessors are also capable of passing additional information to the Jinja templating engine.

Parameters:
  • preprocessor (Preprocessor) – A dotted module name, a type, or an instance
  • enabled (bool) – Mark the preprocessor as enabled
class nbconvert.exporters.TemplateExporter(config=None, **kw)

Exports notebooks into other file formats. Uses Jinja 2 templating engine to output new formats. Inherit from this class if you are creating a new template type along with new filters/preprocessors. If the filters/ preprocessors provided by default suffice, there is no need to inherit from this class. Instead, override the template_file and file_extension traits via a config file.

Filters available by default for templates:

  • add_anchor
  • add_prompts
  • ansi2html
  • ansi2latex
  • ascii_only
  • citation2latex
  • comment_lines
  • convert_pandoc
  • escape_latex
  • filter_data_type
  • get_lines
  • get_metadata
  • highlight2html
  • highlight2latex
  • html2text
  • indent
  • ipython2python
  • json_dumps
  • markdown2asciidoc
  • markdown2html
  • markdown2latex
  • markdown2rst
  • path2url
  • posix_path
  • prevent_list_blocks
  • strip_ansi
  • strip_dollars
  • strip_files_prefix
  • wrap_text
__init__(config=None, **kw)

Public constructor

Parameters:
  • config (config) – User configuration instance.
  • extra_loaders (list[of Jinja Loaders]) – ordered list of Jinja loader to find templates. Will be tried in order before the default FileSystem ones.
  • template (str (optional, kw arg)) – Template to use when exporting.
from_notebook_node(nb, resources=None, **kw)

Convert a notebook from a notebook node instance.

Parameters:
  • nb (NotebookNode) – Notebook node
  • resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
from_filename(filename, resources=None, **kw)

Convert a notebook from a notebook file.

Parameters:
  • filename (str) – Full filename of the notebook file to open and convert.
  • resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
  • **kw – Ignored
from_file(file_stream, resources=None, **kw)

Convert a notebook from a notebook file.

Parameters:
  • file_stream (file-like object) – Notebook file-like object to convert.
  • resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
  • **kw – Ignored
register_preprocessor(preprocessor, enabled=False)

Register a preprocessor. Preprocessors are classes that act upon the notebook before it is passed into the Jinja templating engine. preprocessors are also capable of passing additional information to the Jinja templating engine.

Parameters:
  • preprocessor (Preprocessor) – A dotted module name, a type, or an instance
  • enabled (bool) – Mark the preprocessor as enabled
register_filter(name, jinja_filter)

Register a filter. A filter is a function that accepts and acts on one string. The filters are accessible within the Jinja templating engine.

Parameters:
  • name (str) – name to give the filter in the Jinja engine
  • filter (filter) –

Specialized exporter classes

The NotebookExporter inherits directly from Exporter, while the other exporters listed here inherit either directly or indirectly from TemplateExporter.

class nbconvert.exporters.NotebookExporter(config=None, **kw)

Exports to an IPython notebook.

This is useful when you want to use nbconvert’s preprocessors to operate on a notebook (e.g. to execute it) and then write it back to a notebook file.

class nbconvert.exporters.HTMLExporter(config=None, **kw)

Exports a basic HTML document. This exporter assists with the export of HTML. Inherit from it if you are writing your own HTML template and need custom preprocessors/filters. If you don’t need custom preprocessors/ filters, just change the ‘template_file’ config option.

class nbconvert.exporters.SlidesExporter(config=None, **kw)

Exports HTML slides with reveal.js

class nbconvert.exporters.LatexExporter(config=None, **kw)

Exports to a Latex template. Inherit from this class if your template is LaTeX based and you need custom tranformers/filters. Inherit from it if you are writing your own HTML template and need custom tranformers/filters. If you don’t need custom tranformers/filters, just change the ‘template_file’ config option. Place your template in the special “/latex” subfolder of the ”../templates” folder.

class nbconvert.exporters.MarkdownExporter(config=None, **kw)

Exports to a markdown document (.md)

class nbconvert.exporters.PDFExporter(config=None, **kw)

Writer designed to write to PDF files.

This inherits from LatexExporter. It creates a LaTeX file in a temporary directory using the template machinery, and then runs LaTeX to create a pdf.

class nbconvert.exporters.PythonExporter(config=None, **kw)

Exports a Python code file.

class nbconvert.exporters.RSTExporter(config=None, **kw)

Exports reStructuredText documents.