How to Add a Dynamic Table of Contents to Your Squarespace Blog Post

Create a dynamic, auto-updating Table of Contents for any Squarespace blog post to boost navigation and reduce bounce rate with one easy copy-paste script.

Simple table of contents for a Squarespace blog post, with nested list items showing the hierarchy of the blog post structure
  • Hank Teicheira By Hank Teicheira

Ever published a 2,000-word Squarespace post only to watch readers bounce after 20 seconds? Readers love depth, but they need a map. This tutorial shows you how to drop in a lightweight Table of Contents (TOC) that boosts navigation, improves SEO, and even trims Core Web Vitals—all with a single copy-paste snippet.

I implement this exact approach on high-traffic Squarespace builds for clients across Los Angeles. You’ll get the same code + pro-tips packaged for non-coders and tinkerers alike.

Quick Copy-Paste Start

Paste the block below into Blog Post → Settings → Advanced → Page Header Code Injection if you want the TOC on every post—or place it inside a single Code Block on an individual post if you’d rather add it case-by-case.


<!-- Begin Table of Contents -->
<style>
  .table-of-contents {
    padding: 0 2rem 1rem;
    border: 1px solid #3f342b;
    border-radius: 16px;
    margin: 2rem 0 1rem; /* top | left/right | bottom */
  }

  .table-of-contents h2 {
    margin: 1rem 0;
  }

  .table-of-contents li {
    line-height: 1.75;
    /* Optional: add your own typeface
       .table-of-contents li { font-family: 'YourFont'; } */
  }

  /* Prevent headings from hiding beneath a fixed header */
  .blog-item-content h2,
  .blog-item-content h3,
  .blog-item-content h4 {
    scroll-margin-top: 4rem; /* adjust if your header height differs */
  }

  @media screen and (max-width: 767px) {
    .table-of-contents {
      padding: 0 1rem 1rem;
      margin: 1rem 0; /* simpler mobile spacing */
    }
  }
</style>

<script defer>
  /* ---------- Helpers ---------- */
  const slugify = (text) =>
    text
      .toLowerCase()
      .trim()
      .replace(/[^a-z0-9s-]/g, "")
      .replace(/s+/g, "-")
      .replace(/-+/g, "-");

  /* Recursively turn headings into a tree */
  function processNode(heading, level) {
    const text = heading.textContent.trim();
    const id = slugify(text);
    heading.id = id;

    const node = { text, id, level, children: [] };
    let sibling = heading.nextElementSibling;

    while (sibling) {
      const match = sibling.tagName.match(/^H([2-4])$/);
      if (match) {
        const siblingLevel = +match[1];
        if (siblingLevel <= level) break;
        if (siblingLevel === level + 1) {
          node.children.push(processNode(sibling, siblingLevel));
        }
      }
      sibling = sibling.nextElementSibling;
    }
    return node;
  }

  function buildTree() {
    const container = document.querySelector(".blog-item-content");
    if (!container) return [];
    return Array.from(container.querySelectorAll("h2")).map((h2) =>
      processNode(h2, 2)
    );
  }

  /* Render the tree into nested <ul> */
  function renderTree(nodes) {
    const ul = document.createElement("ul");

    nodes.forEach((node) => {
      const li = document.createElement("li");
      const a = document.createElement("a");
      a.href = "#" + node.id;

      if (node.level === 2) {
        const strong = document.createElement("strong");
        strong.textContent = node.text;
        a.appendChild(strong);
      } else {
        a.textContent = node.text;
      }

      li.appendChild(a);
      if (node.children.length) li.appendChild(renderTree(node.children));
      ul.appendChild(li);
    });

    return ul;
  }

  /* Inject the TOC once the DOM is ready */
  function generateTOC() {
    const tree = buildTree();
    if (!tree.length) return;

    const toc = document.createElement("div");
    toc.className = "table-of-contents";

    const title = document.createElement("h2");
    title.textContent = "Table of Contents";
    toc.appendChild(title);
    toc.appendChild(renderTree(tree));

    /* Place after hero banner if one exists; otherwise, top of article */
    const banner = document.querySelector(
      ".blog-item-content-wrapper .image-block"
    );

    const target = banner
      ? banner // banner detected → put TOC after it
      : document.querySelector(".blog-item-content-wrapper") || document.body; // no banner → top

    target.insertAdjacentElement(banner ? "afterend" : "afterbegin", toc);
  }

  document.addEventListener("DOMContentLoaded", generateTOC);
