In this tutorial, I will show you how to create a table of contents for your articles on Dev.to
A table of contents is a great way to structure your articles, posts, and blogs, especially if they’re long. It improves navigation for your readers, allows them to glance at the topics covered in the article, and saves time by letting them go straight to the desired section.
What we'll cover
Prerequisites
There is no prerequisite for this tutorial. However, you should be familiar with the Markdown markup language.
Write your article
The first step is writing your article and sharing your ideas and thoughts. Once you have your content ready, you can enhance its readability and accessibility by adding a table of contents.
Structure the content of your article
Divide and structure your articles into sections, subsections, and blocks. You can use Markdown headings to organize your content effectively.
You can use # for main sections, ## for subsections and ### for smaller divisions within subsections
This ensures the article is more readable and creates a clear and logical flow of information.
For instance,
# Introduction
## Part 1
## Part 2
### Subsection 2.1
### Subsection 2.2
Create the Table Of Contents
At the beginning of the article, create a list of links that match the headings (sections) in your article. For each heading, Markdown automatically creates an ID based on the text of the heading.
Markdown is a lightweight, text-based markup language used to create emails, documents, notes, presentations, websites, etc. The markup for creating links using Markdown is very straightforward.
Here’s how you can do it:
Understanding Markdown links
A Markdown link can be external or internal. It has two parts:
- The label in brackets
[] - The URL in parentheses
().
Only the label is visible on the page.
External Links
An external link points to a URL outside the article. It may lead to another website or page.
Example:
[Katshi.dev Portfolio](https://katshi.dev)
The markdown above will give the following link: Katshi.dev Portfolio
Internal Links
An internal link points to a section or paragraph within the article. The link should correspond to the matching heading of the section in the article.
Examples:
[Prerequisites](#prerequisites)
[Internal Links](#internal-links)
The markdown above will give:
Links to Headings
The most important remaining step is to add an HTML <a> tag to link with the relevant ID on top of each section heading.
For example, the following table of contents line [Internal Links](#internal-links) will be referred as:
<a id='internal-links'></a>
## Internal Links
### Internal links section content...
Preview and adjust
Use the preview feature of Dev.to to ensure that the table of contents links correctly to the sections. You can adjust the links if necessary.
Once the article is published, if you make any edits to section headings, don’t forget to update the links in the table of contents accordingly.
Following these simple steps, you can create a fully functional table of contents with active links for easier navigation.
What tool or strategy do you use to create article navigation links?
Feel free to share your experience in the comments.
Top comments (6)
Easy and simple.
A table of contents is important but I don't prefer it.
If the content is decent, I prefer reading from start to finish.
Interesting approach, indeed!
Thanks for sharing your experience @dark_coder_vibes
Needed this! Thank you!
Welcome @martinbaun
Glad it helps. Happy writing !
Nice article article,it's insightful and well explained !
Thanks @verlaine_devnet!
Feel free to share your tips when it comes to organizing your article's content.