Skip to content
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

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

Open
j1elo opened this issue Aug 24, 2021 · 4 comments
Open

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

j1elo opened this issue Aug 24, 2021 · 4 comments
Labels
extension Related to one or more of the included extensions. feature Feature request. someday-maybe Approved low priority request.

Comments

@j1elo
Copy link

j1elo commented Aug 24, 2021

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
Copy link
Member

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

@waylan waylan added the needs-decision A decision needs to be made regarding request. label Aug 24, 2021
@iBug
Copy link

iBug commented Sep 17, 2021

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
Copy link
Author

j1elo commented Oct 8, 2021

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.

@waylan waylan added extension Related to one or more of the included extensions. feature Feature request. labels Nov 3, 2021
@waylan waylan added someday-maybe Approved low priority request. and removed needs-decision A decision needs to be made regarding request. labels Nov 7, 2023
@j-davis-2022
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
extension Related to one or more of the included extensions. feature Feature request. someday-maybe Approved low priority request.
Projects
None yet
Development

No branches or pull requests

4 participants