docs: notation stays on the rule page and leaves every nav - #229
Merged
Merged
Conversation
`evaluation.md`'s heading is "J1. Expression evaluation `Γ, H ⊢ e ⇓ v`" and `verdict.md`'s is "J2. Per-file verdict `B, ι ⊢ f ⇓ fold(X, L) | run(reason)`". `sync-spec.mjs` took the H1 verbatim as the page title, so the judgment form reached the sidebar of every specification page, the browser tab, and any link somebody sends a colleague. It belongs at the top of the rule file. It does not belong in a list of page names, where a reader who has not met it has nothing to do with it and no gloss in reach. Hugo has exactly this distinction. `sync-spec.mjs` emits a `linkTitle` with the trailing code span stripped, and everywhere a page is listed or linked by name uses it: the sidebar, section listings, the breadcrumb's parent, and the `<title>` element. The page's own `<h1>` keeps the full heading, so the judgment form is the first thing on the page it belongs to. A tab now reads "J2. Per-file verdict · typescript-as-data" rather than carrying the whole judgment. Across every rendered page on the site there are no notation characters left in any nav. The readability gate does not cover this and still does not: it reads markdown sources, and a title is generated into frontmatter from a heading. The check here was the rendered HTML. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AzfJnYw9p6rAxhJqXK3CPv
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-on from #228. The sidebar was the gap I flagged when that merged.
The problem
sync-spec.mjstook each rule file's H1 verbatim as the page title:J1. Expression evaluation \Γ, H ⊢ e ⇓ v``J2. Per-file verdict \B, ι ⊢ f ⇓ fold(X, L) | run(reason)``So the judgment form reached the sidebar of every specification page, the browser tab, and any link someone sends a colleague. A tab read
J2. Per-file verdict \B, ι ⊢ f ⇓ fold(X, L) | run(reason)` · typescript-as-data`.That form belongs at the top of the rule file. It does not belong in a list of page names, where a reader has nothing to do with it and no gloss within reach.
The fix
Hugo already has this distinction.
sync-spec.mjsemitslinkTitlewith the trailing code span stripped, and every place a page is listed or linked by name uses it:<title>elementThe page's own
<h1>keepstitle, so the judgment form is still the first thing on the page it belongs to.Verified against rendered HTML
And across every rendered page on the site: 0 notation characters in any nav.
Worth knowing
The readability gate from #228 does not cover this and still doesn't. It reads markdown sources, and these titles are generated into frontmatter from a heading — so the source it would scan is
spec/evaluation.md, where the notation is correct. Catching it needed the rendered output.I've left that as-is rather than extending the gate to parse HTML, but it's a real blind spot if more generated frontmatter appears.
Verification
124 tests in 20 files, prose lint 51 with no regressions,
npm run docs:buildclean.🤖 Generated with Claude Code
https://claude.ai/code/session_01AzfJnYw9p6rAxhJqXK3CPv