How to make a Table of Contents in Substack

A short guide to sections, anchor links, and improving navigation

Screencap: from my recent Variations article.

If you are a Substack author, especially one who writes long detailed articles or newsletters that tackle multiple subjects, you might occasionally find yourself wishing your post was easier to navigate and thus more enjoyable to read.

Particularly helpful in this regard might be a table of contents (TOC) at the beginning, with links that send you to a specific part or section of the post.

For a while now, I’ve been interested in publishing posts with TOCs in them but I didn’t believe that this was possible on Substack, as none of the formatting and blogging guides I’ve found suggested otherwise.

Recently, however, I’ve discovered that this is indeed possible while fiddling around with headings. As nobody else seemed to be talking about it, I’ve decided to write this little guide to help more Substack authors add TOCs to their posts.

---

---

Adding a TOC

Basically, adding a TOC is a simple process consisting of five main steps.

Step One:

Begin writing an article in the Substack interface and use the “headings” feature in the “Style” drop-down menu to break it up into multiple sections.

Essentially, you select a text part, then press H1, H2, H3, or H4 to turn it into a heading. Note that while there are six different kinds of headings you can use, only the first four will work for our purposes here. Each time you turn a block of text into a section heading, you create what is known as an “anchor link.”

Now, go ahead and publish the article.

---

Step Two:

Now that the article is published, each heading and thus each section has its own unique weblink that you can copy and paste. To do this, hover the cursor next to your heading until the “link” icon appears and then click on it.

This will copy the link to your clipboard.

So, copy all your section anchor links to an external list (eg. in a word doc).

Screencap: From an article of mine that has headings and a TOC.

---

Step Three:

Now, select the option to re-edit the article, go to the beginning (or elsewhere if you wish) and make your TOC, listing all your section/heading titles. 

---

Step Four:

Now, highlight the name of each section in your TOC, press the link button in the toolbar and then attach the corresponding anchor link from the external list to it. 

---

Step Five

Now, press the ‘Update’ button in the post editor.

And voila! You’ve now added a Table of Contents to your article! 

---

Update 1

As has been confirmed by

Arjan Tupan

(see comments), it is possible to actually create a TOC without having to publish the post first and then revise it. In other words, you can just attach the anchor links to your TOC in the post editor interface first and then publish the article. So, if you wish, you can basically skip steps two and three. In this case, your section links should arrive in the emailed version of the post as well.

However, I have sometimes had issues with skipping the steps as the anchor link icon pops up at the beginning of the article in the post editor rather than right next to the heading. In such cases, I find it easier to publish first then revise.

Update 2

Taro of

Softer Human Future

has found an alternative TOC method (see comments). After creating your TOC, instead of using anchor links, for each section, you should add #§heading-in-kebap-case to the post URL and attach the resulting link.

I have tested this method and it works. The benefit is that this way when you click on a section name in the TOC, the page will not be reloaded, resulting in less friction when you navigate.

Update 3: October 28, 2024

I’ve discovered that Substack appears to be adding automatic TOC Navigation Bars, which show up on the left side of the screen to posts that utilize headings. In other words, if you use headings, a TOC should appear by default. I don’t know if this feature is currently rolled out to everyone, but it appears in my interface. Once fully implemented, it would obviate the need for using the method I’d outlined above.

---

Additional Notes

• Ironically, it was only after discovering how headings could allow me to make a TOC that I found out Substack had a help article on the topic of anchor links. I have found, however, contrary to the claim of the help article, anchor links already appear in the post editor interface, so the article may be somewhat out-of-date. For more information on anchor links and their potential benefits, I suggest reading this other article from visualcomposer.com.  

• Of course, you can also use anchor links to your advantage in other ways. For instance, if you have a Twitter or Facebook account, you can paste the link of a specific section in your posts on either platform to allow your followers to immediately jump to that section. 

• Admittedly, anchor links in Substack are not perfect. When you click them, the text jumps a little below the actual section heading in the post, requiring you to scroll up. So, I hope Substack improves this feature in the future. UPDATE 12/28/22: So, it looks like Substack did indeed update anchor links to make the text stop jumping to below the section heading.

• ‘Anchor Links’ seem to be a relatively recent Substack feature. I’m not sure when exactly it became possible to add them, but the aforementioned help article was posted on June 22, 2022. If anchor links were unavailable on Substack until that time, it means it was not possible to make a table of contents until about six months ago. I believe their addition has not been widely reported or discussed, even by Substack itself.

---