Runbook: In-page “On this page” sidebar missing or empty

Trigger

• A long HTML page under docs/ (not docs/api/) has no “On this page” list, or the list is empty.
• You expect a main column plus a right-hand (or stacked) table of contents from docs/assets/docs-nav.js.

Fast triage

1. The page loads <script defer src="…/assets/docs-nav.js"></script> (Network tab: no 404 for docs-nav.js).
2. JavaScript is on. For file:// URLs some browsers block scripts; use a small server, e.g. cd docs && python -m http.server 8765.
3. Console: no errors from docs-nav.js before the layout runs.
4. After load, <div id="docs-top-nav"> still exists (the script fills it; it should not disappear). It should contain <nav class="top-nav">.
5. The page uses <main class="container"> and <div id="docs-top-nav">; the script can add the TOC mount for you.

Most common causes

• Wrong page shell — Auto TOC needs <main class="container"> and #docs-top-nav.
• No headings — TOC lists h2/h3 (adds id if missing). p.lead is not listed.
• Broken markup — The script sets id from heading text; bad HTML around a heading can hide it.
• Diagram headings — h3 inside figure.sys-diagram / .sys-diagram is skipped.
• Long list — Many headings still use one mount; the sidebar scrolls. To hide the sidebar on one page, remove that page’s mount only.
• Two TOCs — Old Contents blocks are removed by docs-nav.js; keep only the generated “On this page”.

Recovery steps

1. Ensure page shell is correct: <main class="container"> with <div id="docs-top-nav"></div> near the top (see Documentation pipeline → In-page “On this page” sidebar).
2. Ensure each section you want in the TOC has an h2 or h3 with a stable id (or let the script generate one from heading text).
3. Use clear h2/h3 structure. Cards do not change which headings appear.
4. Run make docs-fix so HTML normalization stays consistent, then make docs-check.

Exit criteria

• “On this page” lists the right sections; the active link updates as you scroll.
• No console errors from docs-nav.js on that page.

Page history