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.
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.
What you need
Step-by-step fix
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.
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.
<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>
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.
<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>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.
<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>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.
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; }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.
curl -s https://example.com/blog/pricing-guide | grep -o 'href="#[^"]*"' | sort -u
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 freeFAQ
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.