Markdown TOC with Special Characters?

Question

I am trying to create a TOC for my Markdown blog.

The methods I am finding here... : Markdown to create pages and table of contents?

....do not work for me because I am naming all of my headers # _</>_ The Setup because I am using CSS on to style the "", giving each header a nice colored Icon next to it. If I simply use ```# The Setup ```` it works great.

This causes issues whenever I try to use [The Setup](#The-Setup).

I tried a few things like [The Setup](#_</>_-The-Setup) and other things, but I can not get it to work.

If someone can point me in the right direction I would greatly appreciate it. Also, if anyone has a better way of adding custom icons next to headers, I think that would be the better way to go about it.

As always, thanks in advance.

Which Markdown implementation are you using? Autogenerated IDs being assigned to headers is a non-standard feature and each implementation which supports it uses a slightly different method for generating the IDs. — Waylan, Dec 30 '19 at 00:11
I am using visual studio code and writing .md files for a blog — ETHan, Dec 30 '19 at 04:07
That doesn't tell us which Markdown implementation. PHP Markdown, Python-Markdown, markdown.pl, marked.js, common mark, or something else? — Waylan, Dec 30 '19 at 15:52
I am using Gridsome.org and placing .md files. I am then using the Vue-remark plugin to display the markdown content in my Vue app. I am new to markdown, so I apologize for my lack of knowledge here. — ETHan, Dec 30 '19 at 16:21
I also wanted to add that in VS Code I am using a markdown TOC generator extension and it doesn’t really work ( because I have “_>_” in each of my headers ). — ETHan, Dec 30 '19 at 16:26

score 0 · Answer 1 · answered Oct 12 '22 at 18:29

The general solution is to examine the rendered HTML output to see what the tool is converting the special characters to, in the HTML's element ID. Every tool could handle the conversion differently (it could convert special characters to -, _, or just remove special characters). Some examples:

<h1 id="_____the-setup">The Setup</h1>
<h1 id="-the-setup">The Setup</h1>
<h1 id="the-setup">The Setup</h1>

Once you have identified the exact id that the tool is using, then you use that value as the heading link in the markdown's table of contents. For example:

[The Setup](#_____the-setup)

Now, the tricky part is that not all Markdown tools will export the rendered HTML, including VS Code. The workaround for VS Code is:

Open the markdown preview mode (which renders to html internally).
Open the VS Code Developer Tools (Help > Toggle Developer Tools).
Use DevTools to inspect the element (in this case, the heading element for "The Setup").

I see that VS Code named the id as the-setup, so in the markdown's table of contents, I write [The Setup](#the-setup). Now the table of content hyperlink works in VS Code. Caveat: it might not work in other Markdown tools if they render a different HTML element ID!

Another shortcut now available in VS Code (1.70 July 2022), is that markdown can autocomplete the header ID. So you just type #, and it will list the valid IDs:

Markdown TOC with Special Characters?

1 Answers1