Ipython Notebook Markdown

Posted on  by admin

Many people have asked me how I create the table of contents withinternal links for my IPython Notebooks and Markdown documents onGitHub. Well, no (IPython) magic is involved, it is just a little bit ofHTML, but I thought it might be worthwhile to write this little how-totutorial.

Select the cell you want to convert, and then: Select Cell from the top navigation Cell Type Markdown. There's also a shortcut – Select the cell, press ESC (escape key) and enter the command mode, then press M. This way the cell will get converted from Code to Markdown. After converting the cell to Markdown, refer the guide below. The IPython Notebook is now known as the Jupyter Notebook. It is an interactive computational environment, in which you can combine code execution, rich text, mathematics, plots and rich media. For more details on the Jupyter Notebook, please see the Jupyter website. A Jupyter Notebook of Markdown examples given in the book can be downloaded here: jupyter-markdown.zip: the Notebook and associated media files. A static HTML version of the Notebook. Note: As of April 2015, IPython Notebook has evolved into part of the Jupyter Project.Jupyter Project.

In ipython, there are markdown cells available but you cannot execute any code there. So what if you want to show the markdown output generated by a code cell in ipython notebook? It would look like this: The only problem: the ipython magic “asmarkdown” (as shown in the screenshot) does not exist.

You can find and download many example IPython Notebooks in my GitHubrepository


For example, click this link to jump to the bottom of thepage.

The two components to create an internal link

So, how does it work? Basically, all you need are those two components:

  1. the destination
  2. an internal hyperlink to the destination

1. The destination

To define the destination (i.e., the section on the page or the cell youwant to jump to), you just need to insert an empty HTML anchor tag andgive it an id,
e.g., <a></a>


This anchor tag will be invisible if you render it as Markdown in theIPython Notebook.
Note that it would also work if we use the name attribute insteadof id, but since the name attribute is not supported byHTML5 anymore, I would suggest to just use the id attribute, whichis also shorter to type.

2. The internal hyperlink

Now we have to create the hyperlink to the<a></a> anchor tag that we just created. We can either do this in ye goode olde HTML where we put a fragmentidentifier in form of a hash mark (#) in front of the name,for example,
<a href='#the_destination'>Link to the destination'</a>

Or alternatively, we can just use the slightly more convenient Markdownsyntax:
[Link to the destination](#the_destination)

Ipython notebook markdown numbered list

That’s all!

Jupyter Notebook Add Text

Of course it would make sense to place the empty anchor tags for youtable of contents just on top of each cell that contains a heading.

And I did this for a very long time … until I figured out that itwouldn’t render the Markdown properly if you convert the IPythonNotebook into HTML (for example, for printing via the print previewoption).

But instead of


Section 2

it would be rendered as

###Section 2


which is certainly not what we want (note that it looks normal in theIPython Notebook, but not in the converted HTML version). So my favoriteremedy would be to put the id-anchor tag into a separate cell justabove the section, ideally with some line breaks for nicer visuals.

Solution 1: id-anchor tag in a separate cell

Solution 2: using header cells

Ipynb Markdown

To define the hyperlink anchor tag to this “header cell” is just thetext content of the “header cell” connected by dashes. E.g.,

[link to another section](#Another-section)

[Click this link and jump to the top of the page]

Ipython Notebook Markdown Tutorial

Ipython markdown syntax

You can’t see it, but this cell contains a <a></a>anchor tag just below this text.