Getting Started


Using Conda is recommended for package management, in order to create self contained environments with specific versions of packages. The main external packages required are the Jupyter notebook and Pandoc (for conversion between file formats):

conda create --name ipyreport -c conda-forge jupyter pandoc

ipypublish can then be installed into this environment:

source activate ipyreport
pip install ipypublish

For converting to PDF, the TeX document preparation ecosystem is required, in particular latexmk), which can be installed from:

For helpful extensions to the notebooks core capabilities, see the Jupyter Notebook Extensions package:

conda install --name ipyreport jupyter_contrib_nbextensions

Additionally, a more extensive setup of useful packages (used to create the examples) are listed in conda_packages.txt and an environment can be created directly from this file using conda:

conda create --name ipyreport -c conda-forge -c matsci --file conda_packages.txt

Basic Conversion

The nbpublish script handles parsing the notebooks to nbconvert, with the appropriate converter.

nbpublish -h
nbpublish -pdf -f latex_ipypublish_nocode path/to/notebook.ipynb

For a more detailed explanation see the Controlling Content Output section.

The nbpresent script handles serving reveal.js slides to a webbrowser.

nbpresent -h
nbpresent -f slides_ipypublish_nocode path/to/notebook.ipynb

Note that, for offline use, simply download the latest version of reveal.js here, rename the entire folder to reveal.js and place it in the same folder as the converted .slides.html file. The slides can also be save to PDF my appending pdf-export to the url (see here for details).


For installation issues, Travis CI is used to automatically test updates against python 2.7 and 3.6, for both Linux and OSX, Therefore, to troubleshoot any installation/run issues, it is best to first look at the travis config and travis test runs for working configurations.

For conversion issues, for both nbpublish and nbpresent, detailed log messages of the run are output to both the console and file (default path: converted/notebook_name.nbpub.log). To debug conversions, use the --log-level debug and --pdf-debug flags. If there is still an error, please raise an issue on the GitHub repository, including the run environment and the log file.


See Example.ipynb, Example.pdf, Example.html and Example.slides.html for an example of the potential input/output.

Or, for a practical example of the ipypublish capability, see these documents on Atomic 3D Visualisation: Notebook, PDF, HTML or Reveal.JS slideshow.