Skip to content

Commit ce93c39

Browse files
rasbtrasbt
committed
Creating a table of contents with internal links in IPython Notebooks and Markdown documents
1 parent efa50ac commit ce93c39

2 files changed

Lines changed: 225 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ Useful functions, tutorials, and other Python-related things
3434

3535
**// other**
3636

37+
- Creating a table of contents with internal links in IPython Notebooks and Markdown documents [[IPython nb](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/tutorials/table_of_contents_ipython.ipynb)]
3738
- Happy Mother's Day [[IPython nb]](http://nbviewer.ipython.org/github/rasbt/python_reference/blob/master/funstuff/happy_mothers_day.ipynb?create=1)
3839

3940

‎tutorials/table_of_contents_ipython.ipynb‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
{
2+
"metadata": {
3+
"name": "",
4+
"signature": "sha256:3c2a446633991d2794356f74854558a9fa03bb10b4498bc2f618afc26fedddcb"
5+
},
6+
"nbformat": 3,
7+
"nbformat_minor": 0,
8+
"worksheets": [
9+
{
10+
"cells": [
11+
{
12+
"cell_type": "markdown",
13+
"metadata": {},
14+
"source": [
15+
"[Sebastian Raschka](http://sebastianraschka.com) \n",
16+
"last updated: 05/18/2014\n",
17+
"\n",
18+
"- [Link to this IPython notebook on Github](https://github.com/rasbt/One-Python-benchmark-per-day/blob/master/ipython_nbs/day4_2_cython_numba_parakeet.ipynb) \n",
19+
"- [Link to the GitHub Repository One-Python-benchmark-per-day](https://github.com/rasbt/One-Python-benchmark-per-day)\n"
20+
]
21+
},
22+
{
23+
"cell_type": "markdown",
24+
"metadata": {},
25+
"source": [
26+
"<hr>\n",
27+
"I would be happy to hear your comments and suggestions. \n",
28+
"Please feel free to drop me a note via\n",
29+
"[twitter](https://twitter.com/rasbt), [email](mailto:bluewoodtree@gmail.com), or [google+](https://plus.google.com/118404394130788869227).\n",
30+
"<hr>"
31+
]
32+
},
33+
{
34+
"cell_type": "markdown",
35+
"metadata": {},
36+
"source": [
37+
"<a id='top'></a>"
38+
]
39+
},
40+
{
41+
"cell_type": "markdown",
42+
"metadata": {},
43+
"source": [
44+
"# Creating a table of contents with internal links in IPython Notebooks and Markdown documents"
45+
]
46+
},
47+
{
48+
"cell_type": "markdown",
49+
"metadata": {},
50+
"source": [
51+
"Many people have asked me how I create the table of contents in my IPython notebooks and Markdown documents with links. Well, no (IPython) magic is involved, it is just a little bit of HTML, but I thought it might be worthwhile to write up this little tutorial. \n"
52+
]
53+
},
54+
{
55+
"cell_type": "markdown",
56+
"metadata": {},
57+
"source": [
58+
"For example, [click this link](#bottom) to jump to the bottom of the page."
59+
]
60+
},
61+
{
62+
"cell_type": "markdown",
63+
"metadata": {},
64+
"source": [
65+
"## The two components to create an internal link"
66+
]
67+
},
68+
{
69+
"cell_type": "markdown",
70+
"metadata": {},
71+
"source": [
72+
"So how does it work? Basically, all you need are those two components: \n",
73+
"1. the destination\n",
74+
"2. an internal hyperlink to the destination"
75+
]
76+
},
77+
{
78+
"cell_type": "markdown",
79+
"metadata": {},
80+
"source": [
81+
"<br>"
82+
]
83+
},
84+
{
85+
"cell_type": "markdown",
86+
"metadata": {},
87+
"source": [
88+
"###1. The destination"
89+
]
90+
},
91+
{
92+
"cell_type": "markdown",
93+
"metadata": {},
94+
"source": [
95+
"To define the destination (i.e., the section on the page or the cell you want to jump to), you just need to insert an empty HTML anchor tag and give it an **`id`**, \n",
96+
"e.g., **`<a id='the_destination'></a>`** \n",
97+
"\n",
98+
"This anchor tag will be invisible if you render it as Markdown in the IPython notebook. \n",
99+
"Note that it would also work if we use the **`name`** attribute instead of **`id`**, but since the **`name`** attribute is not supported by HTML5 anymore, I would suggest to just use the **`id`** attribute, which is also shorter to type."
100+
]
101+
},
102+
{
103+
"cell_type": "markdown",
104+
"metadata": {},
105+
"source": [
106+
"<br>"
107+
]
108+
},
109+
{
110+
"cell_type": "markdown",
111+
"metadata": {},
112+
"source": [
113+
"###2. The internal hyperlink"
114+
]
115+
},
116+
{
117+
"cell_type": "markdown",
118+
"metadata": {},
119+
"source": [
120+
"Now we have to create the hyperlink to the **`<a id='the_destination'></a>`** anchor tag that we just created. \n",
121+
"We can either do this in ye goode olde HTML where we put a fragment identifier in form of a hash mark (`#`) in front of the name, \n",
122+
"for example, **`<a href='#the_destination'>Link to the destination'</a>`**\n",
123+
"\n",
124+
"Or alternatively, we can just use the slightly more convenient Markdown syntax: \n",
125+
"**`[Link to the destination](#the_destination)`**\n",
126+
"\n",
127+
"**That's all!**\n"
128+
]
129+
},
130+
{
131+
"cell_type": "markdown",
132+
"metadata": {},
133+
"source": [
134+
"<br>\n",
135+
"<br>"
136+
]
137+
},
138+
{
139+
"cell_type": "markdown",
140+
"metadata": {},
141+
"source": [
142+
"### One more piece of advice"
143+
]
144+
},
145+
{
146+
"cell_type": "markdown",
147+
"metadata": {},
148+
"source": [
149+
"Of course it would make sense to place the empty anchor tags for you table of contents just on top of each cell that contains a heading. \n",
150+
"E.g., "
151+
]
152+
},
153+
{
154+
"cell_type": "markdown",
155+
"metadata": {},
156+
"source": [
157+
"`<a id='section2'></a>` \n",
158+
"`###Section 2` \n",
159+
"`some text ...` "
160+
]
161+
},
162+
{
163+
"cell_type": "markdown",
164+
"metadata": {},
165+
"source": [
166+
"And I did this for a very long time ... until I figured out that it wouldn't render the Markdown properly if you convert you IPython notebook to HTML (for example, via the print preview option). \n",
167+
"\n",
168+
"Instead of "
169+
]
170+
},
171+
{
172+
"cell_type": "markdown",
173+
"metadata": {},
174+
"source": [
175+
"###Section 2"
176+
]
177+
},
178+
{
179+
"cell_type": "markdown",
180+
"metadata": {},
181+
"source": [
182+
"it would be rendered as"
183+
]
184+
},
185+
{
186+
"cell_type": "markdown",
187+
"metadata": {},
188+
"source": [
189+
"`###Section 2`"
190+
]
191+
},
192+
{
193+
"cell_type": "markdown",
194+
"metadata": {},
195+
"source": [
196+
"which is certainly not what we want (note that it looks normal in the IPython notebook, but not in the converted HTML version).\n",
197+
"<br>\n",
198+
"<br>\n",
199+
"<br>\n",
200+
"<hr>"
201+
]
202+
},
203+
{
204+
"cell_type": "markdown",
205+
"metadata": {},
206+
"source": [
207+
"[[Click this link and jump to the top of the page](#top)]"
208+
]
209+
},
210+
{
211+
"cell_type": "markdown",
212+
"metadata": {},
213+
"source": [
214+
"You can't see it, but this cell contains a \n",
215+
"`<a id='bottom'></a>` \n",
216+
"anchor tag just below this text.\n",
217+
"<a id='bottom'></a>"
218+
]
219+
}
220+
],
221+
"metadata": {}
222+
}
223+
]
224+
}

0 commit comments

Comments
 (0)