Table of contents

[vascot]

Generate Table of Contents from Heading cells.

[fperez]

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

[ethanwhite]

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.

[Carreau]

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

[cdeil]

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!

[houshuang]

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 https://github.com/hpiwowar/citation11k/blob/master/analysis/stats.md

[Carreau]

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.

[houshuang]

I'm just learning Python right now to do some statistics in IPython for a
research project (I used SPSS for a stats class last year, but never liked
it, this time I first thought about learning R, partly inspired by knitr
and executable documents, but then I came across IPython, pandas etc, and
Wes' book, and was very impressed)... I'm coming from Ruby, and slowly
picking it up. So not quite ready to jump into the code yet, but perhaps in
the future.

On Tue, Dec 18, 2012 at 6:22 PM, Bussonnier Matthias <
notifications@github.com> wrote:

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.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1692#issuecomment-11496213.

http://reganmian.net/blog -- Random Stuff that Matters

[Carreau]

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.

[ellisonbg]

The heading cells should definitely be used for generating things like a
table of contents - rather than Markdown headings...

On Tue, Dec 18, 2012 at 9:46 AM, Bussonnier Matthias <
notifications@github.com> wrote:

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

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1692#issuecomment-11497211.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[magican]

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:

http://nbviewer.ipython.org/urls/gist.github.com/magican/5546776/raw/9385e8f2c519e6a4880584ea42fd9d5b54b15ee1/ipnb_table_of_contents.ipnb

Or like this in a numbered style:

http://nbviewer.ipython.org/urls/gist.github.com/magican/5546776/raw/e1586476c52168f96c3191fb8bacb518eb4ff460/ipnb_table_of_contents.ipnb

and the code itself:

https://gist.github.com/magican/5546776

[magican]

After some days together with my colleague (https://github.com/nonamenix) we found a better solution to autogenerate the Contents from the Headers using jQuery and simple CSS.

The ipnb example code:

https://gist.github.com/magican/5578367

And the toc code itself:

https://gist.github.com/magican/5574556

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.

[jankatins]

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

[minrk]

@JanSchulz https://github.com/minrk/ipython_extensions/blob/master/nbtoc.py

[RKBK]

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?

[Carreau]

There are a few things that are to hard to do with heading in MD cells.

What we could allow (or could already be built as a js extension) would be
the ability to break a MD cell with different heading into the
corresponding header-cell and markdown cell.

Le mardi 18 juin 2013, RKBK a écrit :

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?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1692#issuecomment-19600373
.

[jankatins]

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).

[RKBK]

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.

[Carreau]

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.

[RKBK]

@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.

[Carreau]

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.

[jdavidheiser]

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.

https://github.com/jdavidheiser/ipython_extensions

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.

[arogozhnikov]

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 http://nbviewer.ipython.org/gist/anonymous/5578367

[jdavidheiser]

@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.

[arogozhnikov]

@jdavidheiser,
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)

[chiwhalee]

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

[metakermit]

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.