Vscode-markdown: GitLab TOC support

[quicktrick]

Hello! Your extension is very convenient, but there are a few issues with the TOC, generated with markdown.extension.toc.githubCompatibility=true when using with GitLab (v. 11.11.3-ee, the latest one)

The first issue is the same I described here for doctoc. The others are specific for this extension (doctoc processes them correctly).

Here is my test.md with the generated TOC:

- [MikroTik hAP ac²](#mikrotik-hap-ac²)
  - [Switch + Access Point](#switch--access-point)
  - [Настраиваем Доступ к Сети](#Настраиваем-Доступ-к-Сети)

## MikroTik hAP ac²

The [hAP ac²](https://mikrotik.com/product/hap_ac2) is a Dual-concurrent Access Point, that provides Wifi coverage for 2.4 GHz and 5 GHz frequencies at the same time. Five 10/100/1000 Ethernet ports provide Gigabit connections for your wired devices, USB can be used for external storage or 4G/LTE modem, and device supports IPsec hardware acceleration.

### Switch + Access Point

### Настраиваем Доступ к Сети

1. The 1st entry contains a specific symbol ². I described a similar issue here. The real GitLab link for that header is

https://mydomain.tld/myrepo/test.md#mikrotik-hap-ac

1. The 2nd entry. Your extension incorrectly processes the + sign. The real GitLab link for that header is

https://mydomain.tld/myrepo/test.md#switch-access-point

1. The 3rd entry. This is a Cyrillic text. Your extension does not convert upper case characters to lower case. The correct TOC entry for that header (the working one) should be

  - [Настраиваем Доступ к Сети](#настраиваем-доступ-к-сети)

And the real GitLab link for that header is

https://mydomain.tld/myrepo/test.md#%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%B0%D0%B8%D0%B2%D0%B0%D0%B5%D0%BC-%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF-%D0%BA-%D1%81%D0%B5%D1%82%D0%B8

---

In fact, doctoc works more correctly, but your extension is much more convenient, and I love it a lot. I'd like you have corrected those issues. Thanks in advance!

[yzhang-gh]

Thanks for the feedback.

Actually, I have to say there is no "correct" way to generate the TOC links as they are different everywhere (inside VSCode, on GitHub, on GitLab, etc.).

As you can see from the setting name githubCompatibility, it is designed for GitHub. I just tested your example and Problem 1 indeed, but no Problem 2 and 3 _for GitHub_.

For Problem 2, it may be an incompatibility between GitHub and GitLab.

For Problem 3, it is tricky. GitHub and VSCode are _case-insensitive_ while by default (normal HTML) the case matters. So keeping the exact case is a better choice (working almost everywhere) (#312).

However, when it comes to Russian (I guess), an uppercase letter and its lowercase letter are different letters, but not one letter with different cases. _It is not "downcase" in fact, it is "change to another letter"_.
(If it works on GitLab, it won't work on GitHub) https://github.com/yzhang-gh/vscode-markdown/issues/90#issuecomment-371465429

---

BTW, there is no Problem 1 in VSCode preview. 🤦‍♂️

[quicktrick]

Thanks for your reply, @yzhang-gh !

BTW, there is no Problem 1 in VSCode preview.

That's right, there is no problem in VSCode preview, I only wrote about GitLab issues.

Then is it possible to make a separate option for GitLab support (as they did in doctoc)? Taking in account that GitLab is "Used by more than 100,000 organizations around the globe" (link), that option is in real demand.

[yzhang-gh]

I see the popularity of GitLab.

We need to find out how GitLab generates those links (i.e. slugify function). For VSCode, we know it as it is open-sourced. And there is also a ruby function for GitHub.

https://github.com/yzhang-gh/vscode-markdown/blob/d394c9d8af5e5121b38d01c3c2de274b2a57ed80/src/util.ts#L88-L89

https://github.com/yzhang-gh/vscode-markdown/blob/d394c9d8af5e5121b38d01c3c2de274b2a57ed80/src/util.ts#L97-L98

Do you have any idea where we can find that of GitLab?

[quicktrick]

I'm not quite sure, but take a look at this and this

And there is an explanation in the docs too.

[BeeeWall]

From a quick search of Gitlab's source repo, it's either this or this. Based on the explanation in the docs linked above, probably the former.

Edit: It looks like READMEs don't actually use either of those. Instead, they use this.

[yzhang-gh]

Thanks for the information! It looks quite simple so I would like to look for help if anyone is interested.

Just change the slugify function here

https://github.com/yzhang-gh/vscode-markdown/blob/deccf51140eef590c696628672b898e9dcfa30c7/src/util.ts#L161

(Probably we need to redesign the githubCompatibility option)

And add some tests for the GitLab slugify function

https://github.com/yzhang-gh/vscode-markdown/blob/deccf51140eef590c696628672b898e9dcfa30c7/src/test/suite/slugify.test.ts#L5

[BeeeWall]

I'd be willing to take a crack at it.

I suppose githubCompatibility could be changed to something like slugifyMode, with the options github, gitlab, vscode? (I haven't really worked with VS Code extensions before, so I don't know whether limiting it to specific values is possible or not, but if not, defaulting to "vscode" could work)

[yzhang-gh]

Many thanks.

It can be enum values. We already have some options of this kind.

[BeeeWall]

I'll take a look at doing that, then.

[Lemmingh]

Thank BeeeWall for the great contribution.

---

GitLab has changed their logic recently, so our next release will be shipped with a rewritten implementation.

This issue will be closed soon.