Adding custom styled paragraphs in markdown cells

Question

I want to add more formatting elements than provided by the Markdown synthax in an IPython Notebook.

For example, I want to add a "Warning Box" or a "Memo Box" that are basically paragraph with different styles (for example different background color, border, an icon, etc...).

I guess I can add HTML code in the cell, for example a <div> with an inline style. But what is the "proper" way to do that, I mean the one that ipython developer promote?

Examples appreciated.

NB: I'm using the current 1.0dev version from git master.

Answer 1

These custom css styles are already added in ipython version 2 and higher.

<div class="alert">
As of IPython 2.0, the user interface has changed significantly
</div>

---

<div class="alert alert-success">
Enter edit mode by pressing `Enter`
</div>

---

<div class="alert alert-error">
Don't try to type into a cell in command mode
</div>

Just paste this in the cell and change it to markdown type.

Check this for the examples and ipython in depth for the cutting edge features of ipython.

Answer 2

Another mean consists to simply create a style chain and open it with iPython HTML object in a code cell:

from IPython.display import HTML
style = "<style>div.warn { background-color: #fcf2f2;border-color: #dFb5b4; border-left: 5px solid #dfb5b4; padding: 0.5em;}</style>"
HTML(style)

Then use it in a markdown cell:

<div class="warn">Warning!</div>

Answer 3

A simple way to add warning, note, success (etc...) boxes (also called admonition or alert boxes) is simply using the bootstrap classes already included with the notebook. The only caveat is that links and other styles (e.g. bold) must be specified in HTML inside the box.

Example

A markdown cell containing this code:

# Upload data files
<p class="lead">This <a href="https://jupyter.org/">Jupyter notebook</a>
shows how to upload data files to be converted
to [Photon-HDF5](http://photon-hdf5.org) format. </p>

<i>Please send feedback and report any problems to the 
[Photon-HDF5 google group](https://groups.google.com/forum/#!forum/photon-hdf5).</i>

<br>
<div class="alert alert-warning">
<b>NOTE</b> Uploading data files is only necessary when running the notebook online.
</div>

will result in this output:

You can change alert-warning with alert-success, alert-info or alert-danger to get different colors for the box.

Answer 4

Answering to my own question...

Other solutions

Jim proposed to add some custom CSS style in a markdown cell of each notebook. This solution works, but is not convenient since you need to embed the style on each notebook. In my case I want a global style and I don't want to modify all the notebooks after every the style modification.

A natural solution would be using a custom file (custom.css) containing the style. However after trying these instructions the style is not applied to the notebook (it can be downloaded from the server though).

Best solution (so far)

I found a solution looking at this impressive book written as a collection of IPython notebooks. The author adds at the end of each notebook the following code cell:

from IPython.core.display import HTML
def css_styling():
    styles = open("./styles/custom.css", "r").read()
    return HTML(styles)
css_styling()

Putting a file custom.css in your notebook folder (in the styles subfolder), the style will be loaded after the first cell execution. Moreover the style will be magically loaded every time the notebook is opened, without the need to execute the cell again!

This magic trick works because the style is saved in the ouput cell the first time we execute it, and although being invisible, will be saved like any other output. So when we load the notebook, and conseguentely the output cells, the style will be applied.

Sample CSS

To complete the answer I post a CSS style I used to create a "Warning box":

<style>
div.warn {    
    background-color: #fcf2f2;
    border-color: #dFb5b4;
    border-left: 5px solid #dfb5b4;
    padding: 0.5em;
    }
 </style>

Save this style and load it using the code cell shown before. Now, to insert a warning box in your notebook use this syntax:

<div class=warn>
**Warning:** remember to do bookeping  
<div/>

That will be rendered like this:

For more general notebook styling you can take inspiration from the custom.css of the book mentioned above.

Answer 5

Update: This technique no longer works in IPython 4.0 / Jupyter since the way the notebook is rendered has changed.

I believe the best way to do such styling is to create a markdown entry at the top of your document and to collect your styles there. Since a markdown cell can contain any valid HTML code, it could contain (for instance)

<style>
    .warning { color: red; }
</style>

See Matt Davis' PyCon 2013 talk, about 22 minutes in during the Q&A for an example of this in use.