Repository navigation
[Feature Request] Ignore header in table of contents (toc) #1178
Description
It could be useful, and after seeing the code, almost trivial to add support to skip / ignore / omit some of the document headers, using a header attribute.
I'm thinking of something like this: https://bookdown.org/yihui/rmarkdown-cookbook/toc-unlisted.html
Using the Attribute Lists extension is a great way to allow users fine tune the desired behavior. Right now, the TOC extension allows using just one, data-toc-label, so I'd propose adding a data-toc-unlisted which disables adding the header to the TOC.
Code would be pretty minimal, something like this (but I'm no Python programmer so syntax may be off):
for el in doc.iter():
....
# Check if data-toc-unlisted attribute is present, to skip current element
if 'data-toc-unlisted' in el.attrib:
del el.attrib['data-toc-unlisted'] # Not sure if deleting the attr is really needed
continue # This is the key point: to skip the current element altogether
...Let me take the chance to say thank you to all maintainers and devs of this project!
Activity
waylan commentedon Aug 24, 2021
Interesting idea. The existing implementation elsewhere certainly helps.
However, I have to wonder what use case this meets. Seems weird to me to just skip one in a list of headers all from the same level. It would seem more reasonable to me to ignore all headers above and/or below a certain level, which we already support via the
toc_depthconfig option.iBug commentedon Sep 17, 2021
Ruby Kramdown already ignores headings with class
no_tocin ToC generation. What about just adopting this setup for "compatibility" (so users migrate their documents easier)?j1elo commentedon Oct 8, 2021
That's the most typical way to skip elements in a TOC, yes. But it's a different thing.
Say you have this:
Depending on the narrative, it might make perfect sense to have the "Advanced comments" as a subheading inside some title... and not having it appear in the TOC. Meanwhile, the "Examples" and each of its subsections would make sense in the TOC (so people interested in C++ can jump right into it). This is a typical scenario where excluding specific headers from TOC would be helpful, while the simpler mechanism of excluding higher or lower bounds becomes insufficient.
j-davis-2022 commentedon Mar 6, 2024
I'm working on a project where a feature like this would be very useful (at least, with my amateur coding ability).
I'm trying to build a fan wiki, and I noticed wikipedia has a sort of box with basic information to one side (example here: https://en.wikipedia.org/wiki/Cat_Quest). I want to be able to implement something similar purely with markdown, but I haven't found a way to omit the heading of the box that looks consistent with the rest of the page.
The only other option I can think of is to style an element or class to look like the header with CSS, but that might be bad for accessibility, so I'd rather not resort to that. I've edited the library in my personal project to add this functionality, but I think it would be easier in the long run, and for more people, to have it as a part of the code to begin with.