feat(docs): move inline TOC to a responsive left sidebar; preserve logo aspect ratio

Doc pages with `:toc:` used to render the TOC as a long inline block at
the top of the body. On longer pages (Harness Inventory, Socratic Recovery
Skill, the Brownfield reports) that pushed the actual content far below
the fold.

- render-docs.js extracts the `<div id="toc">` block from each rendered
  page into a sidecar `<basename>.toc.html` (depth-counting parser so
  nested ULs are handled cleanly). Pages without a TOC produce no sidecar.
- doc-page.js wraps content in a two-slot flex layout: a sticky left
  sidebar on lg+ and a bordered, height-capped block above the content on
  smaller screens. The aside is hidden by default and only appears when a
  sidecar fetch returns an actual TOC fragment. A content-type-style
  sanity check rejects the Vite SPA fallback (index.html served as 200 OK
  for missing files), so pages without a TOC keep full-width content.
- TOC in-page links bypass the SPA router (which only handles `#/...`
  routes) and scroll smoothly to the target heading.
- asciidoctor-scoped.css gets a `.doc-toc` block with sticky-sidebar
  styling — small caps title, indented nested lists with a left border,
  hover backgrounds matching the theme tokens.

Also fixes a separate report: the header logo lost its aspect ratio on
narrow screens. Tailwind's preflight `max-width: 100%` was clamping the
img width while the height stayed pinned by `h-24`/`h-16`. Adding
`max-w-none shrink-0` keeps the declared dimensions intact at every
viewport.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: raifdmueller

scripts/render-docs.js

@@ -36,17 +36,62 @@ const OPTS = {
   },
 }
 
