Skip to main content

​
Overview

Creating a table of contents in ButterCMS involves three main steps:
  1. Create a list of sections at the top of your post
  2. Add anchor IDs to headings using the Source Code view
  3. Link your list items to those anchor IDs
This creates clickable links that jump readers directly to each section of your post.

​
Step-by-step guide

​
Step 1: Create your table of contents list

First, create a list of all the sections of your blog post that you would like to include as your table of contents. Create table of contents list
Place your table of contents near the top of your post, typically right after the introduction paragraph.

​
Step 2: Open source code view

Open the Source Code view for your blog post to access the HTML. Open Source Code view Click the Source Code button (< >) in the WYSIWYG toolbar to switch to the HTML view.

​
Step 3: Add IDs to your headings

Look for the headlines of your post that correspond to each section of your table of contents. You can do this with a simple Ctrl+F (Find), and then add an id attribute to each heading. Add id to headings For example, change: 
<h2>Getting Started</h2>
To: 
<h2 id="getting-started">Getting Started</h2>
ID naming tips:
  • Use lowercase letters
  • Replace spaces with hyphens
  • Keep IDs short but descriptive
  • Each ID must be unique within the page
Now link the items on your table of contents to the IDs you just created by adding anchor links. Link to anchors Change your list items from: 
<li>Getting Started</li>
To: 
<li><a href="#getting-started">Getting Started</a></li>
The # symbol followed by the ID creates an anchor link that jumps to that section.

​
Step 5: Verify and save

Go back to the Source Code view to check and make sure everything is linked correctly. Then save your post or publish it.

​
Complete example

Here’s a complete example of a blog post with a table of contents: 
<p>Welcome to our comprehensive guide. Use the table of contents below to jump to any section.</p>

<h3>Table of Contents</h3>
<ul>
  <li><a href="#introduction">Introduction</a></li>
  <li><a href="#getting-started">Getting Started</a></li>
  <li><a href="#advanced-tips">Advanced Tips</a></li>
  <li><a href="#conclusion">Conclusion</a></li>
</ul>

<h2 id="introduction">Introduction</h2>
<p>Your introduction content here...</p>

<h2 id="getting-started">Getting Started</h2>
<p>Your getting started content here...</p>

<h2 id="advanced-tips">Advanced Tips</h2>
<p>Your advanced tips content here...</p>

<h2 id="conclusion">Conclusion</h2>
<p>Your conclusion content here...</p>

​
Best practices

​
When to use a table of contents

Good for TOC

  • Long-form articles (1500+ words)
  • Tutorials with multiple steps
  • How-to guides
  • Documentation
  • Comparison posts

May not need TOC

  • Short blog posts
  • News updates
  • Announcements
  • Single-topic posts

​
Naming your anchors

Good PracticeExample
Use descriptive names#how-to-install
Keep it short#installation not #installation-instructions-for-users
Use hyphens for spaces#getting-started not #getting_started
Be consistentAll lowercase, same format

​
Structuring your content

For the best table of contents experience:
  1. Use clear headings - Readers should understand the section from the heading alone
  2. Keep consistent depth - Don’t mix H2 and H4 without H3 in between
  3. Limit to major sections - 5-10 items is usually ideal
  4. Update when editing - If you change a heading, update the TOC link too

​
Troubleshooting

  • The visual styling depends on your website’s CSS
  • Contact your developer to add styling for TOC lists
  • Consider using a specific class for TOC lists
  • Look for the < > button in the WYSIWYG toolbar
  • It may be in a dropdown menu depending on your configuration
If you prefer not to use the Source Code view, you can create anchor links using the Link tool:
  1. Add IDs via Source Code (one-time setup for each heading)
  2. Select your TOC text in the normal editor view
  3. Click the Link button in the toolbar
  4. Enter the anchor link as #your-heading-id
  5. Save the link
This method still requires accessing Source Code to add the id attributes to headings, but the linking step can be done in the visual editor.