Table of content making

For the purposes of this article, we’re going to use freeCodeCamp.org's content manager for visual and demonstration purposes. freeCodeCamp/news uses the blogging platform Ghost at the time of writing this, but this method can really apply to any article you write.

Why is this helpful?

Providing a table of contents helps improve the experience that the people reading your article will have.

It gives readers a preview of the article

Jumping into an article, at least a lengthy one, can be a big time commitment. No one wants to spend 20 minutes of their morning only to figure out a post they dove into hasn’t actually answered their questions. Or that it's a rehash of something they’re already an expert on (although differing perspectives can still be helpful).

By providing this preview, you can help people get a sense of what to expect as they start to read. It allows them to prioritize their time with the other list of articles they have to read.

It provides anchor points to jump down to specific content

Similar to providing a preview, maybe someone wants to read a specific portion of the page. Maybe it’s because they can skip the first few bits of a tutorial or they are coming in from a link a coworker shared in Slack.

The point is, people can use the table of contents to jump down to the parts that are more important to them.

Bonus: it helps you as an author

Providing a table of contents might not help for many practical reasons, but it's an additional tool for you to prioritize and understand the content of your post. It serves as a high level outline that you can refer to when making sure the flow of your story actually makes sense.

What it doesn’t do

Unfortunately, this is a manual process. This table of contents isn’t going to magically update any time you tweak your content. So make sure to be vigilant during the editing process and update any broken links or add and remove any changes before you publish.

How can we add a table of contents?

Content headers and anchor links

The key to this solution is to utilize the built in id attributes applied to content headers in the HTML when building a post page. Using these attributes allows us to create an anchor link that will jump the browser’s scroll position down to the location of the element with that id.