Custom Template

In some instances, we need to customize the page even more than the other tools allow us. The typical scenarios might be these:

• We want to apply the same styles or changes to all our reports.

• We want to change to change behavior of the default template, which does not suit us.

Pretty Jupyter handles these situations by allowing us to extend the basic template.

How to Extend

1. We need to create a new directory in our repository, where we save our new template files. We can name it for example our_template.

2. Create a new file called conf.json and store it in this new directory. The configuration file will specify, what is the output of the template and what is the base template. It should look like this:

   {
       "base_template": "pj",
       "mimetypes": {
           "text/html": true
       }
   }
   

3. Create a new file that will extend the Jinja template file from Pretty Jupyter. Name it for example index.html.j2 and place it into our_template directory. The file should look like this:

   {%- extends "pj.index.html.j2" -%}
   
   ...
   

4. In the new index.html.j2 file, override or extend some of the blocks to provide custom behavior. For example:

   {%- extends "pj.index.html.j2" -%}
   
   {% block notebooks_css %}
   {# call the super in this instance to apply default styles #}
   {{ super() }}
   
   <style>
       html {
           background-color: red;
       }
   </style>
   {% endblock notebook_css %}
   

Important

The files, such as index.html.j2, are Jinja template files. For more information about how they work, check out its documentation, specifically the sections about blocks and inheritance.

Exporting with Custom Template

To export the Jupyter notebook using our newly created template, we need to change the basic export command a little bit:

Code: Export with Custom Template

jupyter nbconvert --to html --template custom_template --TemplateExporter.extra_template_basedirs=path/to/directory/w/our/custom/template /path/to/ipynb/file

Blocks

Some of the most interesting that we can overide are:

• notebook_css: Specify styling for your pages here. It is highly recommended to call super in this block to apply default styles as well.

• notebook_js: Specify JavaScript for the pages here. It is highly recommended to call super, otherwise the page might break.

• page_header: We can provide a custom page header by overriding this block.

• main_container_start: Start of the main container. Can be added to provide notebook-level logo etc.

• main_container_end: End of the main container. Can be used for a footer.

Examples

Check out Pretty Jupyter’s example repository, specifically:

• extending-template: This example shows how to customize the template. It overrides page_header and removes it and specifies the header inside main_container_start. It also specifies a custom footer in main_container_end.