+/**
+ * Extract the AsciiDoc-generated `<div id="toc">...</div>` block from the
+ * rendered HTML. Returns `{ toc, body }` where `toc` is the TOC HTML (or
+ * `null` if the doc has no TOC) and `body` is the HTML with the TOC removed.
+ *
+ * AsciiDoctor outputs the TOC as a single `<div id="toc" class="toc">` (or
+ * `class="toc2"` for `:toc: left`). We depth-count `<div>` open/close tags
+ * so a TOC with arbitrarily nested ULs is removed cleanly.
+ *
+ * Splitting the TOC out at build time lets doc-page.js render it in its own
+ * sticky sidebar slot instead of inline at the top of the body.
+ */
+function extractToc(html) {
+  const startMatch = html.match(/<div[^>]*\sid="toc"[^>]*>/)
+  if (!startMatch) return { toc: null, body: html }
+  const start = startMatch.index
+  let depth = 1
+  let pos = start + startMatch[0].length
+  while (pos < html.length && depth > 0) {
+    const nextOpen = html.indexOf('<div', pos)
+    const nextClose = html.indexOf('</div>', pos)
+    if (nextClose === -1) return { toc: null, body: html }
+    if (nextOpen !== -1 && nextOpen < nextClose) {
+      depth++
+      pos = nextOpen + 4
+    } else {
+      depth--
+      pos = nextClose + 6
+    }
+  }
+  if (depth !== 0) return { toc: null, body: html }
+  return { toc: html.slice(start, pos), body: html.slice(0, start) + html.slice(pos) }
+}
+
 /**
  * Render a single AsciiDoc file to HTML.
  * Uses safe:'safe' so include:: directives are resolved from the filesystem.
+ * If the rendered HTML contains an AsciiDoc TOC, it is extracted into a
+ * sidecar `<basename>.toc.html` file so doc-page.js can render it in its
+ * own sidebar slot.
  */
 function renderFile(srcPath, destPath) {
   if (!fs.existsSync(srcPath)) return
   try {
     fs.mkdirSync(path.dirname(destPath), { recursive: true })
-    const html = asciidoctor.convertFile(srcPath, { ...OPTS, to_file: false })
-    fs.writeFileSync(destPath, String(html), 'utf-8')
+    const html = String(asciidoctor.convertFile(srcPath, { ...OPTS, to_file: false }))
+    const { toc, body } = extractToc(html)
+    fs.writeFileSync(destPath, body, 'utf-8')
     console.log(`Rendered: ${path.relative(ROOT, destPath)}`)
+    const tocPath = destPath.replace(/\.html$/, '.toc.html')
+    if (toc) {
+      fs.writeFileSync(tocPath, toc, 'utf-8')
+      console.log(`Rendered: ${path.relative(ROOT, tocPath)}`)
+    } else if (fs.existsSync(tocPath)) {
+      fs.unlinkSync(tocPath)
+    }
   } catch (err) {
     console.error(`Failed to render ${path.relative(ROOT, srcPath)}:`, err.message)
     process.exit(1)

website/src/components/doc-page.js

@@ -2,16 +2,28 @@ import { i18n } from '../i18n.js'
 import { hydrateYouTubeFacades } from '../utils/youtube-facade.js'
 
 /**
- * Render a documentation page shell (content loaded async)
+ * Render a documentation page shell (content loaded async).
+ *
+ * Layout: on `lg` and up, a sticky TOC sidebar sits to the left of the
+ * content. On smaller screens the aside stacks above the content. The
+ * aside stays hidden until loadDocContent fetches a TOC sidecar; pages
+ * without a TOC keep the full content width.
+ *
  * @returns {string} HTML string with loading placeholder
  */
 export function renderDocPage() {
   return `
     <main class="flex-1">
-      <div class="mx-auto max-w-4xl px-4 py-8 sm:px-6 lg:px-8">
-        <div id="doc-content" class="asciidoc-content">
-          <div class="flex items-center justify-center py-12">
-            <div class="animate-pulse text-gray-500 dark:text-gray-400">Loading...</div>
+      <div class="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
+        <div class="lg:flex lg:gap-8">
+          <aside
+            id="doc-toc"
+            class="doc-toc hidden mb-6 max-h-72 overflow-y-auto p-4 rounded-md border border-[var(--color-border)] bg-[var(--color-bg-secondary)] lg:mb-0 lg:w-64 lg:flex-shrink-0 lg:sticky lg:top-20 lg:self-start lg:max-h-[calc(100vh-6rem)] lg:p-0 lg:border-0 lg:rounded-none lg:bg-transparent"
+          ></aside>
+          <div id="doc-content" class="asciidoc-content min-w-0 lg:flex-1 lg:max-w-4xl">
+            <div class="flex items-center justify-center py-12">
+              <div class="animate-pulse text-gray-500 dark:text-gray-400">Loading...</div>
+            </div>
           </div>
         </div>
       </div>
@@ -33,11 +45,14 @@ export async function loadDocContent(docPath) {
 
   try {
     let response
+    let resolvedPath = htmlPath
 
     if (currentLang !== 'en') {
       const langPath = htmlPath.replace(/\.html$/, `.${currentLang}.html`)
       response = await fetch(`${import.meta.env.BASE_URL}${langPath}`)
-      if (!response.ok) {
+      if (response.ok) {
+        resolvedPath = langPath
+      } else {
         response = await fetch(`${import.meta.env.BASE_URL}${htmlPath}`)
       }
     } else {
@@ -48,6 +63,8 @@ export async function loadDocContent(docPath) {
       throw new Error(`Failed to load: ${response.status}`)
     }
 
+    await loadDocToc(resolvedPath)
+
     contentEl.innerHTML = await response.text()
 
     // Auto-expand collapsible sections
@@ -91,3 +108,44 @@ export async function loadDocContent(docPath) {
     `
   }
 }
+
+/**
+ * Fetch the TOC sidecar that render-docs.js extracts at build time and
+ * inject it into the #doc-toc aside. Pages without a TOC produce no
+ * sidecar — the fetch 404s and the aside stays hidden.
+ *
+ * Also rewrites the in-page hash links so they bypass the SPA router
+ * (which only handles `#/...` routes) and scroll to the target heading.
+ */
+async function loadDocToc(htmlPath) {
+  const aside = document.getElementById('doc-toc')
+  if (!aside) return
+
+  aside.innerHTML = ''
+  aside.classList.add('hidden')
+
+  const tocPath = htmlPath.replace(/\.html$/, '.toc.html')
+  try {
+    const tocResponse = await fetch(`${import.meta.env.BASE_URL}${tocPath}`)
+    if (!tocResponse.ok) return
+    const text = await tocResponse.text()
+    // Vite's SPA fallback returns index.html (200 OK) for missing files.
+    // Verify the response is actually a TOC fragment, not the SPA shell.
+    if (!/^\s*<div[^>]*\sid="toc"/i.test(text)) return
+    aside.innerHTML = text
+    aside.classList.remove('hidden')
+
+    aside.querySelectorAll('a[href^="#"]').forEach((link) => {
+      const href = link.getAttribute('href')
+      if (!href || href.startsWith('#/')) return
+      link.addEventListener('click', (e) => {
+        e.preventDefault()
+        const id = decodeURIComponent(href.slice(1))
+        const target = document.getElementById(id)
+        if (target) target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+      })
+    })
+  } catch {
+    // No TOC for this page — leave aside hidden.
+  }
+}

website/src/components/header.js

@@ -11,7 +11,7 @@ export function renderHeader() {
           <!-- Logo left, spanning both rows -->
           <div class="flex items-center">
             <a href="#/" class="no-underline flex flex-col items-center">
-              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" width="218" height="96" class="h-24 w-[218px]" />
+              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" width="218" height="96" class="h-24 w-[218px] max-w-none shrink-0" />
               <span class="text-xs text-[var(--color-text-secondary)] leading-tight" data-i18n="header.slogan">${i18n.t('header.slogan')}</span>
             </a>
             <button
@@ -101,7 +101,7 @@ export function renderHeader() {
         <div class="sm:hidden">
           <div class="flex flex-col items-center">
             <a href="#/" class="no-underline flex flex-col items-center">
-              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" width="145" height="64" class="h-16 w-[145px]" />
+              <img src="${import.meta.env.BASE_URL}logo.png" alt="Semantic Anchors" width="145" height="64" class="h-16 w-[145px] max-w-none shrink-0" />
               <span class="text-xs text-[var(--color-text-secondary)] leading-tight text-center" data-i18n="header.slogan">${i18n.t('header.slogan')}</span>
             </a>
             <div class="flex items-center gap-3 mt-2">

website/src/styles/asciidoctor-scoped.css

@@ -292,3 +292,58 @@
     border-color: #bf0000;
   }
 }
+
+/*
+ * Styles for the TOC sidebar that doc-page.js extracts from each rendered
+ * doc and injects into the #doc-toc aside. The TOC HTML keeps its
+ * asciidoctor-generated id/classes (#toc, #toctitle, ul.sectlevel1, ...).
+ * We do not reuse the body.toc2 fixed-position styles because the aside
+ * is already positioned by Tailwind classes on the doc-page shell.
+ */
+.doc-toc {
+  font-size: 0.875rem;
+  line-height: 1.5;
+  color: var(--color-text);
+}
+
+.doc-toc #toctitle {
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--color-text-secondary);
+  margin-bottom: 0.75rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.doc-toc ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.doc-toc ul ul {
+  padding-left: 0.875rem;
+  margin-top: 0.125rem;
+  margin-bottom: 0.25rem;
+  border-left: 1px solid var(--color-border);
+}
+
+.doc-toc li {
+  margin: 0.125rem 0;
+}
+
+.doc-toc a {
+  color: var(--color-text-secondary);
+  text-decoration: none;
+  display: block;
+  padding: 0.125rem 0.5rem;
+  border-radius: 0.25rem;
+  transition: color 0.15s, background-color 0.15s;
+}
+
+.doc-toc a:hover {
+  color: var(--color-text);
+  background-color: var(--color-bg-secondary);
+}