</script>
<!-- End Table of Contents -->

(No JavaScript degree required—just paste and publish.)

Two ways to inject the script

Site-wide injection

Where: Blog Post → Settings → Advanced → Post Blog Item Code Injection (one-time setup)
Pros: Adds a TOC to every future and existing post automatically.
Cons: You’ll need to spot-check older posts to confirm the TOC lands in the right place (especially if layouts vary).

Single Code Block

Where: Add a Code Block at the very top (or anywhere) in a specific post.
Pros: Full control—apply the TOC only where you want it.
Cons: Must remember to paste the snippet for each new post that needs it.

Tip: If you use the single-post method, the Code Block can sit anywhere in the layout, but placing it at the very top (just below the post title) keeps your editor organized.

Customization & Performance Tweaks

Choosing where the TOC appears

By default, the script looks for a banner image block at the very top of the post and inserts the TOC right after it. If your first image isn’t a hero banner—or your article starts with text—Squarespace still labels that first image as an .image-block, so the TOC could end up midway through the piece.

Force it to the very top if no banner exists

Replace the last lines of generateTOC() with:


const banner = document.querySelector(
  ".blog-item-content-wrapper .image-block"
);

const target = banner
  ? banner // banner detected → place TOC after it
  : document.querySelector(".blog-item-content-wrapper") || document.body; // no banner → top

target.insertAdjacentElement(banner ? "afterend" : "afterbegin", toc);

This logic keeps the banner-first behavior but guarantees a top-of-article placement when no hero image exists.

Quick Tweaks at a Glance

  • H2-only TOC – In the script, swap /^H([2-4])$/ ➜ /^H([2])$/.
  • Brand colors – Replace #3f342b with your site’s hex color.
  • Font-family – Add a line of CSS to use your own font for the TOC.

Potential Drawbacks (Versus The Upside)

Even with the readable, non-minified script, the performance cost is tiny—while the engagement boost is significant:

  • Payload: ~8 KB raw → ~3 KB gzipped. Too small to move Largest Contentful Paint or Total Blocking Time.
  • Main-thread time: ~10 ms on a mid-range phone—below the 50 ms “long task” threshold.
  • CLS: The TOC is injected before first paint, so there’s no visual jump.

What about crawlers? Googlebot runs JavaScript, so it still discovers the new anchor IDs and links.

What is bounce rate and why does the TOC help?

Bounce rate measures the percentage of sessions where a user leaves after viewing only one page—no further clicks, no scroll-depth events. According to Backlinko, a high bounce rate can indicate that visitors aren’t finding what they need, or that the page loads slowly.

A dynamic TOC lowers bounce rate by:

  1. Instant navigation – visitors jump straight to the sub-section they care about instead of skimming or bouncing.
  2. Perceived speed – less scrolling friction means they reach useful content quicker, making them more likely to continue reading or click internal links.

Troubleshooting & FAQ

TOC doesn’t appear
Make sure the code is in Page Header Injection and your post has at least one H2. Squarespace sometimes strips tags in Code Blocks—use Post Settings instead.

Anchor lands too high / low
Tweak scroll-margin-top (currently 4rem) until the heading sits just below your fixed header.

Duplicate IDs warning
Rename repeated headings (“Introduction 2”) to keep slugs unique.

Styling & Branding Tips

  • Typography – add your own font with one CSS line, e.g. .table-of-contents li { font-family: 'YourFont'; }
  • Borders vs. shadows – prefer a soft shadow (box-shadow: 0 2px 8px rgba(0,0,0,.06)) if your palette is minimal.
  • Collapsible sections – wrap the entire TOC in <details> if you want it hidden by default on mobile.

SEO & UX Wins

  • Internal anchor links often surface as Jump to sitelinks in Google, boosting CTR.
  • Better navigation lowers bounce rate and increases dwell time—helpful ranking signals.
  • Screen-reader users gain quick landmarks, improving accessibility scores.

Next Steps

Need hands-on help optimizing your Squarespace site? Book a free 15-minute consult and I’ll walk you through quick wins tailored to your site.