# jupyter/nbconvert

ab9632e Feb 16, 2019
10 contributors

### Users who have contributed to this file

304 lines (204 sloc) 9.35 KB

# Using as a command line tool

The command-line syntax to run the nbconvert script is:



## Supported output formats

The currently supported output formats are:

Jupyter also provides a few templates for output formats. These can be specified via an additional --template argument and are listed in the sections below.

### HTML

• --to html

• --template full (default)

A full static HTML render of the notebook. This looks very similar to the interactive view.

• --template basic

Simplified HTML, useful for embedding in webpages, blogs, etc. This excludes HTML headers.

### LaTeX

• --to latex

Latex export. This generates NOTEBOOK_NAME.tex file, ready for export. Images are output as .png files in a folder.

• --template article (default)

Latex article, derived from Sphinx's howto template.

• --template report

• --template base

Very basic latex output - mainly meant as a starting point for custom templates.

Note

nbconvert uses pandoc to convert between various markup languages, so pandoc is a dependency when converting to latex or reStructuredText.

### PDF

• --to pdf

Generates a PDF via latex. Supports the same templates as --to latex.

### Reveal.js HTML slideshow

• --to slides

This generates a Reveal.js HTML slideshow.

Running this slideshow requires a copy of reveal.js (version 3.x).

By default, this will include a script tag in the html that will directly load reveal.js from a public CDN.

This means that if you include your slides on a webpage, they should work as expected. However, some features (specifically, speaker notes & timers) will not work on website because they require access to a local copy of reveal.js.

Speaker notes require a local copy of reveal.js. Then, you need to tell nbconvert how to find that local copy.

To make this clearer, let's look at an example of how to get speaker notes working with a local copy of reveal.js: SlidesWithNotesExample.

Note

In order to designate a mapping from notebook cells to Reveal.js slides, from within the Jupyter notebook, select menu item View --> Cell Toolbar --> Slideshow. That will reveal a drop-down menu on the upper-right of each cell. From it, one may choose from "Slide," "Sub-Slide", "Fragment", "Skip", and "Notes." On conversion, cells designated as "skip" will not be included, "notes" will be included only in presenter notes, etc.

#### Example: creating slides w/ speaker notes

Let's suppose you have a notebook your_talk.ipynb that you want to convert to slides. For this example, we'll assume that you are working in the same directory as the notebook you want to convert (i.e., when you run ls ., your_talk.ipynb shows up amongst the list of files).

First, we need a copy of reveal.js in the same directory as your slides. One way to do this is to use the following commands in your terminal:

git clone https://github.com/hakimel/reveal.js.git
cd reveal.js
git checkout 3.5.0
cd ..

Then we need to tell nbconvert to point to this local copy. To do that we use the --reveal-prefix command line flag to point to the local copy.

jupyter nbconvert your_talk.ipynb --to slides --reveal-prefix reveal.js

This will create file your_talk.slides.html, which you should be able to access with open your_talk.slides.html. To access the speaker notes, press s after the slides load and they should open in a new window.

Note: This does not enable slides that run completely offline. While you have a local copy of reveal.js, by default, the slides need to access mathjax, require, and jquery via a public CDN. Addressing this use case is an open issue and PRs are always encouraged.

#### Serving slides with an https server: --post serve

Once you have speaker notes working you may notice that your timers don't work. Timers require a bit more infrastructure; you need to serve your local copy of reveal.js from a local https server.

Fortunately, nbconvert makes this fairly straightforward through the use of the ServePostProcessor. To activate this server, we append the command line flag --post serve to our call to nbconvert.

jupyter nbconvert your_talk.ipynb --to slides --reveal-prefix reveal.js --post serve

This will run the server, which will occupy the terminal that you ran the command in until you stop it. You can stop the server by pressing ctrl C twice.

### Markdown

• --to markdown

Simple markdown output. Markdown cells are unaffected, and code cells indented 4 spaces. Images are output as .png files in a folder.

### Ascii

• --to asciidoc

Ascii output. Images are output as .png files in a folder.

### reStructuredText

• --to rst

Basic reStructuredText output. Useful as a starting point for embedding notebooks in Sphinx docs. Images are output as .png files in a folder.

Note

nbconvert uses pandoc to convert between various markup languages, so pandoc is a dependency when converting to LaTeX or reStructuredText.

### Executable script

• --to script

Convert a notebook to an executable script. This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook. If there were any magics in an Jupyter notebook, this may only be executable from a Jupyter session.

For example, to convert a Julia notebook to a Julia executable script:

jupyter nbconvert --to script my_julia_notebook.ipynb


### Notebook and preprocessors

• --to notebook

.. versionadded:: 3.0



This doesn't convert a notebook to a different format per se, instead it allows the running of nbconvert preprocessors on a notebook, and/or conversion to other notebook formats. For example:

jupyter nbconvert --to notebook --execute mynotebook.ipynb


This will open the notebook, execute it, capture new output, and save the result in :file:mynotebook.nbconvert.ipynb. Specifying --inplace will overwrite the input file instead of writing a new file. By default, nbconvert will abort conversion if any exceptions occur during execution of a cell. If you specify --allow-errors (in addition to the --execute flag) then conversion will continue and the output from any exception will be included in the cell output.

The following command:

jupyter nbconvert --to notebook --nbformat 3 mynotebook


will create a copy of :file:mynotebook.ipynb in :file:mynotebook.v3.ipynb in version 3 of the notebook format.

If you want to convert a notebook in-place, you can specify the output file to be the same as the input file:

jupyter nbconvert --to notebook mynb --output mynb


Be careful with that, since it will replace the input file.

Note

nbconvert uses pandoc to convert between various markup languages, so pandoc is a dependency when converting to latex or reStructuredText.

The output file created by nbconvert will have the same base name as the notebook and will be placed in the current working directory. Any supporting files (graphics, etc) will be placed in a new directory with the same base name as the notebook, suffixed with _files:

$jupyter nbconvert notebook.ipynb$ ls
notebook.ipynb   notebook.html    notebook_files/


For simple single-file output, such as html, markdown, etc., the output may be sent to standard output with:

$jupyter nbconvert --to markdown notebook.ipynb --stdout  ## Converting multiple notebooks Multiple notebooks can be specified from the command line: $ jupyter nbconvert notebook*.ipynb
$jupyter nbconvert notebook1.ipynb notebook2.ipynb  or via a list in a configuration file, say mycfg.py, containing the text: c = get_config() c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]  and using the command: $ jupyter nbconvert --config mycfg.py
`