How do I write a table of contents in Markdown?

Creating a Table of Contents (ToC) in Markdown is primarily about generating clickable links to different sections within your document. Here's how to do it, along with key details and considerations:

1. Create Section Headers:

- Begin by creating your sections using Markdown header syntax. For instance: # Introduction, ## Subsection One, ### Sub-subsection A.

2. Generate Unique IDs:

- Many Markdown processors and viewers will automatically assign unique IDs (usually derived from the header text) to your headers. However, if you are dealing with custom or inconsistent output, consider manually adding custom HTML anchor IDs above the header tag for explicit referencing:

<div id="introduction"></div>
# Introduction


- Or with no surrounding element:
<a id="introduction"></a> # Introduction


- Here the <a> is acting as an "invisible anchor"

3. Build the Table of Contents:

- Create the table of contents at the beginning of your document using a simple list format with appropriate hyperlinks to the corresponding IDs of the headers, for instance:

- [Introduction](#introduction)
- [Section 1](#section-1)
- [Subsection 1.1](#subsection-1-1)

4. Handle Spaces and Special Characters:

- The auto-generated IDs for your headers are commonly sanitized by processors for special characters. Spaces often turn into hyphens (-), or you will get a CamelCase id. For example, ## My Header with Spaces can produce #my-header-with-spaces or #myHeaderWithSpaces.

5. Consider Dynamic ToCs:

- Some editors (like GitHub, GitLab or Obsidian) render Markdown using scripts, and thus might create Table of Contents automagically or give you a feature/extension to do so without extra work. This usually creates better result, since you do not have to worry about making ids.

6. Example With Nested Headers:

Here is a more robust example of markdown document with nested headers and with html <a id=""></a> anchors:

<a id="top"></a>
# Table of Contents Example
- [Introduction](#introduction)
- [Section 1](#section-1)
- [Subsection 1.1](#subsection-1-1)
- [Sub-subsection 1.1.1](#sub-subsection-1-1-1)
- [Section 2](#section-2)
- [Conclusion](#conclusion)
<a id="introduction"></a>
# Introduction
This is the introductory section of this document
<a id="section-1"></a>
# Section 1
This is the first main section.
<a id="subsection-1-1"></a>
## Subsection 1.1
Some contents in this sub section.
<a id="sub-subsection-1-1-1"></a>
### Sub-subsection 1.1.1
Here goes even more nested info
<a id="section-2"></a>
# Section 2
Second big section here.
<a id="conclusion"></a>
# Conclusion
And finally the concluding paragraph


By correctly generating your IDs (manually if needed) and ensuring that each item in the table of contents points to those unique IDs, your Markdown document can include a simple and clear way of navigation.

Please note, you might need a pluggin in your favorite markdown editor to generate automatical Table of contents.

Learn more about this