Vscode-markdown: Add an option to disable TOC features

[yzhang-gh]

Related #304.

[DaveEveritt]

Auto-generation occurs in the case of a simple list with links, which generates an (unwanted) entire TOC, when the following needs to remain as below:

- [Information Architecture](#information-architecture)
- [Responsiveness](#responsiveness)
- [Design and Interaction](#design-and-interaction)
- [Accessibility](#accessibility)
- [Critical Analysis](#critical-analysis)

on save, this pulls in every markdown heading, which is fine for a full TOC but _not_ what's required for the above:

- [Coursework 1 - Specification](#coursework-1---specification)
  - [Submitting your coursework](#submitting-your-coursework)
- [Overview](#overview)
- [Where to Start?](#where-to-start)
- [Deliverables](#deliverables)
- [Marking Criteria](#marking-criteria)
  - [Information Architecture](#information-architecture)
  - [Responsiveness](#responsiveness)
  - [Design and Interaction](#design-and-interaction)
  - [Accessibility](#accessibility)
  - [Critical Analysis](#critical-analysis)
- [Example website ideas](#example-website-ideas)

For now, I've disabled the generate TOC on save toggle.

[fbl07]

I also have this same issue would appreciate a way to suppress the TOC detection in a certain spot. My document has a full TOC that I would like to stay updated with the full document. I also have a list of header links inside one of the sections that sort of serves as a preview of the steps to come at the same time. I would like that list of link to only contain the headers from that section (which I can quite easily handle manually). Instead, Markdown All in One automatically detects this as an attempt at creating a TOC and automatically fills in the full TOC every time I save, which I don't want. If there was the option to disable the TOC detection for a specific spot in the document, that would quite useful.

[yzhang-gh]

Thanks for the information.

This extension calculates the similarity of the real TOC and a potential TOC list. The threshold is set to 0.5 currently.

https://github.com/yzhang-gh/vscode-markdown/blob/a1fbdcca26d0ed7b8abdb2b12fb7f83954495945/src/toc.ts#L135-L138

A solution might be providing an option allowing users to change this. Larger threshold means stricter TOC identification.

[fbl07]

While that could potentially fix the issue, I fear it could get a bit finicky. Having a comment function similar to the ` that would tell the TOC detection code "what follows is not a TOC, ignore it" I feel would be simpler to use

[yzhang-gh]

I agree

[yzhang-gh]

Added in the dev build.

Now it is <!-- no toc -->. Any suggestion on the wording?

[DaveEveritt]

How about using a positive instead? Just <!-- TOC --> to trigger the generation only when required? Otherwise "not required" means we have to prefix all our linked lists with a "no TOC"…

Cleaner, simpler and less parsing.

[yzhang-gh]

Smart TOC detection is a feature (and the original motivation) of this extension. With the current implementation, _most users won't ever_ need an extra <!-- TOC --> comment which I think is distracting.

If you see too many false positive TOC identifications, feel free to provide more information and let's see how we can improve it.

[DaveEveritt]

If you see too many false positive TOC identifications, feel free to provide more information and let's see how we can improve it.

For now, then <!-- no toc --> addresses the issue—will this be in an update?

I still like the idea of users being able to set preferences, rather than have the TOC automatically happen. But the extension has so many other good Markdown features that (for me) the TOC wasn't the main reason for using it.