Table of contents #1692

vascot opened this Issue May 3, 2012 · 26 comments


None yet

Generate Table of Contents from Heading cells.

IPython member

Could you be more specific? A table of contents where, with what kind of UI, etc, do you have in mind?


I don't know what @vascot had in mind, but I ended up here looking for the following:
1. A table of contents based on the the either just the top level headers or one where the different header levels are indicated by different levels of indentation/numbering.
2. It would contain the titles of the different sections with links to anchors at the beginning of that section.
3. The placement would probably typically be after an opening markdown cell (i.e., one that includes a title an a brief introduction), but it could be left up to the user to place the table if/where they want it.

In other words, something almost identical to Wikipedia's tables of contents see an example here.

The use case for this is that with long notebooks users may want to jump to a particular point in the notebook rather than having to scroll through looking for a specific section that is hidden in the middle somewhere. This is particularly valuable for learning purposes, where someone can't remember how to do a specific thing, but they know that there is an example in a notebook.

IPython member

That would make sens in the toolbar to have maybe a dropdown menu with the level cells title.
The things we would need are a way to scroll a notebook to a specific cell, but that would be trivial :

fct = function(n)
value = IPython.notebook.get_cell(0).element.position().top-IPython.notebook.get_cell(n).element.position().top ; 
IPython.notebook.element.animate({scrollTop:-value}, 100);
return -value

It should even be easier if we transition to bootstrap.
making a dynamic drop down menu right now, is not the easiest thing on earth.

This could totally be part of a js extension anybody could wrote in their custom.js


I do have the problem that some of my notebooks for tutorials are so long that it becomes difficult to find things. A navigation menu that gives links to the headings would be awesome!


I really love the automatic table of content that is generated by docuwiki. Unobtrusive, and can also be set to appear only once a certain number of headings or levels are present.

This would also mean making the Markdown headers into anchor links. I really like how this is done at Github, where a little anchor pops up to the left of the headline when you mouse over it, unobtrusive, and removes the necessity to make the whole headline a link (which is kind of unsemantic I guess). Example

Screen Shot 2012-12-18 at 16 47 50

IPython member

This is partly what header cell are made for.
We also need to consider that notebooks have worksheet but the current implementation does not make anything with it.

We'll be happy if you want to take a shot at writing a way to have table of content, it shouldn't be too hard, and we could provide pointers if you have difficulties.

IPython member

Whenever you wish to try don't hesitate to ask question.
If you are a ruby guy, please have a look at #2643
We'll be happy to get your help.

IPython member

At the moment I simply use a custom menu CSS style in a markdown cell. The menu is always fixed and I can easily navigate. But you have to write the contents yourself.
Smth like this:

Or like this in a numbered style:

and the code itself:


After some days together with my colleague ( we found a better solution to autogenerate the Contents from the Headers using jQuery and simple CSS.

The ipnb example code:

And the toc code itself:

The only thing is that you have to put the code at the end of the ipnb file, so that the headers would have time to generate on page load. Of course there are ways to overcome this and we will probably do that in a while.


This would be a nice Magic: %toc :-)


Usually when I write my notebooks, I just put in a lot of headings while I'm writing in a single markdown cell. This extension doesn't work with that use case. I guess I could use the heading cells, but that would break up my flow more. It would be really nice if headings also could be generated from contents of markdown cells.

What's the opinion on this point?

IPython member

I find it also much easier to simply write MD and not use headings at all...

What is actually so problematic that MD can't handle it? MinRK explained in minrk/ipython_extensions#5 that MD is "not structure", but I don't see why ipython couldn't simple use MD only instead of headings cells (apart from the "Move complete substructure as indicated by a headline", which would need the abaility to split MD cells).


I agree with JanSchulz, I just tend to drop in headings and subheadings while I'm working in markdown cells, and then I want those headings to end up in a ToC (as I also discussed in minrk/ipython_extensions#5). It actually took me a good 20 minutes to figure out why my headings didn't show up after I loaded the (very nice) nbtoc extension.

IPython member

Because :

  • you need to parse each MD cell to find heading,
  • duplicate the functionality in nbconvert,
  • patch the markdown converter to have anchors in headers,
  • it will also conflict with the UI to move group of cell.
  • It is more difficult to convert to latex and other as you have to map the right depth of heading to the correct section/subsection/paragraph,
  • Have coherent css for header in and outside of MD cell
  • markdown support also different way of stating that something is a header, and this is not always obvious to get right as you have to know how the previous header was declared.
  • add mathjax support on top of that

I don't say that it is not feasible, nor that it will not be done in future. We just don't have the manpower to do it for now, even if we would like things like that.


@Carreau Well, that explains the difficulties of it quite well. I can see why it isn't so easy to implement. Thanks for the clarifying comment.

IPython member

No problem, it's not easy to fully understand if you are not familiar with both what already exist and what will be done. In the end if you take the habit of making something a header with keyboard shortcut it is not much more difficult than using plain old markdown and it will greatly help you when you will use nbconvert.

it is among the few things that I try to have people do, like not doing display_html() instead of defining _repr_foo_ on their object, or write iPython instead of IPython. It not a lot to learn and it will be a big plus for both users and dev later on.


I forked @minrk 's excellent TOC extension, and hacked in some functionality from @kmahelona to make a version which shows HTML headers in the TOC, in addition to header cells.

all credit goes to the two existing bits of javascript I copy-and-pasted from.

I realize that my approach doesn't obey the "all structure goes in header cells" mantra, and would not be as useful for things like LaTeX conversion, but a lot of folks seem to use HTML to structure their documents, so this is a usable workaround for those people. Since it works with both HTML and header cells, hopefully it can help during the transition toward exclusively using header cells.

It also completely ignores markdown headers, because those are just awful.


Hi, @jdavidheiser
I think that an example of notebook is needed to see the result
In particular I am interested in how it will look in nbviewer, because seemingly @magican 's example is displayed wrongly


@iamfullofspam - the TOC extension from @minrk that I forked is not inline, and will not show up in nbviewer. It's a floating panel that appears to the right side of the screen on any notebook you view locally after installing the extension. It doesn't modify your notebooks in any way. The point is to have something to make navigation of notebooks easier while you are working on them.


thanks for explanation.
Meanwhile I am using @kmahelona 's script, and a good thing to me is it works in nbviewer (with some problems, but still)


could you make toc itself support folding for each level? currently it can only be folded entirely.


Oh, I'd also love a floating TOC so much! On my big desktop screen I see exactly enough place on the left for a nice hierarchical TOC that moves with me as I scroll, letting me quickly jump to other sections of big notebooks. :)

I think the goal UX is something in line with the TOC offered in PDF readers (e.g. Evince in Linux, Preview in OS X). Being able to fold certain sections of cells would also be nice sometime in the future.

Regarding heading cells, I personally don't use them, as it's easier for me to remember # and ## in Markdown (don't know why heading cells were introduced as a separate entity instead of just a GUI way of generating the relevant Markdown), so it would be great if TOC could be made to use them as well.

@minrk minrk removed the type-enhancement label Jan 14, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment