How To Create a Table of Contents to your Dev.to article

Table of Contents

• My Confession
• Step 1: Create your Table of Contents structure
• Step #2: Add Labels
• Step #3: Integrate Labels into Your Sections
• Step #4: Test it Out
• Now it's your turn

My Confession

After using Dev.to for a year, I finally noticed something…there’s no built-in table of contents feature. Imagine this, you’re immersed in a dense blog post and become so overwhelmed that your head starts to spin! This is where a table of contents saves the day. Not only is it your article’s roadmap, it also let’s go straight to the parts you want to read with clickable heading. Now, that you know the benefits, let’s start building!

Step 1: Create your Table of Contents structure

Dev.to articles are written using Markdown, a text-based language primarily used for software documentation. With this in mind, structuring your table of contents is a breeze.

First, put the words Table of Contents into an <h2> element. This step ensures that your headings fall into a hierarchical order, making it easy for people who rely on screen readers to navigate your blog post. Next, wrap brackets ([ ]) around the headings of your post's sections and showcase them as an unordered list using hyphens (-). Need a visual? Take a peek at how I did it for my article “Accessible Colors: How I Brought Rainbows to Everyone”.

## Table of Contents
- [Dispelling a belief]
- [The Problem]
- [Level #1: Change the Color]
- [Level #2: Putting a label on it] 
- [Lessons Learned]

Bam! Your table of contents is up and running! 😊 But hold on, before we break out the confetti, let's figure out how to weave this structure into the sections of your post.

Step 2: Add Labels

To make your table of contents work, you'll need to assign an ID to each heading. I highly recommend reading through your paragraphs and give each heading a name that reflects its topic. For instance, in “Accessible Colors: How I Brought Rainbows to Everyone”, I named the heading for “Level #1” with the ID #issue because, well, it's about presenting a problem. Once you've picked your IDs picked, put them right next to their corresponding headings in parentheses ( ).

Example:

## Table of Contents
- [Introduction](#intro)
- [Body paragraph 1](#point-one)
- [Body paragraph 2](#point-two)
- [Body paragraph 3](#point-three) 
- [Body paragraph 4](#point-four) 
- [Ending](#conclusion)

Now that your labels are in place, it's time to go to the next step! 😊

Step 3: Integrate Labels into Your Sections

Now you've got your table of contents laid out, but there's a problem. If you click on those headings, they don't send you to the right paragraphs.

Why is this happening? Well, the headings aren't woven into your paragraphs just yet. Fear not my fellow writer, you can fix this by nesting your headings' ID names within open and closing anchor elements, like this:

<a id="heading's id name"></a>

Once that's done, insert your paragraph's heading and content. Here's how it looks in full:

<a id="heading's id name"></a>
## Heading of your paragraph
paragraph's content

Voila! With this tweak, you're just one step away from hitting that publish button.

Step 4: Test it Out

Before hitting that publish button, you want to make sure everything works.

Click on the "Preview" button and go through each heading in your article's table of contents. If they don't lead to specific parts of your article, here are some reasons why:

• Missing IDs: Double-check your table of contents. If you're not getting those clickable headings, chances are you've skipped assigning IDs. Remember, those IDs are the secret sauce that makes your headings dance. Need a refresher? Read step 2.
• Broken Structure: If your headings aren't playing nice with your paragraphs, you might have missed integrating those IDs. Reread step 3 for a gentle reminder.

Once you've revised your table of contents, click on that shiny "Publish" button, and watch your article go live! 🚀

Now it’s Your Turn

Congratulations, you now have a table of contents! 😊 By incorporating this feature in your posts, you just saved your readers from information overload. Oh speaking of articles, if you've enjoyed this tutorial, why not hop on over to Dev.to and give me a follow?

Christine Belzie Follow

Technical Writer| Open Source Maintainer | Coding Hobbyist

There's plenty more content where this came from!😊 Oh, and while you're at it, click on the links below to connect with me outside of Dev.to.

🚀 Follow me on X(Twitter)

🚀 Check out my other content on Hashnode

🚀 Connect with me on Linkedin

Happy writing, my friend! 😊