01: **Table of content:** 02: - [Hello World]( ) 03: - [First Item]( ) 04: - [Second Item]( ) 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
04 you have a list of links that when clicked on should take you to the respective headings below thus
Adding the IDs to the TOC.
Most markdown renderers when converting your headings to HTML add IDs to them.
### 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:
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:
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 for you 😊 "How to reuse links in markdown (reference links)"