feat: add auto-generated ON THIS PAGE table of contents sidebar

jpr5 · jpr5 · commit 227eae0df16e · 2026-04-08T21:59:59.000-07:00
diff --git a/docs/a2a-mock/index.html b/docs/a2a-mock/index.html
@@ -225,6 +225,7 @@ <h2>Inspection</h2>
 a2a.reset();   <span class="cm">// Clears all agents and tasks</span></code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/aimock-cli/index.html b/docs/aimock-cli/index.html
@@ -305,6 +305,7 @@ <h2>Docker Compose</h2>
       - <span class="str">aimock</span></code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/aws-bedrock/index.html b/docs/aws-bedrock/index.html
@@ -344,6 +344,7 @@ <h2>Converse API</h2>
           format for fixture matching.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/azure-openai/index.html b/docs/azure-openai/index.html
@@ -172,6 +172,7 @@ <h2>Environment Variables</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/chaos-testing/index.html b/docs/chaos-testing/index.html
@@ -281,6 +281,7 @@ <h2>Prometheus Metrics</h2>
 aimock_chaos_triggered_total{action="disconnect"} 2</code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/chat-completions/index.html b/docs/chat-completions/index.html
@@ -228,6 +228,7 @@ <h3>Streaming (stream: true)</h3>
           <code>message</code>.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/claude-messages/index.html b/docs/claude-messages/index.html
@@ -148,6 +148,7 @@ <h2>Request Translation</h2>
           across all providers.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/cohere/index.html b/docs/cohere/index.html
@@ -234,6 +234,7 @@ <h2>Request Translation</h2>
           format.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/compatible-providers/index.html b/docs/compatible-providers/index.html
@@ -279,6 +279,7 @@ <h2>Example Fixture</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/docker/index.html b/docs/docker/index.html
@@ -205,6 +205,7 @@ <h2>v1.6.0 Features</h2>
           <li><strong>Converse API</strong> &mdash; Bedrock Converse and Converse-stream</li>
         </ul>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/drift-detection/index.html b/docs/drift-detection/index.html
@@ -537,6 +537,7 @@ <h2>CI Integration</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/embeddings/index.html b/docs/embeddings/index.html
@@ -192,6 +192,7 @@ <h2>Response Format</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/error-injection/index.html b/docs/error-injection/index.html
@@ -187,6 +187,7 @@ <h2>Interruption Behavior</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/fixtures/index.html b/docs/fixtures/index.html
@@ -284,6 +284,7 @@ <h2>Routing Rules</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/gemini/index.html b/docs/gemini/index.html
@@ -185,6 +185,7 @@ <h2>Vertex AI</h2>
           <a href="/vertex-ai">Vertex AI</a> page for configuration details.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/mcp-mock/index.html b/docs/mcp-mock/index.html
@@ -237,6 +237,7 @@ <h2>Inspection</h2>
 mcp.reset();        <span class="cm">// Clears all tools, resources, prompts, and sessions</span></code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/metrics/index.html b/docs/metrics/index.html
@@ -285,6 +285,7 @@ <h2>Implementation Details</h2>
           </li>
         </ul>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/migrate-from-mock-llm/index.html b/docs/migrate-from-mock-llm/index.html
@@ -514,6 +514,7 @@ <h2>CLI / Docker quick start</h2>
           </div>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/migrate-from-mokksy/index.html b/docs/migrate-from-mokksy/index.html
@@ -420,6 +420,7 @@ <h2>CLI / Docker quick start</h2>
           </div>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/migrate-from-msw/index.html b/docs/migrate-from-msw/index.html
@@ -388,6 +388,7 @@ <h2>CLI / Docker quick start</h2>
           </div>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/migrate-from-piyook/index.html b/docs/migrate-from-piyook/index.html
@@ -432,6 +432,7 @@ <h2>CLI / Docker quick start</h2>
           </div>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/migrate-from-python-mocks/index.html b/docs/migrate-from-python-mocks/index.html
@@ -514,6 +514,7 @@ <h2>Alternative: npx fixture (no Docker)</h2>
     proc.wait()</code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/migrate-from-vidaimock/index.html b/docs/migrate-from-vidaimock/index.html
@@ -355,6 +355,7 @@ <h2>CLI / Docker quick start</h2>
           </div>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
 
     <footer class="docs-footer">
diff --git a/docs/mount/index.html b/docs/mount/index.html
@@ -244,6 +244,7 @@ <h2>Built-in Services</h2>
           <code>createMockSuite()</code>, and the <a href="/aimock-cli">aimock CLI</a>.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/ollama/index.html b/docs/ollama/index.html
@@ -257,6 +257,7 @@ <h2>Request Translation</h2>
           across all providers.
         </p>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/record-replay/index.html b/docs/record-replay/index.html
@@ -438,6 +438,7 @@ <h2>Cross-Language Testing</h2>
 let client = Client::new().with_base_url("http://localhost:4010/v1");</code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/responses-api/index.html b/docs/responses-api/index.html
