Awkward syntax to omit section

[mrbrainstem]

Proposal

The syntax for omitting a section from the table of contents is "omit in toc". That works, but it isn't a typical use of English grammar. More typical would be to say "omit from toc". It would be nice to support both versions as the non-standard version is harder to remember (for native English speakers).

References

• OALD

• Merriam-Webster

[yzhang-gh]

Thanks for pointing it out! I will add support to both of them.

[Lemmingh]

I believe this issue reveals a design fault.

We could avoid the natural language stuff, if all magic comments were key-value pairs.

---

Here is a widespread YAML-like paradigm:

• Change <title>:

  <!-- document_title: Shoot yourself in the foot -->
  

• Exclude a Markdown list from heading recognition:

  <!-- toc_field: false -->
  

• Exclude a Markdown heading from TOC:

  <!-- outline_heading: false -->
  

[yzhang-gh]

Thanks.

There is always a trade-off between succinctness and expressiveness. The current design is more of a preference made in the very beginning. Back in 2016, there was another Markdown TOC extension (maybe not the exact one) which uses such a syntax

<!-- vscode-markdown-toc -->
* 1. [Summary](#Summary)
* 2. [Features](#Features)
* 3. [Usage](#Usage)
<!-- vscode-markdown-toc-config
	numbering=true
	autoSave=true
	/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->

##  1. Summary 
##  2. Features 
##  3. Usage

It looks tedious (although it provides more controllability) and I don't think it gets the spirit of Markdown. (It should read like natural language but not another HTML.) That's why I decided to make an extension that detects the TOC automatically.

I do see there are several requests for more controllability but luckily they do not seem urgent up to now. I would like to be kind of conservative in this part. Once we support this kind of syntax, it ends up with more and more requests for customization.