feat(shell-docs): add table of contents (TOC) support

Author: samjulien

showcase/shell-docs/src/components/docs-page-view.tsx

@@ -16,6 +16,7 @@ import { SidebarNav } from "@/components/sidebar-nav";
 import { SidebarLink } from "@/components/sidebar-link";
 import { SidebarFrameworkSelector } from "@/components/sidebar-framework-selector";
 import { Snippet } from "@/components/snippet";
+import { DocsToc } from "@/components/docs-toc";
 import { docsComponents } from "@/lib/mdx-registry";
 import {
   NavNode,
@@ -26,6 +27,7 @@ import {
   loadDoc,
   CONTENT_DIR,
 } from "@/lib/docs-render";
+import { childrenToText, extractHeadings, slugify } from "@/lib/toc";
 
 export interface DocsPageViewProps {
   /** Slug path relative to `CONTENT_DIR` (no leading slash). */
@@ -86,6 +88,12 @@ export async function DocsPageView({
   const inlined = inlineSnippets(rawContent, slugPath);
   const content = convertTablesInJSX(inlined);
 
+  // Extract H2/H3 headings for the right-rail TOC. Run on the final
+  // content (post-snippet-inlining) so a page like threads.mdx whose
+  // body comes from a shared snippet still surfaces its sections.
+  const tocHeadings =
+    hideBody || doc.fm.hideTOC ? [] : extractHeadings(content);
+
   const defaultFramework = frameworkOverride ?? doc.fm.defaultFramework;
   const defaultCell = doc.fm.defaultCell;
 
@@ -226,6 +234,26 @@ export async function DocsPageView({
                         />
                       );
                     },
+                    // Inject stable IDs on H2/H3 so the right-rail TOC's
+                    // #anchor links resolve. Slugify the child text with the
+                    // same algorithm used by extractHeadings() so IDs line up
+                    // with the TOC entries.
+                    h2: ({
+                      children,
+                      ...rest
+                    }: React.HTMLAttributes<HTMLHeadingElement>) => (
+                      <h2 id={slugify(childrenToText(children))} {...rest}>
+                        {children}
+                      </h2>
+                    ),
+                    h3: ({
+                      children,
+                      ...rest
+                    }: React.HTMLAttributes<HTMLHeadingElement>) => (
+                      <h3 id={slugify(childrenToText(children))} {...rest}>
+                        {children}
+                      </h3>
+                    ),
                     // When rendering under a framework-scoped route, rewrite
                     // root-relative MDX links (/quickstart, /shared-state, …)
                     // to the framework-scoped equivalent so clicks never land
@@ -264,6 +292,8 @@ export async function DocsPageView({
             return body;
           })()}
       </main>
+
+      <DocsToc headings={tocHeadings} />
     </div>
   );
 }

showcase/shell-docs/src/components/docs-toc.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import type { TocHeading } from "@/lib/toc";
+
+export interface DocsTocProps {
+  headings: TocHeading[];
+}
+
+// Right-rail TOC. Hidden below xl (1280px) because the main column
+// already fills most of the viewport at laptop widths. Above that, it
+// sits beside the content with a scrollspy-highlighted active link.
+export function DocsToc({ headings }: DocsTocProps) {
+  const [activeSlug, setActiveSlug] = useState<string | null>(
+    headings[0]?.slug ?? null,
+  );
+
+  useEffect(() => {
+    if (headings.length === 0) return;
+
+    const targets = headings
+      .map((h) => document.getElementById(h.slug))
+      .filter((el): el is HTMLElement => el !== null);
+    if (targets.length === 0) return;
+
+    // Mark a heading active once its top crosses ~20% from the top of
+    // the viewport. `-20% 0px -70% 0px` creates a narrow "active band"
+    // near the top so a heading activates as it scrolls into reading
+    // position, not when it merely enters the viewport from the bottom.
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const intersecting = entries.filter((e) => e.isIntersecting);
+        if (intersecting.length === 0) return;
+        intersecting.sort(
+          (a, b) => a.boundingClientRect.top - b.boundingClientRect.top,
+        );
+        setActiveSlug(intersecting[0].target.id);
+      },
+      { rootMargin: "-20% 0px -70% 0px", threshold: 0 },
+    );
+
+    targets.forEach((el) => observer.observe(el));
+    return () => observer.disconnect();
+  }, [headings]);
+
+  if (headings.length === 0) return null;
+
+  return (
+    <aside className="hidden xl:block w-[200px] shrink-0 sticky top-0 self-start max-h-screen overflow-y-auto py-8 pl-6 pr-4">
+      <div className="text-[10px] font-mono uppercase tracking-widest text-[var(--text-faint)] mb-3">
+        On this page
+      </div>
+      <nav className="flex flex-col gap-1 text-[12px] leading-relaxed">
+        {headings.map((h) => {
+          const isActive = activeSlug === h.slug;
+          return (
+            <a
+              key={h.slug}
+              href={`#${h.slug}`}
+              // Sync the highlight immediately on click. The
+              // IntersectionObserver can't take over here because the
+              // anchor jump lands the target above the active band
+              // (which starts ~20% from the top of the viewport), so
+              // no intersection fires and the last-active slug would
+              // otherwise stay selected.
+              onClick={() => setActiveSlug(h.slug)}
+              className={`block transition-colors ${
+                h.depth === 3 ? "pl-3" : ""
+              } ${
+                isActive
+                  ? "text-[var(--accent)] font-medium"
+                  : "text-[var(--text-muted)] hover:text-[var(--text-secondary)]"
+              }`}
+            >
+              {h.text}
+            </a>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}

showcase/shell-docs/src/content/docs/generative-ui/tool-rendering.mdx

@@ -2,7 +2,6 @@
 title: Tool Rendering
 icon: "lucide/Server"
 description: Render your agent's tool calls with custom UI components.
-hideTOC: true
 snippet_cell: tool-rendering
 ---
 

showcase/shell-docs/src/lib/docs-render.tsx

@@ -711,6 +711,7 @@ export interface DocFrontmatter {
   description?: string;
   defaultFramework?: string;
   defaultCell?: string;
+  hideTOC?: boolean;
 }
 
 /**
@@ -780,6 +781,7 @@ export function loadDoc(
       : undefined;
   const defaultCell =
     typeof data.snippet_cell === "string" ? data.snippet_cell : undefined;
+  const hideTOC = data.hideTOC === true;
 
   return {
     source,
@@ -789,6 +791,7 @@ export function loadDoc(
       description,
       defaultFramework,
       defaultCell,
+      hideTOC,
     },
   };
 }

showcase/shell-docs/src/lib/toc.ts

@@ -0,0 +1,99 @@
+// Right-rail "On this page" TOC. Extracts H2/H3 headings from rendered
+// MDX source (post-snippet-inlining) so the TOC surfaces the page's
+// actual sections, including anything pulled in from shared snippets.
+//
+// Slug algorithm matches the conventional GitHub/rehype-slug behavior
+// closely enough for same-page anchors. Duplicate handling is kept
+// intentionally minimal — a scan of showcase/shell-docs content shows
+// no H2 collisions today; if that changes, swap in rehype-slug.
+
+export interface TocHeading {
+  depth: 2 | 3;
+  text: string;
+  slug: string;
+}
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[`*_~]/g, "")
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+// Strip trivial inline markdown (bold/italic/code spans) from heading
+// text so the rendered TOC labels read as plain prose rather than "** &
+// `` scattered through them.
+function plainHeadingText(raw: string): string {
+  return raw
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\*([^*]+)\*/g, "$1")
+    .replace(/_([^_]+)_/g, "$1")
+    .trim();
+}
+
+export function extractHeadings(source: string): TocHeading[] {
+  const lines = source.split("\n");
+  const headings: TocHeading[] = [];
+  const slugCounts = new Map<string, number>();
+  let inFence = false;
+  let fenceChar: "`" | "~" | "" = "";
+
+  for (const line of lines) {
+    // Track fenced code blocks so `# comment` inside python/js samples
+    // doesn't masquerade as a heading.
+    const fenceMatch = line.match(/^\s*(```+|~~~+)/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0] as "`" | "~";
+      if (!inFence) {
+        inFence = true;
+        fenceChar = marker;
+      } else if (fenceChar === marker) {
+        inFence = false;
+        fenceChar = "";
+      }
+      continue;
+    }
+    if (inFence) continue;
+
+    const match = line.match(/^(#{2,3})\s+(.+?)\s*$/);
+    if (!match) continue;
+    const depth = match[1].length as 2 | 3;
+    const text = plainHeadingText(match[2]);
+    if (!text) continue;
+
+    let slug = slugify(text);
+    if (!slug) continue;
+    const count = slugCounts.get(slug) ?? 0;
+    slugCounts.set(slug, count + 1);
+    if (count > 0) slug = `${slug}-${count}`;
+
+    headings.push({ depth, text, slug });
+  }
+
+  return headings;
+}
+
+// Flatten React heading children to a plain string so we can reuse the
+// slugify algorithm in the MDX `h2`/`h3` component overrides. Must match
+// the transforms applied by extractHeadings() so IDs line up with the
+// slugs surfaced in the TOC.
+export function childrenToText(children: unknown): string {
+  if (typeof children === "string") return children;
+  if (typeof children === "number") return String(children);
+  if (Array.isArray(children)) return children.map(childrenToText).join("");
+  if (
+    children &&
+    typeof children === "object" &&
+    "props" in children &&
+    typeof (children as { props: unknown }).props === "object"
+  ) {
+    const props = (children as { props: { children?: unknown } }).props;
+    return childrenToText(props?.children);
+  }
+  return "";
+}