Exporting

Some extensions add functionality you might want to keep when exporting a notebook to another format using nbconvert.

There are several parts to customize nbconvert output:
  • Preprocessors to change content before conversion to another format
  • Postprocessors to change content after conversion to another format
  • Exporters to actually do the conversion to another format
  • Templates provide customization using Jinja without writing an exporter

Preprocessors

Generic documentation for preprocessors can be found at nbconvert.readthedocs.io/en/latest/api/preprocessors.html.

Executing and updating timing metadata

class jupyter_contrib_nbextensions.nbconvert_support.ExecuteTimePreprocessor(**kw)

Executes all the cells in a notebook, updating their ExecuteTime metadata.

Retaining Codefolding

class jupyter_contrib_nbextensions.nbconvert_support.CodeFoldingPreprocessor(**kw)

nbconvert Preprocessor for the code_folding nbextension.

Folds codecells as displayed in the notebook. The hidden code below the fold gets removed.

The preprocessor is installed by default. To enable codefolding with NbConvert, you need to set the configuration parameter CodeFoldingPreprocessor.remove_folded_code=True. This can be done either in the jupyter_nbconvert_config.py file:

c.CodeFoldingPreprocessor.remove_folded_code=True = True

or using a command line parameter when calling NbConvert:

$ jupyter nbconvert --to html --CodeFoldingPreprocessor.remove_folded_code=True mynotebook.ipynb
The folding mark can be configured using
c.CodeFoldingPreprocessor.fold_mark = ‘<->’

Retaining Highlighting

class jupyter_contrib_nbextensions.nbconvert_support.HighlighterPreprocessor(**kw)

nbconvert Preprocessor for the highlighter nbextension.

The preprocessor replaces highlighter html tags in markdown with a “neutral” text version, which enables markdown conversion of text included in the data field, command or environment. Then the neutral text is translated into LaTeX/html output by the corresponding HighlighterPostProcessor.

For example the highlighter-created markdown

<span class="mark"> *text* </span>

is translated for html conversion into:

!oph!span class="mark"!clh! *text* !oph!/span!clh!

or for LaTeX conversion is translated into:

!sl!highlighta!op! *text* !cl!

Evaluating code in Markdown (PyMarkDown)

class jupyter_contrib_nbextensions.nbconvert_support.PyMarkdownPreprocessor(**kw)

nbconvert Preprocessor for the python-markdown nbextension.

This Preprocessor replaces kernel code in markdown cells with the results stored in the cell metadata.

Converting linked SVG to PDF

class jupyter_contrib_nbextensions.nbconvert_support.SVG2PDFPreprocessor(**kw)

Preprocessor to convert svg graphics embedded in notebook markdown to PDF. Example for a markdown cell image:

![My graphic](graphics.svg)

Because LaTeX can’t use SVG graphics, they are converted to PDF using inkscape. This preprocessor is for SVG graphics in markdown only. For SVG outputs from codecells, there is already the built-in nbconvert preprocessor.

Configuration:

c.Exporter.preprocessors.append(
    "jupyter_contrib_nbextensions.nbconvert_support.SVG2PDFPreprocessor"
)

Postprocessors

Generic documentation for postprocessors can be found at nbconvert.readthedocs.io/en/latest/api/postprocessors.html

Retaining Highlighting

class jupyter_contrib_nbextensions.nbconvert_support.HighlighterPostProcessor(**kw)

nbconvert PostProcessor for the highlighter nbextension.

Replaces the “neutral” text versions created by the HighlighterPreprocessor by the destination language tags.

e.g. the html example becomes

<span class="mark"> <em>text</em> </span>

(the data text have been correctly emphasized in html markup)

e.g. the LaTeX example becomes

\highlighta{\emph{text}}

(the data text have been correctly emphasized using LaTeX tags)

Exporters

Generic documentation for exporters can be found at

nbconvert.readthedocs.io/en/latest/api/exporters.html

Embed images in HTML

class jupyter_contrib_nbextensions.nbconvert_support.EmbedHTMLExporter(config=None, **kw)

nbconvert Exporter which embeds graphics as base64 into html.

Convert to HTML and embed graphics (pdf, svg and raster images) in the HTML file.

Example usage:

jupyter nbconvert --to html_embed mynotebook.ipynb

Allows embedding images (pdf, svg and raster images) into a HTML file as base64 encoded binary, instead of linking to them.

jupyter nbconvert –to html_embed –NbConvertApp.codefolding=True mynotebook.ipynb

