How to Add a Table of Contents to Long Pages and Articles

This check flags long pages, such as articles, guides and documentation, that have no table of contents linking to sections further down the page. By the end of this guide you will have found every page over about 1,500 words, given its headings stable anchor IDs, and added a crawlable jump-link table of contents near the top.

⏱ 30–60 minutes for a template fix, plus 5 minutes per manually edited page🎯 Intermediate● Low impactOn-Page
ON-PAGE · FIX GUIDE Table of contents on long pages IMPACTEFFORT TIME30–60 minutes for a template fix, plus 5 minutes per manually edited page LEVELIntermediate

Why it matters

A table of contents lets readers jump straight to the section they need, which cuts pogo-sticking on long pages. It also gives Google clear section anchors it can show as "Jump to" links and use for scroll-to-text deep links. AI answer engines use the same headings and anchors to cite a specific passage instead of the whole page. The ranking effect is small, which is why the impact is rated Low, but the change is cheap and the usability gain on mobile is real.

✕Beforehttps://example.com/blog/pricing-guidehas 3,200 words and 9 H2 sections butno links to any of them; readers must✓AfterThe same page opens with a "Contents"box of 9 links, such as <ahref="#refund-policy">, each jumping

What you need

A list of your long pages, from a crawler with a word count column such as Screaming Frog or Sitebulb
Edit access to your CMS post editor or theme templates
Basic HTML knowledge to add id attributes and anchor links
A browser with DevTools to check the rendered result

Step-by-step fix

1

List the pages that need a table of contents

Crawl your site and export URL, word count and H2 count. In Screaming Frog, run the crawl, open the Internal tab, filter to HTML, and sort by the Word Count column. Any article or guide over roughly 1,500 words with three or more H2 sections should get a TOC. Skip home, category, product and contact pages; these are not the long-form content this check targets.

Pro tip: Word counts in crawlers include navigation and footer text. If your boilerplate is heavy, set a content area under Configuration > Content > Content Area so only the article body is counted.
2

Give every H2 and H3 a stable id

Jump links need a target. Add a short, lowercase, hyphenated id to each section heading. Keep IDs stable after publishing, because people and search engines will link to them. Do not reuse an ID on the same page.

html
<h2 id="how-pricing-works">How pricing works</h2>
<h3 id="monthly-vs-annual">Monthly vs annual billing</h3>
<h2 id="refund-policy">Refund policy</h2>
Pro tip: Avoid IDs that start with a number or contain spaces. "refund-policy" is safe; "3 Refund Policy!" is not.
3

Add the table of contents block near the top

Place a <nav> with links to those IDs right after the intro paragraph, above the first H2. Use real <a href="#id"> links in the HTML so crawlers can see them without running JavaScript. Label the nav so screen readers announce it.

html
<nav class="toc" aria-labelledby="toc-title">
  <h2 id="toc-title">Contents</h2>
  <ol>
    <li><a href="#how-pricing-works">How pricing works</a>
      <ol>
        <li><a href="#monthly-vs-annual">Monthly vs annual billing</a></li>
      </ol>
    </li>
    <li><a href="#refund-policy">Refund policy</a></li>
  </ol>
</nav>
Pro tip: Keep it to H2s, with H3s only when sections are long. A 40-item TOC is as hard to scan as the article itself.
4

Automate it in your article template (optional)

If you publish often, generate the TOC from headings instead of writing it by hand. The safest approach is server-side, through a CMS plugin, a Liquid snippet or a build-time Markdown plugin, so the links exist in the raw HTML. Use the script below as a fallback for templates you cannot change on the server. It only builds a TOC when the article has 3 or more H2s.

javascript
<script>
document.addEventListener('DOMContentLoaded', function () {
  var article = document.querySelector('article');
  if (!article) return;
  var heads = article.querySelectorAll('h2');
  if (heads.length < 3) return;
  var nav = document.createElement('nav');
  nav.className = 'toc';
  nav.setAttribute('aria-label', 'Contents');
  var ol = document.createElement('ol');
  heads.forEach(function (h) {
    if (!h.id) {
      h.id = h.textContent.trim().toLowerCase()
        .replace(/[^a-z0-9\s-]/g, '').replace(/\s+/g, '-');
    }
    var li = document.createElement('li');
    var a = document.createElement('a');
    a.href = '#' + h.id;
    a.textContent = h.textContent;
    li.appendChild(a);
    ol.appendChild(li);
  });
  nav.appendChild(ol);
  heads[0].parentNode.insertBefore(nav, heads[0]);
});
</script>
Pro tip: JavaScript-built TOCs work for users, but crawlers that read only the raw source will not see them. Prefer a server-rendered TOC when you can.
5

