[Feature Request] Ignore header in table of contents (toc)

[j1elo]

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!

[waylan]

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_depth config option.

[iBug]

Ruby Kramdown already ignores headings with class no_toc in ToC generation. What about just adopting this setup for "compatibility" (so users migrate their documents easier)?

[j1elo]

seem more reasonable to me to ignore all headers above and/or below a certain level

That's the most typical way to skip elements in a TOC, yes. But it's a different thing.

Say you have this:

# Topic title
## Advanced comments on the topic

# Examples
## Example 1: with Java
## Example 2: with C++

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]

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.