This is one of the 100 recipes of the IPython Cookbook, the definitive guide to high-performance scientific computing and data science in Python.

3.4. Customizing the CSS style in the notebook (IPython 4)

You will need the CSS dataset on the book's website. (http://ipython-books.github.com)

You are expected to know a bit of CSS3 for this recipe. You can find many tutorials online (see references at the end of this recipe).

This recipe is significantly different for IPython 4.x and IPython 3.x (and below). IPython configuration files are organized in grops called profiles, which can be easilly chosen on IPython startup. In the case of IPython 3, a profile contains configuration for both IPython kernel and the front-ends (including the HTML notebook). With IPython 4, the language independent front-ends are separated into a new project, Jupyter, which has its own configuration directory, (~/.jupyter by default). IPython 4 still supports profiles, but they contain only kernel-related configuration. Jupyter does not have a notion of profiles.

In this recipe, we are modifying the Notebook look, but we want to do it in a way that it does not mess up the default look. With IPython 3, it can be easilly done by using a dedicated profile. With Jupyter, it can still be done, but in a more convoluted way. This version of the recipe shows how to do it with IPython 4 and Jupyter.

1. First, we retrieve in Python the path to the default Jupyter configuration directory (this should be ~/.jupyter).

In [ ]:
confdir = !jupyter --config-dir
confdir = confdir[0]
confdir

2. Now, we create a new Jupyter configuration directory, called css_profile, inside the default one, to avoid messing with our regular Jupyter configuration. We also create a subdirectory custom to hold our HTML customizations. The CSS file will be called custom.css.

In [ ]:
import os
cssprofdir = os.path.realpath(os.path.join(
            confdir, 'css_profile'))
cssdir = os.path.join(cssprofdir, 'custom')
csspath = os.path.join(cssdir, 'custom.css')
os.makedirs(cssdir)
In [ ]:
csspath

3. We can now edit this file here. We change the background color, the font size of code cells, the border of some cells, and we highlight the selected cells in edit mode.

In [ ]:
%%writefile {csspath}

body {
    /* Background color for the whole notebook. */
    background-color: #f0f0f0;
}

/* Level 1 headers. */
h1 {
    text-align: right;
    color: red;
}

/* Code cells. */
div.input_area > div.highlight > pre {
    font-size: 10px;
}

/* Output images. */
div.output_area img {
    border: 3px #ababab solid;
    border-radius: 8px;
}

/* Selected cells. */
div.cell.selected {
    border: 3px #ababab solid;
    background-color: #ddd;
}

/* Code cells in edit mode. */
div.cell.edit_mode {
    border: 3px red solid;
    background-color: #faa;
}

4. Now we can open a notebook with the css_profile configuration. The output of the following cell shows the command(s) to execute from the shell, depending on your operating system type:

In [ ]:
from sys import platform
if platform == 'win32':
    print('set JUPYTER_CONFIG_DIR="{0}"'.format(cssprofdir))
    print('jupyter notebook')
else:
    print('JUPYTER_CONFIG_DIR="{0}" jupyter notebook'.format(cssprofdir))

5. We can also use this stylesheet with nbconvert. We just have to convert a notebook to a static HTML document, and copy the custom.css file in the same folder. Here, we use a test notebook that has been downloaded on this book's website (see Getting started).

In [ ]:
!cp {csspath} custom.css
!jupyter nbconvert --to html data/test.ipynb

Here is how this HTML document look like:

In [ ]:
from IPython.display import IFrame
IFrame('test.html', 600, 650)

You'll find all the explanations, figures, references, and much more in the book (to be released later this summer).

IPython Cookbook, by Cyrille Rossant, Packt Publishing, 2014 (500 pages).