@@ -162,6 +162,7 @@ <h2>SSE Event Sequence</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/sequential-responses/index.html b/docs/sequential-responses/index.html
@@ -152,6 +152,7 @@ <h2>JSON Fixture</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/services/index.html b/docs/services/index.html
@@ -223,6 +223,7 @@ <h2>Journal Integration</h2>
 <span class="kw">const</span> moderationRequests = entries.filter((e) =&gt; e.service === <span class="str">"moderation"</span>);</code></pre>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/sidebar.js b/docs/sidebar.js
@@ -1,4 +1,4 @@
-/* global window, document */
+/* global window, document, IntersectionObserver, history */
 (function () {
   // ─── Nav Hierarchy ──────────────────────────────────────────────
   var sections = [
@@ -203,4 +203,98 @@
   var isOverview = currentPage === "/docs";
   var sectionBarEl = document.getElementById("section-bar");
   if (sectionBarEl && isOverview) sectionBarEl.innerHTML = buildSectionBar();
+
+  // ─── Page TOC (right sidebar) ──────────────────────────────────
+  function buildPageToc() {
+    var tocEl = document.getElementById("page-toc");
+    if (!tocEl) return;
+
+    var content = document.querySelector(".docs-content");
+    if (!content) return;
+
+    var headings = content.querySelectorAll("h2, h3");
+    if (headings.length < 4) return;
+
+    // Ensure each heading has an id for anchor links
+    for (var i = 0; i < headings.length; i++) {
+      var h = headings[i];
+      if (!h.id) {
+        h.id = h.textContent
+          .toLowerCase()
+          .replace(/[^a-z0-9\s-]/g, "")
+          .replace(/\s+/g, "-")
+          .replace(/-+/g, "-")
+          .replace(/^-|-$/g, "");
+      }
+    }
+
+    // Build TOC HTML
+    var html = '<div class="page-toc-label">On this page</div>';
+    for (var j = 0; j < headings.length; j++) {
+      var heading = headings[j];
+      var cls = heading.tagName === "H3" ? ' class="toc-h3"' : "";
+      html += '<a href="#' + heading.id + '"' + cls + ">" + heading.textContent + "</a>";
+    }
+    tocEl.innerHTML = html;
+
+    // Active state tracking with IntersectionObserver
+    var tocLinks = tocEl.querySelectorAll('a[href^="#"]');
+    var headingEls = [];
+    for (var k = 0; k < tocLinks.length; k++) {
+      var target = document.getElementById(tocLinks[k].getAttribute("href").slice(1));
+      if (target) headingEls.push(target);
+    }
+
+    if (!headingEls.length || typeof IntersectionObserver === "undefined") return;
+
+    function setActive(index) {
+      for (var m = 0; m < tocLinks.length; m++) {
+        tocLinks[m].classList.remove("active");
+      }
+      if (tocLinks[index]) {
+        tocLinks[index].classList.add("active");
+      }
+    }
+
+    var observer = new IntersectionObserver(
+      function (entries) {
+        // Find the topmost visible heading
+        var topmostIndex = -1;
+        for (var n = 0; n < entries.length; n++) {
+          if (entries[n].isIntersecting) {
+            var idx = headingEls.indexOf(entries[n].target);
+            if (idx !== -1 && (topmostIndex === -1 || idx < topmostIndex)) {
+              topmostIndex = idx;
+            }
+          }
+        }
+        if (topmostIndex !== -1) {
+          setActive(topmostIndex);
+        }
+      },
+      { rootMargin: "-80px 0px -60% 0px", threshold: 0 },
+    );
+
+    for (var p = 0; p < headingEls.length; p++) {
+      observer.observe(headingEls[p]);
+    }
+
+    // Set initial active state
+    setActive(0);
+
+    // Smooth scroll on click
+    for (var q = 0; q < tocLinks.length; q++) {
+      tocLinks[q].addEventListener("click", function (e) {
+        e.preventDefault();
+        var targetEl = document.getElementById(this.getAttribute("href").slice(1));
+        if (targetEl) {
+          targetEl.scrollIntoView({ behavior: "smooth", block: "start" });
+          // Update URL hash without jumping
+          history.pushState(null, "", this.getAttribute("href"));
+        }
+      });
+    }
+  }
+
+  buildPageToc();
 })();
diff --git a/docs/streaming-physics/index.html b/docs/streaming-physics/index.html
@@ -201,6 +201,7 @@ <h2>Realistic Profiles</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/structured-output/index.html b/docs/structured-output/index.html
@@ -161,6 +161,7 @@ <h2>Match Behavior</h2>
           </p>
         </div>
       </main>
+      <aside class="page-toc" id="page-toc"></aside>
     </div>
     <footer class="docs-footer">
       <div class="footer-inner">
diff --git a/docs/style.css b/docs/style.css
diff --git a/docs/vector-mock/index.html b/docs/vector-mock/index.html
diff --git a/docs/vertex-ai/index.html b/docs/vertex-ai/index.html
diff --git a/docs/websocket/index.html b/docs/websocket/index.html
