-
Notifications
You must be signed in to change notification settings - Fork 71
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
nbtoc does not work with markdown headlines #5
Comments
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 |
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 |
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.
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.
We use pandoc for the markdown to latex conversion in nbconvert, I don't think this has any relevance here. |
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.
Not sure how to fix that, my jquery isn't good enough for this :-/
The text was updated successfully, but these errors were encountered: