Limit automatic TOC generation to one TOC per file

[redactedscribe]

Proposal

At the top of my file I'm using a TOC generated by Markdown AIO. Later on in my file I have a list linking to four headings and Markdown AIO thinks that this should also be a TOC when I don't want it to be, thus saving generates a second TOC.

The only solution I know of currently is to not use a list for these four heading links, and instead mention them in the format of a sentence, for example.

Maybe the default should be to only allow one TOC per file? But I guess there might be cases where someone has a very long document and requires more than one, each with their own set of links (not sure if this is yet possible).

I think a configurable extension setting to limit TOCs to one per file would be ideal. I'm not fond of having extension specific references in my Markdown, even as comments (e.g. <!-- omit in toc -->), so a further setting similar to markdown.extension.toc.omittedFromToc but to override the number of allowable TOCs for files would be appreciated. If people want to override the max TOCs per file value via a comment, maybe it should also be supported.

Thank you.

[yzhang-gh]

Thanks for your feedback. I agree and I remember there was an issue asking for the same thing (one TOC per file) but couldn't find it now.

[jlahijani]

I'm having a similar issue. I have a document like this:

# My First Heading 
- eggs
- bacon
- cheese

# My Second Heading
- apples
- oranges
- bananas

For some reason, Markdown AIO wants to put a second table of contents where the list under "My Second Heading" is even though I have one at the beginning of my file. If I save the page, it wipes the list items and replaces them with a secondary TOC!. This is really bad because it wipes out crucial data.

I tried creating a new file and copy/pasted the previous files contents but the same thing happened. I even copied the text to notepad (to see if there was any weird formatting somehow behind the scenes) and pasted it back, but the same issue occurred.

I then found this issue and added <!-- omit in toc --> to "# My Second Heading" and that temporarily resolved the issue.

I'm not sure how you can replicate this bug however. I've done what I described above in over 100 files and this issue has never occurred until now.

Also I should note that I have the following in settings.json of VSCode:

"markdown.extension.toc.plaintext": true,

Lastly, thank you for this extension. It's made VSCode into the best Markdown editor (I've tried many other extensions and standalone Markdown editors like Obsidian but using VSCode outright is the best).

[yzhang-gh]

Thanks for the feedback. Could you provide a sample document for me to debug? Before we finally have the per-file toggle, we can always try to make the TOC recognition "smarter".

[jlahijani]

I made a video which you can view here with a very simplified example. As you watch the video, you'll see what's actually happening and what I discovered while recording the video: https://www.youtube.com/watch?v=nj-NvqaBSUg

[yzhang-gh]

Thanks a lot. For the case you showed in the video I will probably come up with a rule that "never treat a short list as a TOC", no worries. The real problem is the mis-detection of TOC can happen in a normal document, and I believe that is what happened to you, right? I guess it will be more helpful if I can solve that case.

[jlahijani]

Indeed. I appreciate your efforts.

As a side note, I feel getting a TOC to work correctly and reliably has been an issue with other VSCode modules and other text editors as well (Sublime).

Would you be able to provide some sort of opt-in alternative where-by it gets reliably inserted between some comment landmarks? For example:

<!-- toc -->
the extension automatically inserts the toc here no matter what
<!-- /toc -->

That would really provide me with true peace of mind. The loss of data that I experienced (although I was able to recover it and not a big deal if I didn't) is something that gives me unease with the current approach even if it fixed.

[yzhang-gh]

I see. I haven't found a widely-used way to tell the editor where to insert a TOC for many years, and I don't think there will be 😂. But I do agree that we can have a <!-- toc --> magic comment, given that we already support <!-- no toc -->. The only problem is that it is a new code path and I may not have enough time to implement and test it, comparing to just a few changes (e.g., adding a if-else) to the existing auto-detection logic.