Fix scrolling under sticky headers

If your site has a fixed header, jump links will hide the heading behind it. Add scroll-margin-top to the headings and smooth scrolling to the page. Respect users who prefer reduced motion.

text
h2[id], h3[id] { scroll-margin-top: 90px; }
@media (prefers-reduced-motion: no-preference) {
  html { scroll-behavior: smooth; }
}
.toc { border: 1px solid #ddd; padding: 1rem 1.25rem; margin: 1.5rem 0; }
.toc ol { margin: 0; padding-left: 1.25rem; }
Pro tip: Set the scroll-margin-top value to your header height plus about 10px.
6

Check the result and re-run the audit

Open a fixed page, view the source with Ctrl+U or Cmd+Option+U, and search for href="#. You should find one link per section. Click every TOC link and confirm it lands on the right heading. Then re-crawl the site or re-run the audit to confirm that the long pages are no longer flagged.

text
curl -s https://example.com/blog/pricing-guide | grep -o 'href="#[^"]*"' | sort -u
Pro tip: Also test one link directly, such as https://example.com/blog/pricing-guide#refund-policy, in a fresh tab.

Platform-specific notes

WordPress

Core Gutenberg does not include a stable TOC block. The free Rank Math SEO plugin adds a "Table of Contents by Rank Math" block, and the Easy Table of Contents plugin can insert one automatically on posts above a set heading count (Settings > Table of Contents > Auto Insert). Both output server-rendered anchor links. To add your own IDs, select a heading and open Block settings > Advanced > HTML anchor.

Shopify

Blog posts use the rich text editor. Click the Show HTML (<>) button to add id attributes and a TOC list manually. For automation, create a theme snippet in Online Store > Themes > Edit code, include it in main-article.liquid (the name varies by theme), and generate the IDs from article.content. Several TOC apps exist in the Shopify App Store but may render with JavaScript only.

Webflow

Headings inside a Rich Text element cannot be given IDs in the Designer. For CMS blog posts, either use a JavaScript generator in the Collection template's Page Settings > Before </body> tag, or use Finsweet Attributes Table of Contents. Static pages can set a heading's ID under Element Settings > ID.

Next.js / MDX

Add rehype-slug to give headings IDs at build time and rehype-autolink-headings for anchor links. Then extract the headings into a TOC component, for example with remark-toc or a custom remark plugin. Because this runs during SSG or SSR, the links are present in the HTML that crawlers fetch.

Wix

Wix Blog's post editor offers a Table of Contents element (+ Add > Table of Contents) built from your post headings. Availability depends on the editor version. On Wix Studio static pages, use anchors (Add > Anchor) and link text to them manually.

Check that it worked

✅ How to verify

  • View the page source, not just the rendered DOM, and confirm the TOC <a href="#..."> links exist with matching id attributes on the headings.
  • Click every TOC link on desktop and mobile; each should land on its heading without it being hidden under a sticky header.
  • Re-crawl with Screaming Frog or re-run the site audit and confirm that pages over about 1,500 words are no longer reported as missing a table of contents.
  • After Google recrawls, search for the page and look for "Jump to" section links, or use URL Inspection > View crawled page in Search Console to confirm the TOC is in the indexed HTML.

⚠️ Common mistakes

  • Building the TOC only with client-side JavaScript, so crawlers that read the raw HTML see no jump links.
  • Linking to IDs that do not exist or contain typos, which produces dead anchors that do nothing when clicked.
  • Changing heading IDs every time a title is edited, which breaks inbound links to sections that have already been shared.
  • Adding a TOC to short pages or product pages where it only pushes the main content down.

Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.

Check my site free

FAQ

How long should a page be before it needs a table of contents?

A practical threshold is around 1,500 words or three or more H2 sections. Below that, most readers can scan the page without one.

Does a table of contents help SEO?

Indirectly. It can earn "Jump to" sitelinks in Google, helps search engines and AI tools identify and cite specific sections, and improves usability on long pages. It is not a direct ranking factor.

Should the table of contents be collapsible?

It can be, as long as the links stay in the HTML. A <details><summary>Contents</summary>…</details> element collapses it without JavaScript and keeps the links crawlable.

Should I include H3 headings in the table of contents?

Only when H2 sections are long or contain distinct subtopics. Two levels at most keeps the list short enough to be useful.