How to Add Table of Contents: Step-by-Step Guide

Adding a table of contents can cut reader frustration and improve how search engines understand long pages. This guide on how to add table of contents walks through prerequisites, editor-specific steps (WordPress, Webflow, Notion, Shopify, Ghost, raw HTML), SEO and accessibility tuning, and ongoing maintenance. You’ll learn practical anchor formats, where to place the TOC for best UX, and how to detect and fix broken anchors quickly.

TL;DR:

• Put a page-level TOC near the top for long articles (3–12 entries) and a site-level index only for multi-page pillars.

• Use CMS blocks or named anchors (kebab-case IDs) for stable links; test anchors after edits and update permalinks if headings change.

• Automate checks with broken-link auditing and schedule quarterly reviews; consider dynamic TOC blocks for content published on a recurring schedule.

Step 1: What You Need Before Adding a Table of Contents

Decide Scope: Page vs Site-level TOC

• Page-level TOC: Best for single long articles, guides, and FAQs. Aim for 3–12 visible entries for readability.

• Site-level index: Use for pillar pages or microsites that link many subpages. This requires a clear URL structure and sitemap entries.

Identify Heading Structure (H1–H4)

• H1: Page title only. Don’t include H1s inside the TOC as targets.

• H2: Primary sections that appear in the TOC by default.

• H3–H4: Use for subsections on complex pages; include only when they add navigation value. Research shows that up to H4 can be useful on technical pages; for marketing landing pages, stop at H3 to avoid cognitive overload.

Check Accessibility and SEO Goals

• Define measurable goals: reduce average time to find content, lower bounce rate, improve crawlability of long-form content.

• Review whether the TOC is for human navigation, search signals, or both. A visible TOC helps users; a hidden one rarely helps both bots and people simultaneously.

• If you’re building localized landing pages, shape the TOC to match intent and local content blocks — see our guide on the local SEO checklist for how TOC structure affects local landing pages.

• For pillar-driven sites, align TOC decisions with your cornerstone content strategy.

What else to have ready

• Editor access to your CMS or theme files.

