Add dynamic sidebar table of contents with scroll-spy

benbalter · Copilot · benbalter · commit 18d04c822bf2 · 2026-04-26T16:12:41.000-04:00
Add a sticky right-sidebar TOC on xl: screens that highlights the
active section as the reader scrolls, using IntersectionObserver.
On smaller screens, the existing inline collapsible TOC is preserved.

- Extract shared heading parsing into src/utils/toc.ts with tests
- New TableOfContentsSidebar.astro with scroll-spy and accent border
- PostLayout uses flex layout at xl: breakpoint for sidebar placement
- Respects prefers-reduced-motion and hidden in print

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/src/components/TableOfContents.astro b/src/components/TableOfContents.astro
@@ -7,43 +7,23 @@
  * <details> element — zero JavaScript, progressively enhanced.
  *
  * Only renders when there are 3+ headings (short posts don't need a TOC).
+ * Hidden on xl: screens where the sidebar TOC is shown instead.
  */
 
+import { extractHeadings, MIN_HEADINGS_FOR_TOC } from '../utils/toc';
+
 interface Props {
   /** Rendered HTML content of the post */
   content: string;
 }
 
-interface TocEntry {
-  id: string;
-  text: string;
-  level: number;
-}
-
 const { content } = Astro.props;
-
-// Extract h2 and h3 headings with their IDs from rendered HTML
-const headingRegex = /<h([23])\s+id="([^"]+)"[^>]*>(.*?)<\/h[23]>/gi;
-const headings: TocEntry[] = [];
-let match: RegExpExecArray | null;
-
-while ((match = headingRegex.exec(content)) !== null) {
-  // Strip HTML tags from heading text (e.g. anchor links from rehype-autolink-headings)
-  const text = match[3].replace(/<[^>]+>/g, '').replace(/#$/, '').trim();
-  if (text) {
-    headings.push({
-      level: parseInt(match[1]),
-      id: match[2],
-      text,
-    });
-  }
-}
-
-const showToc = headings.length >= 3;
+const headings = extractHeadings(content);
+const showToc = headings.length >= MIN_HEADINGS_FOR_TOC;
 ---
 
 {showToc && (
-  <details class="toc-container not-prose mb-8 rounded-lg border border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-800/50">
+  <details class="toc-container not-prose mb-8 rounded-lg border border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-800/50 xl:hidden">
     <summary class="cursor-pointer select-none px-4 py-3 text-sm font-semibold text-gray-700 dark:text-gray-300 hover:text-primary dark:hover:text-primary-300 transition-colors duration-200">
       Table of contents
     </summary>
diff --git a/src/components/TableOfContentsSidebar.astro b/src/components/TableOfContentsSidebar.astro
@@ -0,0 +1,203 @@
+---
+/**
+ * TableOfContentsSidebar
+ *
+ * Sticky right-sidebar table of contents with scroll-spy highlighting.
+ * Visible only on xl: screens (≥1280px). Uses IntersectionObserver to
+ * track which heading is currently in view and highlights it with an
+ * accent left-border. Respects prefers-reduced-motion.
+ *
+ * Only renders when there are 3+ headings.
+ */
+
+import { extractHeadings, MIN_HEADINGS_FOR_TOC } from '../utils/toc';
+
+interface Props {
+  /** Rendered HTML content of the post */
+  content: string;
+}
+
+const { content } = Astro.props;
+const headings = extractHeadings(content);
+const showToc = headings.length >= MIN_HEADINGS_FOR_TOC;
+---
+
+{showToc && (
+  <aside
+    class="toc-sidebar hidden xl:block"
+    aria-label="Table of contents"
+    data-toc-sidebar
+  >
+    <nav>
+      <p class="toc-sidebar-title">On this page</p>
+      <ol class="toc-sidebar-list">
+        {headings.map((h) => (
+          <li>
+            <a
+              href={`#${h.id}`}
+              class:list={['toc-sidebar-link', h.level === 3 && 'toc-sidebar-link--nested']}
+              data-toc-href={h.id}
+            >
+              {h.text}
+            </a>
+          </li>
+        ))}
+      </ol>
+    </nav>
+  </aside>
+)}
+
+<script>
+  function initTocSidebar() {
+    const sidebar = document.querySelector('[data-toc-sidebar]');
+    if (!sidebar) return;
+
+    const links = sidebar.querySelectorAll<HTMLAnchorElement>('[data-toc-href]');
+    if (links.length === 0) return;
+
+    // Map heading IDs to their TOC link elements
+    const linkMap = new Map<string, HTMLAnchorElement>();
+    links.forEach((link) => {
+      const id = link.dataset.tocHref;
+      if (id) linkMap.set(id, link);
+    });
+
+    // Track which headings are currently visible
+    const visibleHeadings = new Set<string>();
+    let orderedIds: string[] = [];
+
+    // Collect heading elements in DOM order
+    linkMap.forEach((_, id) => {
+      const el = document.getElementById(id);
+      if (el) orderedIds.push(id);
+    });
+
+    function setActive(id: string | null) {
+      links.forEach((link) => link.removeAttribute('data-active'));
+      if (id) {
+        const activeLink = linkMap.get(id);
+        if (activeLink) {
+          activeLink.setAttribute('data-active', 'true');
+        }
+      }
+    }
+
+    // Pick the topmost visible heading, or the last heading above viewport
+    function updateActive() {
+      if (visibleHeadings.size > 0) {
+        // Find the first visible heading in DOM order
+        for (const id of orderedIds) {
+          if (visibleHeadings.has(id)) {
+            setActive(id);
+            return;
+          }
+        }
+      }
+
+      // No heading is visible — find the last heading above the viewport
+      let lastAbove: string | null = null;
+      for (const id of orderedIds) {
+        const el = document.getElementById(id);
+        if (el && el.getBoundingClientRect().top < 100) {
+          lastAbove = id;
+        }
+      }
+      setActive(lastAbove);
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            visibleHeadings.add(entry.target.id);
+          } else {
+            visibleHeadings.delete(entry.target.id);
+          }
+        });
+        updateActive();
+      },
+      { rootMargin: '-80px 0px -60% 0px', threshold: 0 }
+    );
+
+    orderedIds.forEach((id) => {
+      const el = document.getElementById(id);
+      if (el) observer.observe(el);
+    });
+
+    // Initial highlight
+    updateActive();
+  }
+
+  initTocSidebar();
+</script>
+
+<style>
+  @reference "../styles/global.css";
+
+  .toc-sidebar {
+    position: sticky;
+    top: 6rem;
+    align-self: start;
+    max-height: calc(100vh - 8rem);
+    overflow-y: auto;
+    scrollbar-width: thin;
+    scrollbar-color: var(--color-gray-300) transparent;
+    width: 14rem;
+    flex-shrink: 0;
+  }
+
+  .toc-sidebar-title {
+    @apply text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400;
+    margin: 0 0 0.75rem 0;
+  }
+
+  .toc-sidebar-list {
+    @apply list-none m-0 p-0;
+  }
+
+  .toc-sidebar-link {
+    @apply block text-sm py-1.5 no-underline;
+    @apply text-gray-500 dark:text-gray-400;
+    border-left: 2px solid transparent;
+    padding-left: 0.75rem;
+    transition: color 0.15s ease, border-color 0.15s ease;
+  }
+
+  .toc-sidebar-link:hover {
+    @apply text-gray-800 dark:text-gray-200;
+  }
+
+  .toc-sidebar-link[data-active="true"] {
+    color: var(--color-primary);
+    border-left-color: var(--color-primary);
+    @apply font-medium;
+  }
+
+  .toc-sidebar-link--nested {
+    padding-left: 1.5rem;
+    @apply text-xs;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    .toc-sidebar {
+      scrollbar-color: var(--color-gray-700) transparent;
+    }
+
+    .toc-sidebar-link[data-active="true"] {
+      color: var(--color-primary-300);
+      border-left-color: var(--color-primary-300);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .toc-sidebar-link {
+      transition: none;
+    }
+  }
+
+  @media print {
+    .toc-sidebar {
+      display: none;
+    }
+  }
+</style>
diff --git a/src/layouts/PostLayout.astro b/src/layouts/PostLayout.astro
@@ -19,6 +19,7 @@ import ArchivedPostWarning from '../components/ArchivedPostWarning.astro';
 import ShareButtons from '../components/ShareButtons.astro';
 import PostNavigation from '../components/PostNavigation.astro';
 import TableOfContents from '../components/TableOfContents.astro';
+import TableOfContentsSidebar from '../components/TableOfContentsSidebar.astro';
 import ReadingList from '../components/ReadingList.astro';
 import ReadingProgress from '../components/ReadingProgress.astro';
 import KeepReading from '../components/KeepReading.astro';
@@ -95,9 +96,9 @@ const blogPostingSchema = pubDate ? generateBlogPostingSchema({
   image={image}
   author={author}
 >
-  <div class="max-w-4xl mx-auto px-4">
-    <div>
-      <article data-pagefind-body>
+  <div class="max-w-4xl mx-auto px-4 xl:max-w-6xl">
+    <div class="xl:flex xl:gap-8">
+      <article data-pagefind-body class="xl:flex-1 xl:min-w-0 xl:max-w-4xl">
         <Breadcrumbs title={title} />
         <header class="mb-10">
           <h1 class="text-3xl md:text-4xl font-bold leading-tight text-gray-900 dark:text-gray-100">{title}</h1>
@@ -187,6 +188,8 @@ const blogPostingSchema = pubDate ? generateBlogPostingSchema({
       {blogPostingSchema && (
         <script type="application/ld+json" set:html={schemaToJsonLd(blogPostingSchema)} is:inline></script>
       )}
+
+      <TableOfContentsSidebar content={content} />
     </div>
   </div>
 </BaseLayout>
diff --git a/src/utils/toc.test.ts b/src/utils/toc.test.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { extractHeadings, MIN_HEADINGS_FOR_TOC } from './toc';
+
+describe('extractHeadings', () => {
+  it('extracts h2 and h3 headings with IDs', () => {
+    const html = `
+      <h2 id="intro">Introduction</h2>
+      <p>Some content</p>
+      <h3 id="details">Details</h3>
+      <h2 id="conclusion">Conclusion</h2>
+    `;
+    expect(extractHeadings(html)).toEqual([
+      { level: 2, id: 'intro', text: 'Introduction' },
+      { level: 3, id: 'details', text: 'Details' },
+      { level: 2, id: 'conclusion', text: 'Conclusion' },
+    ]);
+  });
+
+  it('strips nested HTML tags from heading text', () => {
+    const html = '<h2 id="test"><a href="#test">Linked <strong>heading</strong></a></h2>';
+    expect(extractHeadings(html)).toEqual([
+      { level: 2, id: 'test', text: 'Linked heading' },
+    ]);
+  });
+
+  it('strips trailing # from heading text', () => {
+    const html = '<h2 id="test"><a href="#test">Heading#</a></h2>';
+    expect(extractHeadings(html)).toEqual([
+      { level: 2, id: 'test', text: 'Heading' },
+    ]);
+  });
+
+  it('skips headings with empty text after stripping', () => {
+    const html = '<h2 id="empty"><a href="#empty">#</a></h2>';
+    expect(extractHeadings(html)).toEqual([]);
+  });
+
+  it('ignores h1, h4, h5, h6 headings', () => {
+    const html = `
+      <h1 id="title">Title</h1>
+      <h2 id="section">Section</h2>
+      <h4 id="sub">Sub</h4>
+    `;
+    expect(extractHeadings(html)).toEqual([
+      { level: 2, id: 'section', text: 'Section' },
+    ]);
+  });
+
+  it('returns empty array for content with no headings', () => {
+    expect(extractHeadings('<p>No headings here</p>')).toEqual([]);
+  });
+
+  it('handles headings with extra attributes', () => {
+    const html = '<h2 id="test" class="text-lg" data-custom="true">Heading</h2>';
+    expect(extractHeadings(html)).toEqual([
+      { level: 2, id: 'test', text: 'Heading' },
+    ]);
+  });
+});
+
+describe('MIN_HEADINGS_FOR_TOC', () => {
+  it('is 3', () => {
+    expect(MIN_HEADINGS_FOR_TOC).toBe(3);
+  });
+});
diff --git a/src/utils/toc.ts b/src/utils/toc.ts
@@ -0,0 +1,39 @@
+/**
+ * Table of contents heading extraction utility.
+ *
+ * Parses rendered HTML to extract h2/h3 headings with their IDs,
+ * used by both the inline and sidebar TOC components.
+ */
+
+export interface TocEntry {
+  id: string;
+  text: string;
+  level: number;
+}
+
+/**
+ * Extract h2 and h3 headings with their IDs from rendered HTML.
+ * Strips nested HTML tags (e.g. anchor links from rehype-autolink-headings)
+ * and trailing `#` characters.
+ */
+export function extractHeadings(html: string): TocEntry[] {
+  const headingRegex = /<h([23])\s+id="([^"]+)"[^>]*>(.*?)<\/h[23]>/gi;
+  const headings: TocEntry[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = headingRegex.exec(html)) !== null) {
+    const text = match[3].replace(/<[^>]+>/g, '').replace(/#$/, '').trim();
+    if (text) {
+      headings.push({
+        level: parseInt(match[1]),
+        id: match[2],
+        text,
+      });
+    }
+  }
+
+  return headings;
+}
+
+/** Minimum number of headings required to show a TOC. */
+export const MIN_HEADINGS_FOR_TOC = 3;
