Vscode-markdown: [Feature Request] [TOC] Toggle lower-case

[bobstead]

What is the Problem

Due to #312 getting merged, it seems that the TOC anchors are now broken in GitHub Enterprise, at least on version 2.15.6. If I change all the links to lowercase, the TOC links appropriately.

How to reproduce it

The following is how v2.4.0 generates the TOC:

# Section One

- [Section One](#Section-One)
  - [Sub Section One](#Sub-Section-One)
  - [Sub Section Two](#Sub-Section-Two)

## Sub Section One
## Sub Section Two

None of the anchors work in GitHub Enterprise v2.15.6 for both Chromium or Firefox (the two browsers I have). I have not tested this in GitHub, but I'm assuming it works based on why #312 was merged.

The following TOC does work and link correctly:

# Section One

- [Section One](#section-one)
  - [Sub Section One](#sub-section-one)
  - [Sub Section Two](#sub-section-two)

## Sub Section One
## Sub Section Two

I have no idea if the toc support for mixed case anchors was updated in the later versions of GHE, I think the latest version is 2.17 so we're not that far behind latest. Perhaps someone that uses a later version of GHE could test?

In the past there used to be a setting: markdown.extension.toc.toLowerCase that forced all the links to be lowercase, I think it may have been removed because it broke some languages but at least we could configure the link being as-is or force it to be lowercase.

Any chance to add this back into the configuration, otherwise I might as well not update the plugin past 1.5.6.

[parsiya]

+1. I have the same issue using the plugin to generate TOC for my blog pages in Hugo. The current ToC does not work because it's not lowercase.

[parsiya]

In case anyone is interested, version 2.3.1 seems to be the last one that works. You can get the VSIX to install here: https://ci.appveyor.com/project/yzhang-gh/vscode-markdown/builds/24541231/artifacts

Edit: See below for better instructions.

[yzhang-gh]

Thanks for the feedback. Things are a little complex here because there are many more differences between different places (VSCode, GitHub, and now GitHub Enterprise, Hugo).

For a workaround, you can install the previous build as @parsiya mentioned (thanks!). Remember to disable extension auto-update in the settings.json first.

I will consider adding a new option this weekend. (related #469)

[bobstead]

Thanks for all the feedback. I have indeed installed 2.3.1, didn't realize about the auto-update so I will add that 👍 Thank you for considering to add a new option, I know that the TOC feature has been a bit of a pain supporting everything.

[parsiya]

There's no need to disable auto-updates. Seems like VS Code disables auto-update if you install a specific version of the extension. Instead of downloading and installing the VSIX you can (see here https://github.com/microsoft/vscode/issues/30579#issuecomment-456028574):

1. Go to the extension tab.
2. Right-click on the extension and select Install Another Version....
3. Select version 2.3.1.
4. Done, the extension will not auto-update.

[lucasgcb]

I can confirm this has been breaking our Markdown to rST section links that Sphinx generates for some of our html documentation. It also doesn't work on my html enabled previewer.

Not entirely sure why this was added and the option stripped.

[yzhang-gh]

I added a new option toc.downcaseLink which defaults to true.
It should be available in the dev build now.

[jasonswearingen]

@yzhang-gh thank you for this, Typedoc generates elements with lowercase id's, so the mixed-case anchors don't work with it. (why I came here)

[yzhang-gh]

@jasonswearingen Thanks. Does the dev build work for you? (with downcaseLink set to false)

[jasonswearingen]

yes, the default with the new dev build works.

One additional slight issue is that if a header has a period, the TOC is generated without a gap character.

for example:

# Some.Header

will generate a toc link of:

- [Some.Header](#someheader)

but tools like TypeDoc generate an anchor like this:

<h1 id="some-header">Some.Header</h1>

Not super critical of an issue though, as I can workaround this by removing the period from headers.

EDIT: sorry I mis-read your question. I needed downcaseLink set to true which is what the new default is. When I explicitly set it to false I get the camelCase links which breaks when using TypeDoc.

[yzhang-gh]

Thanks.

if a header has a period, the TOC is generated without a gap character

Then it is another issue. And it varies in different places (VSCode, GitHub, GitLab etc.). There will be no good solution for a long time 😂.