nbtoc does not work with markdown headlines
jankatins opened this issue · 9 comments
Nice new ToC plugin, thanks!
Unfortunately it doesn't recognize Markdown generated headlines.
Here are two examples (first H1 cell, second a markdown cell with a single entry "#MD-h1"), the first is turned into a ToC entry, the second only shows up as a number without the text.
<h1><a class="heading-anchor" href="#H1-cell" id="H1-cell">H1-cell</a></h1>
<h1>MD-h1</h1>
Not sure how to fix that, my jquery isn't good enough for this :-/
I actually think it should behave this way - structural deliberations should always be heading cells, not in the middle of markdown.
The H1 is not in the middle of a markdown cell :-) Usually I find it easier to write my introduction in markdown, including a headline and a paragraph explaining what I'm doing. I could actually do without headline cells at all :-)
Anyway: would you take a PR for %nbtoc --include-markdown?
No, I actually want to discourage that. When IPython gets proper / official outline views, it will definitely include only heading cells.
May I ask why headline cells are better than markdown (with headlines) cells? I found headline cells impractical because writing text was broken into one cell of headline and then opening another cell for text instead of once cell for both. Is it needed because some code depends on recognizing headlines?
Not sure, but I think that the h1 above (from a headline cell) can be easier written as <h1 id="Headline">Headline</h1>. The <a> shouldn't actually be necessary because it makes hovering over a headline behave as if you are over a link.
heading cells are meant as cells that actually describe document structure, so anything that performs actions on document structure (nbconvert, outline view, tabbed view, whole-section movement within a notebook, automatic anchor links) uses heading cells to indicate sections, whereas a header tag in a markdown cell is simply text formatting.
Isn't it logical to assume that headings in any markdown text would correspond to something worth including in a ToC, though? It's just a matter of workflow, I usually just dump in headings in whatever markdown cell I'm working in, and keep going. What I put as a markdown headline is also what I want indexed in e.g. a ToC.
I see the point about it being nice if headings are in their own cells to separate structure from content, but it's kind of counterintuitive to how I work. I guess I could relearn to just use heading cells, but it feels a bit cumbersome (and I guess part of the idea about Markdown is that you get nice formatting without the cumbersome html tagging part?).
I'm also guessing that every time a new person comes to the ipython notebook, they'll start doing what I'm doing (because it's so easy to just do #Heading ##subheading), and then they'll (also) want those headings in a ToC.
There will be many operations introduced that will only work on heading cells (tabbed view, outline view, whole-section operations). If you just want text formatting, then the markdown header formatting will be fine, but one of the things you will lose is conveying structural information. I want this TOC to reflect that, and in turn encourage people to use heading cells.
I still don't get it.
- If I want to move a part of a MD field around (because the lower part is under a different headline), you would simple have to split it.
- For moving around a complete section it would be more generic to simple mark cells and move them around (so "move part of a section" is also covered).
- The outline view (at least in the html notebook) can also be adjusted (just turn every
<h1>Hello World</h1>into<h1 id="Hello_World">Hello World</h1>via JS and use the id to link to the specific headline (`Hello World Headline. The current use of tages around the headline is actually not needed.) - Something like "run this section" might be tricky as you need to find the next headline in the next MD cells, but that can't be too hard, at least not in JS, where you have the rendered html (Algo: Add a button under each headline, run all cells until you find the next button of the same kind)?
- latex: knitr (http://yihui.name/knitr/) is able to turn MD into latex (ok, using pandoc. And the md2latex entension to the markdown package seems to be dead :-( )
I also don't think that structural information is missing: it's in the MD cell, so maybe not as easiely gotten than simple looking for a cell of type "headline", but headline cells are much more complicated to work with than MD cells (moving text around, adding a new headline in the middle of text, ...).
So the only thing missing is "add the next section as a new tab". If that's done in JS: no problem again, just use the rendered HTML and -tags. If done in the nb server: add a new cell for just that, but you still can get rid of all the heading cell types.
It is not impossible to build all of these things implicitly by scanning and manipulating the interior of markdown cells, but that is not how we plan to build these things. Heading cells denote structure, markdown cells do not. It's just a decision that has been made.
latex: knitr (http://yihui.name/knitr/) is able to turn MD into latex (ok, using pandoc. And the md2latex entension to the markdown package seems to be dead :-( )
We use pandoc for the markdown to latex conversion in nbconvert, I don't think this has any relevance here.