SEO optimizations - #1026
Merged
MDA2AV merged 4 commits intoJul 24, 2026
Merged
Conversation
Resolves the conflict GitHub reported against this PR. Nothing conflicted textually: the PR renames site/static/new-leaderboard/index.html to site/leaderboard/index.html while main modified it in place, and GitHub's mergeability check does not apply rename detection, so it reported the pair as a modify/delete conflict. `git merge-tree --write-tree` exits 0 and both merge directions are clean locally. Carries in the three changes main made to that file since this branch forked at 6bcf729: MDA2AV#1024 the Knowledge Base page search in the left menu (#navq, #navTree, buildSearchIndex) — note buildNav() now clears #navTree, not #nav MDA2AV#1025 the .tsq-* type square colours, which MDA2AV#1017 had deleted by way of a shared CSS line MDA2AV#1018 the type-rules "standard" attribute rename in the generator all of which land in the renamed file and the renamed generator.
Three things, all in service of this PR's goal of making the docs indexable.
1. Authored title + description for all 123 pages
The generator derived the meta description from each page's first <p>. That
opening line is often a cross-reference ("Same workload as JSON Processing,
but…"), which reads as boilerplate in a search result. Descriptions are now
authored in frontmatter; the scrape stays as the fallback for any page that
lacks one.
Titles were worse: 123 pages shared only 71 distinct titles, because 26 are
called "Implementation Guidelines" and 26 more "Validation". As <title> tags
those compete with each other for the same query, and a result reading just
"Validation" says nothing about which test it covers. A new `seo_title`
frontmatter key overrides the tag without touching the sidebar label, so
navigation still reads "Validation" while the page is titled "Baseline
Throughput Benchmark — Validation Checks".
Result: 123 unique titles, 123 unique descriptions, 81-153 characters each.
The SPA index page's own title and description are untouched.
2. The board's page search had been left indexing nothing
MDA2AV#1024 added Knowledge Base search to the left menu, built from window.LB_DOCS
— the docs.js blob. This PR stops generating docs.js, so LB_DOCS is always {}
and the search silently degraded to the 34 leaderboard views: no
documentation results at all, which is the exact complaint MDA2AV#970 was opened
about.
Reverting to docs.js would undo the payload win, so the generator now emits
search.js instead: the same pages as plain text, prepared server-side. It is
266 KB against docs.js's 427 KB, needs no client-side tag stripping, and each
entry carries the URL of its real page, so a hit navigates to /docs/<id>/
rather than rendering in place. The authored description is indexed too.
stripHtml() and docCrumb() go with it — both existed only to process the
retired HTML blob.
3. deploy.yml ships search.js alongside data.js.
Verified by regenerating: 123 static pages, 123 unique titles and
descriptions with no page over 160 characters, a 123-entry search index, and
a 124-URL sitemap.
Six merges landed since the last sync: MDA2AV#1030, MDA2AV#1031, MDA2AV#1032, MDA2AV#1033, MDA2AV#1034 and MDA2AV#1036. One real conflict, in the composite blurb, where both sides had changed the same line for different reasons: main (MDA2AV#1032) made the text state which normalization rule is active, so a screenshot can't be ambiguous about whether scores were rescaled to the current filter this branch pointed the "How it works" link at /docs/scoring/composite -score/ instead of the hash route Both are kept: MDA2AV#1032's wording with this branch's real URL. Everything else merged on its own, but the two structural ones were checked rather than assumed: MDA2AV#1034 moved results from 52 shared per-profile arrays to one file per framework. Git applied that to the renamed generator correctly — it still loads site/data/results/*.json and still emits 1941 rows, and compare.sh kept both its per-framework read and the --compare flag from MDA2AV#1031. MDA2AV#1030 added three echo-ws-limited doc pages after this branch's SEO pass, so they were written with seo_title/description already; all 126 pages now carry both. Generator output on the merged tree: 1941 rows, 126 static doc pages, a 126 -page search index and a 127-URL sitemap. All six workflows validate against a loader that rejects duplicate keys, which is what MDA2AV#1036 had to fix.
Kaliumhexacyanoferrat
marked this pull request as ready for review
July 24, 2026 21:33
MDA2AV
approved these changes
Jul 24, 2026
MDA2AV
added a commit
that referenced
this pull request
Jul 24, 2026
The Knowledge Base used to render inside the board, so it could not look different. #1026 split it into standalone pages and duplicated the chrome into Python string literals, and the two halves promptly drifted: the type-rules widget lost the rules that hide its inactive panels and showed Standard, Tuned and Engine stacked on all 27 implementation pages; the header lost its icon buttons, its Discord link and its RFC link; the disclosure marker turned into a control character. Each was fixed as its own symptom. The cause is that there were two copies. There is now one. board_chrome() reads site/leaderboard/index.html at build time and lifts out the brand block, the top-links block, and every stylesheet rule the two share - theme variables, reset, header, doc body, cards and the shortcode widgets. 78 of the 100 lines in the generated docs.css are now verbatim from the board; the remaining 22 are the standalone-page shell the board has no equivalent for (two-column layout, sidebar, its collapsible tree). Editing the board now updates the doc pages. Nothing can drift, because nothing is copied. It fails loudly rather than quietly: if the .brand or .top-links blocks or the <style> element can't be found, or fewer than 40 shared rules match, the generator exits with a message naming the file instead of emitting a half-styled site. One visible consequence beyond the fixes: the board's "sharp edges" reset is part of the shared set, so doc cards, tables and code blocks now have the same square corners as the board rather than the rounded ones the copy had.
MDA2AV
added a commit
that referenced
this pull request
Jul 24, 2026
…styling (#1039) * Collapse the Knowledge Base sidebar to the current page Every doc page rendered the whole tree expanded: 126 links in a 250px column with its own scrollbar, where the board next door shows a collapsible accordion. Getting anywhere in the Knowledge Base meant scrolling past every other page in the site. The nav is now <details>/<summary>, open only along the path to the page you are on — so the baseline validation page shows Test Profiles > H/1.1 > Isolated > Baseline expanded and the other 40-odd sections closed, about 30 visible links instead of 126. <details> was chosen over JavaScript because these pages exist to be crawled: the markup stays navigable with scripting off, and search engines still see every link. Also fixes the disclosure marker, which was rendering as a control character followed by "B8". _docs_css() is a plain triple-quoted string, not a raw one, so Python read the \25 in "\25B8" as an octal escape (0x15) and left "B8" as text — visible as garbage next to every collapsed section. It is now the literal character, which has no escaping ambiguity. Checked the generated stylesheet for any other control characters: none. * Style the shortcode widgets on the static doc pages The type-rules widget was rendering all three panels stacked with unstyled tab buttons on all 27 implementation pages. _doc_html() emits the same markup the board used — .type-rules-tab, .type-rules-panel, .tr-sq — but the rules that hide the inactive panels only ever existed in the board's inline stylesheet, so the static pages showed Standard, Tuned and Engine text one after another and the tabs did nothing visible. Same for the tabs widget (.doc-tabset / .doc-tab / .doc-tabpanel). Found by listing every class the generated pages actually emit and checking each against docs.css: nine widget classes were unstyled, all nine present in the board's CSS. The remaining unstyled ones are .language-* code-fence hints and bare .active, neither of which is styled anywhere including the board. This is the divergence the two stylesheets always risked: the widget markup and the widget styling live in different files, in different languages, and nothing tied them together. Copying the rules fixes it today; sharing one stylesheet between the board and the static pages would prevent the next one. * Give the doc pages the board's header instead of their own Crossing from / to /docs/ changed the chrome: the brand block lost its Timeline and RFC icon buttons, Timeline and GitHub became plain text links, Discord disappeared, and the theme control changed shape. It read as a different site because it was a different header — hand-written in Python, sharing nothing with the board beyond a couple of class names. The brand block and the top-links block are now lifted verbatim out of site/leaderboard/index.html into two constants, and the header CSS (.top, .brand, .brand-name, .icon-btn, .top-links) is the board's, copied rule for rule instead of approximated. Same markup, same classes, same icons, same sizes. What is deliberately not carried over: the type filter pills, the round selector and the hardware chips. Those are leaderboard state rather than site chrome, and none of them mean anything on a doc page. The brand link points at / rather than the SPA's in-page router, and the "Knowledge Base" label stays as the section marker. * Build the doc pages' chrome from the board instead of copying it The Knowledge Base used to render inside the board, so it could not look different. #1026 split it into standalone pages and duplicated the chrome into Python string literals, and the two halves promptly drifted: the type-rules widget lost the rules that hide its inactive panels and showed Standard, Tuned and Engine stacked on all 27 implementation pages; the header lost its icon buttons, its Discord link and its RFC link; the disclosure marker turned into a control character. Each was fixed as its own symptom. The cause is that there were two copies. There is now one. board_chrome() reads site/leaderboard/index.html at build time and lifts out the brand block, the top-links block, and every stylesheet rule the two share - theme variables, reset, header, doc body, cards and the shortcode widgets. 78 of the 100 lines in the generated docs.css are now verbatim from the board; the remaining 22 are the standalone-page shell the board has no equivalent for (two-column layout, sidebar, its collapsible tree). Editing the board now updates the doc pages. Nothing can drift, because nothing is copied. It fails loudly rather than quietly: if the .brand or .top-links blocks or the <style> element can't be found, or fewer than 40 shared rules match, the generator exits with a message naming the file instead of emitting a half-styled site. One visible consequence beyond the fixes: the board's "sharp edges" reset is part of the shared set, so doc cards, tables and code blocks now have the same square corners as the board rather than the rounded ones the copy had.
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
2 participants
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.
7 .fixing the sitemap
/leaderboard/Do not merge yet.