Export Table of Contents

class jupyter_contrib_nbextensions.nbconvert_support.TocExporter(config=None, **kw)

nbconvert HTMLExporter which embeds the toc2 nbextension.

Export table of contents nbextension functionality to html. The idea is to link a relevant part of the javascript nbextension and the css, and add a small script in the html file.

Example usage:

jupyter nbconvert --to html_toc FILE.ipynb

Inlining css & javascript

class jupyter_contrib_nbextensions.nbconvert_support.ExporterInliner(config=None, **kw)

Forms the basis for ExporterCollapsibleHeadings.

Collapsible Headings

class jupyter_contrib_nbextensions.nbconvert_support.ExporterCollapsibleHeadings(*args, **kwargs)

HTMLExporter which inlines the collapsible_headings nbextension.

Export collapsible_headings nbextension functionality to html by inlining relevant css and js content.

Example usage:

jupyter nbconvert --to html_ch FILE.ipynb

Templates

Generic documentation on templates can be found at nbconvert.readthedocs.io/en/latest/customizing.html

The main jupyter contrib nbextension install command will attempt to alter the nbconvert config to include the package’s templates directory, as mentioned in Config files edited by jupyter_contrib_nbextensions. This should allow you to use the templates nbextensions.tpl and nbextensions.tplx mentioned below just by specifying --template=nbextensions in your call to nbconvert.

To find the location of the custom templates you can use this function: .. autofunction:: templates_directory

nbextensions.tpl

This is a template for notebook extensions that allows hiding code cells, output, or text cells. Usage:

$ jupyter nbconvert --template=nbextensions mynotebook.ipynb
The supported cell metadata tags are:
  • cell.metadata.hidden - hide complete cell
  • cell.metadata.hide_input - hide code cell input
  • cell.metadata.hide_output - hide code cell output

Detailed description:

This will hide the input of either an individual code cell or all code cells of the notebook: .. code-block:

{% block input_group -%}
{%- if cell.metadata.hide_input or nb.metadata.hide_input -%}
{%- else -%}
{{ super() }}
{%- endif -%}
{% endblock input_group %}

This will hide the output of an individual code cell: .. code-block:

{% block output_group -%}
{%- if cell.metadata.hide_output -%}
{%- else -%}
    {{ super() }}
{%- endif -%}
{% endblock output_group %}

This will suppress the prompt string if the input of a code cell is hidden: .. code-block:

{% block output_area_prompt %}
{%- if cell.metadata.hide_input or nb.metadata.hide_input -%}
    <div class="prompt"> </div>
{%- else -%}
    {{ super() }}
{%- endif -%}
{% endblock output_area_prompt %}

nbextensions.tplx

This template implements the features to hide cells used by extensions like hide_input, etc. It won’t produce a valid LaTeX file alone, use it to extend your own template (see printviewlatex.tplx).

printviewlatex.tplx

This template can be used to customize nbconvert when creating LaTex or PDF documents. It extends the nbextensions.tplx template: .. code-block:

((= Nbconvert custom style for LaTeX export =))
((*- extends 'nbextensions.tplx' -*))

The first block is to .. code-block:

%===============================================================================
% Custom definitions
%===============================================================================
((* block definitions *))
    ((( super() )))

    % Pygments definitions
    ((( resources.latex.pygments_definitions )))

    % Exact colors from NB
    \definecolor{incolor}{rgb}{0.0, 0.0, 0.5}
    \definecolor{outcolor}{rgb}{0.545, 0.0, 0.0}

    % Don't number sections
    \renewcommand{\thesection}{\hspace*{-0.5em}}
    \renewcommand{\thesubsection}{\hspace*{-0.5em}}

((* endblock definitions *))

% No title
((* block maketitle *))((* endblock maketitle *))

The next block contains .. code-block:

%===============================================================================
% Latex Article
%===============================================================================
% You can customize your LaTeX document here, e.g. you can
% - use a different documentclass like
%   \documentclass{report}
% - add/remove packages (like ngerman)

((* block docclass *))
% !TeX spellcheck = de_DE
% !TeX encoding = UTF-8
\documentclass{scrreprt}
\usepackage{ngerman}
((* endblock docclass *))

Usage:

$ jupyter nbconvert --to=latex --template=printviewlatex mynotebook.ipynb

The result without specifying a custom template looks like this:

nbconvert output without template

If you specify the printviewlatex template, it should look like this:

nbconvert output without template

If you want to customize the template, simply copy printviewlatex.tplx and modify it.