Markdown Table Of Contents (TOC): How To Create One

🚫 Wrap Code📋 Copy
01: **Table of content:**
02: - [Hello World](#item-one)
03: - [First Item](#item-two)
04: - [Second Item](#item-three)
05: 
06: <!-- headings -->
07: <a id="item-one"></a>
08: ### Hello World
09: Hello world content goes here
10: 
11: <a id="item-two"></a>
12: ### First Item
13: First item content goes here
14: 
15: <a id="item-three"></a>
16: ### Second Item
17: Second item content goes here
18: 

As your markdown document grows in length it becomes impossible to find a particular section without scrolling through different parts. This can ruin the reader's experience.

You can improve your user's navigation experience by providing a Table Of Content(TOC).

let's see how you go about creating one

From the example, I have provided above the line 01 to 04 you have a list of links that when clicked on should take you to the respective headings below thus 07, 11 and 15.

Interesting facts: Did you know most backends will fail this validation test [↗]?

Adding the IDs to the TOC.

Most markdown renderers when converting your headings to HTML add IDs to them.

For example, ### Heading here will be converted to < h3 id="heading-here">Heading here</h 3>. Notice the id attribute id="heading-here" in the opening tag this is what you will typically use in your TOC link ie: [Heading here](#heading-here).

However IDs are supposed to be unique, so if you happen to have two headings with the same text, they will both have the same ID and the TOC will point to the first one only.

To avoid this you should add your own ID and one of the best ways to do so is to add an a tag on top of the heading.

This way you ensure no two headings have the same ID.

This will look something like this:

🚫 Wrap Code📋 Copy
01: <a id="item-two"></a>
02: ### Second Item

This is also useful since some markdown renderers may generate random IDs instead of using the heading text. This means the only way to know the ID is to use your browser's inspect tool.

As you can imagine this is not ideal and might lead to a broken TOC if you get the ID wrong or a new one is auto-generated when your content changes.

Here is another article you might like 😊 "Diary Of Insights: A Documentation Of My Discoveries"