Vscode-markdown: Exclude heading from toc globally.

[tperry-r7]

What is the problem?

I want to exclude the heading "# On this page" from my workspace toc globally. I reviewed the instructions and it seems it might be possible. I'm not able to figure out the right syntax.

How can I reproduce it?

"markdown.extension.toc.omittedFromToc": {
    "/Users/{users}/Documents/{documentation-folder}":[
        "# On this page"
    ]
},

Is there any error message in the console?

---

Proposals

• [ ] Add wildcard support to the omittedFromToc configuration. (1 vote)
• [ ] Add an option to exclude headings before the position of the TOC. (2 votes)

[yzhang-gh]

You need to specify the file name but not the folder.

If your documents have a similar structure, consider to set toc.levels at workspace level.

[tperry-r7]

Hmm, not quite what I am looking for.

I'm using this as part of managing a large amount of documentation.

A typical file will look like below, with each file having a different name. I don't want to have to set the ignore per file. Is there a way to set it at the workspace level so I don't need to add every single file name?

# Title

## On this page

* [Toc](link) 
* [Toc](link) 
* [Toc](link) 

## Heading
some text

## Heading
some text

### Heading 
some text

[yzhang-gh]

Currently, we don't provide such a configuration. As a workaround, you can use ### On this page and set toc.levels to 2..6. (The TOC will start with the first level-2 heading.)

[Thell]

Since I am experiencing a similar desire to omit particular headings perhaps either the heading existing _prior to_ the TOC could be omitted (by a flag) or a distinction could be made between setext and ATX heading styles where one type could be omitted.

The argument for the first option would be a simple question of how many times have you experienced a published work where the TOC _includes_ the cover/title, preamble, summary, etc? Those typically reside before the TOC and aren't included.

The argument for the second option would be the intent of the usage.

Looking at the following outline which items would most likely be found in a ToC?

===
Purpose text.

## Introduction
Summary text/info blurb.

Contents
----------
[ToC]

# Header

## Header

### Header

# Header

## Header

### Header

I haven't looked at the source yet, as I just got started with your extension less than an hour ago and ran into this problem and this was the _first_ issue in the tracker but I wanted to give my feedback on the first feature of your extension that I attempted to make use of.

Perhaps it would be an easy alteration to the code?

edit: Upon re-reading the original post I'm thinking that perhaps this isn't the right spot for these comments?

[Thell]

Looks like you are already special handling setext headings making for a possible opportunity to alter the if block:

https://github.com/yzhang-gh/vscode-markdown/blob/bbada83b39a6ef862e59da0696847d953757ee23/src/toc.ts#L351

to include something along the lines of && !Omit.setextStyle ?

[yzhang-gh]

to omit particular headings perhaps either the heading existing _prior to_ the TOC could be omitted (by a flag) or a distinction could be made between setext and ATX heading styles where one type could be omitted.

Personally, I don't think a distinction between setext and ATX headings is a good solution (in terms of how many users will use this special rule). To omit headings before [TOC] makes more sense to me.

Upon re-reading the original post I'm thinking that perhaps this isn't the right spot for these comments?

This issue is about the toc.omittedFromToc (global) option while you are talking about omitting headings in general. They are different things but are both solutions to a general question.

---

BTW, I understand people may have different ideas about how to organize their Markdown file structures, e.g. blog posts. Just curious why you starts with level-1 heading when coming to the "Contents". You are putting them at the same level as "Title" (in other words, they have visually the same font size/weight etc.).

(See the README source file of this repository for a different section structure.)

[Thell]

To omit headings before [TOC] makes more sense to me.

Indeed and I agree; although I can see a case for being able to treat the two (settext and ATX) distinctly particularly since they are distinct visual indications when viewing a markdown document in its native format as a text document..
Just having the ability to omit Pre TOC headers would be a 👍

Regarding the example: it was meant more for illustration as to what one would anticipate seeing in a ToC given that textual description. One thing I try to avoid in markdown documents is markup.
To me <!-- foo --> or raw HTML(5) tags really hinder reading the document itself without a browser even though it makes sense for a README that is intended to be rendered on github and not in a console.

[yzhang-gh]

I see your point. Let's just collect more feedback and then see how we can improve it.

[hpractv]

I think the easiest change to understand would be to make the path wildcard enabled:

"markdown.extension.toc.omittedFromToc": {
    "*/*.md": [
        "# index"
    ]
},

Also, as an aside, it would be nice if the string being ignored could be done in a case insensitive way. Otherwise, you'd have to add "# Index" and "# INDEX" and hope that "iNdex" isn't used.

[xAlien95]

To omit headings before [TOC] makes more sense to me.

@yzhang-gh, this is exactly what I'm looking for. Is it currently available as feature?

[yzhang-gh]

@hpractv @xAlien95 Thanks for the feedback. I've updated the issue description.

IMHO, they are both valid feature requests/enhancements. Let's see whether there is someone willing to help.