Overview
If you look at open source projects on Github, you’ll see that they are mostly written in Markdown, but they still have a TOC. In today’s post, I’ll show you what a TOC is and how you can easily write a TOC in Markdown.
What is a TOC?
A Markdown Table of Contents (TOC) is a table of contents provided within a Markdown document. It is organized based on headings and subheadings within the document, and helps readers easily navigate to specific parts of the document. TOCs are especially useful in long documents to quickly grasp the structure and immediately access the desired section.
Markdown Acnhor
The Markdown syntax supports anchors. If you write it like below, it will scroll to the location you are referring to when you click the link.
1## Table of Contents
2- [Section 1: Introduction](#section-1-introduction)
3- [Section 2: Main Content](#section-2-main-content)
4 - [Subsection 2.1: Topic A](#subsection-21-topic-a)
5 - [Subsection 2.2: Topic B](#subsection-22-topic-b)
6- [Section 3: Conclusion](#section-3-conclusion)
7
8## Section 1: Introduction
9Content for Section 1...
10
11## Section 2: Main Content
12### Subsection 2.1: Topic A
13Content for Subsection 2.1...
14
15### Subsection 2.2: Topic B
16Content for Subsection 2.2...
17
18## Section 3: Conclusion
19Content for Section 3...
However, there are problems with the above method.
- it takes too much time to write a lot of content.
- when defining the anchor, we specify the name of the header, and if there are special characters or spaces in the header, we need to encode it into a string that the anchor can understand.
Subsection 2.2: Topic B → #subsection-22-topic-b
Everyone has their own favorite way to create a TOC, but today we’ll show you how to generate one automatically using the CLI command.
Generate TOC automatically
I used to be a big fan of websites that let you paste in Markdown and return Markdown with a TOC, but lately I’ve been writing a lot of articles here and there, so I started looking for other ways to do it.
There are a lot of services like this, so there are a lot of different ways to do it, but I’d like to introduce an open source project that has a lot of options and is easy to use.
https://github.com/jonschlinkert/markdown-toc
How to install
To install markdown-toc, you need to have node installed beforehand.
- Installing node (Windows)
- Visit the Node.js website: Node.js official website .
- Download the Windows installer: Select “Windows Installer” from the homepage to download it. We usually recommend the Long Term Support (LTS) version.
- Run the installer: Run the downloaded ``.msi`** file and follow the instructions in the installation wizard. npm will be installed automatically along with Node.js.
- Installing node (MacOS)
1brew install node
2```bash brew install node
3
4- Ubuntu/Debian Systems
5
6```bash
7curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
8sudo apt-get install -y nodejs
- CentOS, Fedora, Red Hat Systems
—]
Once the node installation is complete, execute the command below.
1npm install -g markdown-toc
How to use
Let’s write the TOC from the Anchor example above using markdown-toc with the TOC deleted.
1## Table of Contents
2
3## Section 1: Introduction
4Content for Section 1...
5
6## Section 2: Main Content
7### Subsection 2.1: Topic A
8Content for Subsection 2.1...
9
10### Subsection 2.2: Topic B
11Content for Subsection 2.2...
12
13## Section 3: Conclusion
14Content for Section 3...
In the above state, under ## Table of Contents, write <!-- toc -->. This will automatically create the TOC on that line.
1## Table of Contents
2
3<!-- toc -->
4
5## Section 1: Introduction
6Content for Section 1...
7
8## Section 2: Main Content
9### Subsection 2.1: Topic A
10Content for Subsection 2.1...
11
12### Subsection 2.2: Topic B
13Content for Subsection 2.2...
14
15## Section 3: Conclusion
16Content for Section 3...
Do a markdown-toc (assuming the file is named README.md )
1markdown-toc -i README.md
Result
1## Table of Contents
2
3<!-- toc -->
4
5- [Section 1: Introduction](#section-1-introduction)
6- [Section 2: Main Content](#section-2-main-content)
7 * [Subsection 2.1: Topic A](#subsection-21-topic-a)
8 * [Subsection 2.2: Topic B](#subsection-22-topic-b)
9- [Section 3: Conclusion](#section-3-conclusion)
10
11<!-- tocstop -->
12
13## Section 1: Introduction
14Content for Section 1...
15
16## Section 2: Main Content
17### Subsection 2.1: Topic A
18Content for Subsection 2.1...
19
20### Subsection 2.2: Topic B
21Content for Subsection 2.2...
22
23## Section 3: Conclusion
24Content for Section 3...
If you check the result, you can see that the TOCs for the headers you wrote under <!-- toc --> are automatically created. If you press it in the editor, you can see that it works properly.
Summary
The CLI gave me a lot of freedom and made it easy to create a TOC. This is the simplest case, but there are many other options, so I hope you can use them as well.