fix(docs): collapse the phone nav, and stop the header comment lying

Round 2 of review. Three notes and the mobile-nav call.

THE NAV, and the correction that prompted it. I had called the 25-link
sidebar wall pre-existing and declined to fix it. That was wrong: the entire
CSS is new in this PR, so the wall ships for the first time here and it is
mine. Every phone page opened on ~1500px of nav before any content.

The mechanism is a checkbox and not <details>, and the reason is measured
rather than assumed. <details> was the obvious control, and it collapses
correctly on a phone -- but the sidebar layout has to force it OPEN, and a
closed <details> hides its content through ::details-content, which `display`
cannot override. Chromium showed the desktop sidebar collapsed to one link
with its toggle hidden: unusable. So the hiding is ours, in a media query,
where overriding it is just cascade.

Measured at both widths: 390px shows 1 link and the toggle, with the h1 at
189px instead of ~1500; 1280px shows all 26 links with no toggle and the h1
at 40px, unchanged; and the phone toggle really expands 1 -> 26 on click.
Note the first probe was wrong -- getBoundingClientRect reports a height for
content-visibility-hidden children, so it read 26 visible in both states and
would have passed the broken version. checkVisibility() is what separates them.

The same argument applies to the table of contents, which is equally new
here: repo-map opened on 1397px of TOC on a phone. Capped at 45vh so it
scrolls; 1397 -> 924, desktop identical at 652.

THE HEADER COMMENT. The generator stopped running standalone when the link
check began resolving ../index.html and ../app/ on disk, and its header still
advertised a default OUT_DIR that now exits 1. That is gotcha 48's third
paragraph exactly -- a fact stated in two places and updated in one, with the
copy that was updated being doc-site.md and the copy someone about to run the
script actually reads being the header. It now says so, keeps the strictness
(the hole it replaced was counting those links as checked while skipping
them), and records the other thing the reorder changed: the DIRECTION of a
failure, from an obviously-broken tree with no app/ to a complete-looking one
with a partial docs/.

And one documented subset: a \| inside a code span in a table cell keeps its
backslash where GFM would unescape it. Splitting is suppressed inside code
spans, so the escape is never needed there and never consumed. No corpus
instance; recorded as a decision rather than left to be rediscovered.

Gates: 1378 rust, 26 node --test, 16 playwright (3 skipped, webkit OPFS), all
three check-comment-runs modes, 3460 site links / 0 broken, 0 nested anchors,
0 of 23 pages overflow at 390 and 1280.

improvise-djoo

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Edward Langley
2026-09-20 14:04:19 -07:00
parent 1a0f04856e
commit 41f694f535
2 changed files with 27 additions and 2 deletions
+6
View File
@@ -188,6 +188,12 @@ been shredded into extra columns — a row that still parses, so no column count
could detect it. It was latent when fixed, which is the point: the trigger is
one ordinary sentence away in a document whose subject is pipe quoting.
One deliberate divergence from GFM inside that rule: a `\|` **inside a code
span** in a table cell keeps its backslash, where GFM would unescape it to a
bare pipe. Splitting is suppressed inside code spans, so the escape is never
needed there and never consumed. The corpus contains no instance; it is
recorded as a decision rather than left to be rediscovered as a bug.
## 6. Navigation
`repo-map.md` is one long document whose gotcha list is numbered 1 to 48, and