• A consistent slug/anchor policy (kebab-case recommended, e.g., #how-to-add-table-of-contents).

• A content map that lists headings and desired anchor labels.

• For Word and PDF outputs, follow university-style TOC standards where appropriate — see the UNT guide to table of contents generation for structured document TOC rules.

Quick tip: run an initial content audit and tag pages that will benefit from a TOC. For pillar pages that will host many clusters, a site-level index may be appropriate; otherwise, keep TOCs page-scoped.

Step 2: Add a Table of Contents in Wordpress (gutenberg and Classic Editors)

Gutenberg: Use a TOC Block or Anchor Links

• Open the post in the Gutenberg editor. Search for a "Table of contents" block provided by your theme or a plugin. If available, insert it near the top, immediately after the intro paragraph.

• Configure depth: set the block to include H2 and H3 by default. Use H4 only for highly technical pages.

• Anchor IDs: the block typically auto-generates slugs from headings. Confirm they use kebab-case (lowercase words separated by hyphens) to avoid spaces or special characters.

• Placement: put the TOC after a short summary so readers see context before jumping.

Classic Editor: Insert Manual Anchors or Shortcode

• Classic editor requires either a plugin that inserts a TOC shortcode or manual anchor tags.

• To create a manual anchor: add an id attribute to a heading tag, e.g.,

  Pricing plans

  , then link from the TOC as Pricing plans.

• Shortcodes: many themes or plugins expose [toc] shortcodes — configure depth and exclude headings as needed.

Best Practices for Permalinks and Anchor Ids

• Use stable heading slugs. If you change a heading, update the anchor or leave a 301 in place if the anchor was referenced externally.

• Keep anchor IDs short and descriptive. Avoid special characters and punctuation.

• Test anchors after saving: click each TOC link to confirm it scrolls to the correct section.

Watch this step-by-step guide on adding a table of contents into wordpress:

Accessibility and table design notes

• When your TOC includes tables or data-heavy sections, follow table design best practices to keep layout consistent; the CSE Science Editor outlines table design guidance that helps with readability and order of notes, which can affect how you label TOC entries for data sections: best practices in table design.

Example: SEO-focused service page

• For service pages like a mechanic or a bookkeeper guide, a short TOC that lists H2s helps users jump to pricing, services, and contact sections. See our practical example on SEO for mechanics for how TOC placement improved findability on a long service page.

Common WordPress pitfalls

• Theme JavaScript rewriting heading IDs after load (test in an incognito window).

• Plugins generating duplicate IDs — check the page source if the TOC targets jump to the top or wrong spot.

Step 3: Add a Table of Contents in Other Editors (webflow, Notion, Shopify, Ghost, HTML)

Webflow: Use Anchors and the Site Navigator

• In Webflow, add an element (text link or list) and set its link to an anchor on the page. Use the site navigator to confirm the anchor is attached to the correct element.

• Anchor naming: Webflow uses IDs that show in the element settings — choose kebab-case and avoid auto-generated names like "section-1" if you want stable references.

• If your site uses a global header with offset (sticky header), add scroll offset CSS or script so anchors land below the header.

Notion: Use Built-in Table of Contents Block

• Notion includes a native Table of Contents block that lists H1–H3 by default. Drag it to the top of the page.

• Limitations: Notion’s TOC is page-only and is not crawlable by site search engines unless you publish to a site and expose anchors.

Shopify/ghost/custom HTML: Manual Anchor List

• Shopify themes: edit the theme template to insert a TOC block or use an app that generates a TOC. If editing theme files, add a simple unordered list of anchor links and ensure the liquid template outputs consistent heading IDs.

• Ghost: add an HTML card with a TOC list or use theme partials that parse headings on render.

• Raw HTML fallback: create a UL where each LI contains an anchor to the heading id, e.g.:

• • Install
  • Configure

Content publishing workflows

• If you publish directly via a CMS integration (for example, using direct CMS publishing to WordPress, Webflow, Shopify, Notion, Ghost, or Sanity), ensure your publishing template includes the TOC block so it is consistently added on publish.

• When using AI-generated content, confirm TOC accuracy: generated headings may change between draft and final publish. See our discussion on AI vs human content about ensuring generated headings remain accurate and consistent with TOC links.

Document TOC tips

• For exported documents, follow MS Word instructions to apply heading styles before generating a TOC — the UT Dallas resource explains how updating fields works for Word documents and when to refresh the TOC after edits: Table of contents in Microsoft Word.

Example scenario

• An evergreen long-form guide for home-building companies often uses a mix of H2 and H3 entries. See how a long-form evergreen benefits from clear site structure in our SEO for home builders example.

Step 4: Optimize Your Table of Contents for SEO and Accessibility

SEO: Use Keywords in Visible Headings, Not the TOC Itself

• Put target keywords into the actual H2/H3 headings rather than stuffing the TOC with keyword variations. Headings are content signals for search engines; TOC links should reflect those headings verbatim.

• Avoid duplicate anchor text across pages. If multiple pages use the same TOC wording, refine headings to match page intent.

Accessibility: ARIA Roles and Keyboard Focus

• Wrap the TOC in a nav element with role="navigation" and an accessible label, e.g.,

• Add a "skip to content" link before the TOC for keyboard users if the TOC appears above the main content.

• Ensure keyboard focus moves to the target element; some single-page apps require JS to move focus after the anchor jump.

Performance: Lazy-load Long Tocs and Measure Impact

• If a page has a very long TOC (dozens of entries), consider lazy-rendering the TOC or collapsing it by default to reduce layout shift.

• Measure CLS (Cumulative Layout Shift) and render time using Lighthouse or your analytics tools. If TOC insertion triggers layout shifts, move the TOC into a reserved space or use CSS to prevent reflow. Our guide to optimize core web vitals shows how to measure layout shift and fix common causes.

Visible vs hidden TOCs

• Visible TOC: best for UX. Users see navigation and jump to sections quickly. Visible TOCs also help screen reader users when properly labeled.

• Hidden TOC (for bots only): rarely recommended. Hiding a TOC and exposing it only to crawlers risks accessibility and might be treated suspiciously by search engines.

Practical SEO checks

• Ensure your sitemap and canonical tags align with your preferred page URLs so internal TOC links point to the canonical path.

Example: sector-specific optimization

• For a service page such as a bookkeeper guide, accessible headings and a short TOC improve trust and conversions. See sector tips in our SEO for bookkeepers.

Step 5: Automate and Maintain Your Table of Contents

Use Plugins, Blocks, or CMS Templates

• For scale, add a TOC block to your CMS templates so new posts inherit consistent TOC settings. When using direct CMS publishing to WordPress, Webflow, Shopify, Notion, Ghost, or Sanity, include the TOC block in your publishing template.

• Autopilot publishing: if your workflow publishes content on a recurring schedule, ensure the TOC generation step is part of the template to avoid missed navigation on auto-published pages.

Set Up Checks: Broken-link Auditing and Repair

• Schedule scans after significant site pushes (theme updates, bulk edits, migration) and after changes to heading templates.

Schedule Reviews and Content Updates

• Recommended cadence: quick checks on publish, weekly scans for high-traffic sections, and full audits quarterly.

• For programmatic content at scale, balance automation with manual review. See guidance on when to program at scale and when to review: consult our posts about programmatic SEO limits, the real cost of in-house SEO, and review vs full automation.

Automation trade-offs

• Full automation reduces headcount and speeds publishing, but it can introduce duplicate or inconsistent headings across thousands of pages. Our piece on the risks of automated publishing explains how to avoid common pitfalls such as broken anchors or template duplication.

• If you use programmatic generation, include verification steps that assert heading uniqueness and anchor validity before publish.

Integrations and API options

• Tie TOC generation into your publishing workflow with Zapier or a REST API so new posts get a consistent TOC automatically.

• For teams that want repeatable publishing, a recurring autopublish mode that writes and publishes on schedule should include a TOC validation step.

Quick checklist for maintenance

• Add TOC block to templates.

• Automate broken-anchor scans and repairs.

• Run manual spot checks on representative pages monthly.

• Maintain a naming convention for anchors and document it in your style guide.

Troubleshooting & Common Mistakes When Adding a Table of Contents

Anchors Not Jumping to Sections

• Cause: incorrect ID syntax, duplicate IDs, or JS that alters DOM after anchor click.

• Fix: inspect the heading in browser dev tools (Elements) to confirm the id attribute matches the link href (case-sensitive). If JavaScript is changing IDs, either disable that script for content headings or add a short delay then re-apply anchors.

• Diagnostic: view-source to see server-rendered IDs, then check document.querySelectorAll('h2[id]') in the console to see client-side changes.

TOC Shows Duplicate or Wrong Headings

• Cause: automated content generators creating repeated headings or templates injecting headings twice.

• Fix: remove duplicate headings, use unique IDs, or filter duplicates during TOC generation. If using automation, include a de-duplication step in your publishing workflow. For common editorial pitfalls, see our post on founder SEO pitfalls.

TOC Hurts Page Layout or Mobile Experience

• Cause: TOC with fixed height or absolute positioning overlapping content, or very long lists that push content down.

• Fix: use collapsible TOCs on mobile or hide the TOC behind a toggle that preserves accessibility (ensure the toggle is keyboard-accessible). For sticky headers, add scroll-margin-top on target headings to offset landing position.

Timing issues with dynamic content

• If the page renders headings after initial load (client-side rendering), TOC generation must wait for content render. Either generate TOC after hydration or use mutation observers to rebuild TOC when headings appear.

When to remove a TOC

• Short pages (<600 words) rarely need a TOC. If analytics show TOC clicks under 2% for a page type, consider removing it or simplifying it.

Reference troubleshooting resources

• For document-style problems, user guides like the Studybay walkthrough can help with structuring a research paper TOC: Table of contents research paper guide.

• Accessibility fixes and template cleanups often mirror issues seen on organizational sites; see our example for churches that require accessibility-first navigation in SEO for churches.

The Bottom Line

A clear, well-structured table of contents improves user navigation and helps search engines parse long pages; follow heading best practices, use kebab-case anchors, and automate ongoing checks. When deciding how to add table of contents, choose page-level TOCs for single-document navigation and site-level indexes only for true pillar structures.

Frequently Asked Questions