Actualize counts, repair navigation, add four research articles - #25
Merged
Conversation
Counts were stale everywhere and the browse page had drifted badly out of sync with what is actually in docs/. Stats (from hooks/stats.py, the same counter the build feeds to stats.js): - 847+ -> 851+ articles, 26 domains, in README / docs/index.md / mkdocs.yml / AGENTS.md / welcome.md / article-rules.md - docs/index.md carried a hardcoded fallback of 785 in the server-rendered HTML, so anything that does not run the stats.js overwrite (crawlers, LLM scrapers) read a number 66 articles behind - README per-domain table refreshed; cross-references recounted as 3344, now defined as wiki-links inside articles only (index pages and the browse page are navigation, not cross-references - the old 3987 counted them) Navigation: - 234 articles were linked from no domain index; 438 were absent from the browse page, and audio-voice / go / llm-memory / writing had no browse block at all - scripts/sync_indexes.py appends every unlinked article to its domain MOC and to the browse page, recomputes per-domain counts, converts the plain-text entries left in the Image Generation block into working wiki-links, and adds blocks for the four missing domains - 0 orphans remain; link-checker reports all links OK across 881 files New articles (4): - cpp/winhttp-async-client - progress vs completion notification flags, bounded waits, cancellation semantics; verified against winhttp.h from SDK 10.0.26100.0 - testing-qa/three-state-check-aggregation - PASS/FAIL/UNKNOWN, exit-code contracts, fail-closed rollup, absence-of-signal alarms - testing-qa/negative-controls-for-verification - proving a check can go red, hide-the-subject protocol, mutation testing, self-certifying proofs - image-generation/edge-softness-and-compositing - measured edge softness, robust outline fitting, rounded-corner SDF pitfalls, area-integrated minification, premultiplied resampling, coverage alpha Also: language tags on the seven untagged code fences the build was warning about, llms.txt and its five translations regenerated (851 URLs), and both stats rules now point at the scripts instead of a hand-edit checklist. Verified: mkdocs build --strict passes; validate reports 0 issues across 878 articles; public_check clean.
…criptions Follow-up to aad5ff7, found by running the repo's own lint.py. - 7 slugs exist in more than one domain (error-handling in five, concurrency in three, and five others). hooks/wikilinks.py resolves [[slug]] through a single global map and strips any domain prefix, so every reference landed on whichever file won the map - a Go index entry linked to the C++ article. 111 references in indexes and article bodies are now relative Markdown links pinned to their own domain; 2 genuinely cross-domain references are left as wiki-links. - [[ACE++]] never rendered as a link at all: the resolver refuses any slug containing '+', so three pages shipped a literal "[[ACE++]]" token to the live site. Replaced with Markdown links to docs/image-generation/ACE++.md. - generate_llms_txt.py now strips wiki-link syntax from descriptions; 18 entries in llms.txt carried raw [[slug]] tokens into the LLM-facing index. - History table in architecture/happyin-knowledge-space.md gets the 2026-08-28 row. lint.py orphans: 104 on master -> 0. broken_links 0, wiki-links all resolve, llms.txt in sync (851 URLs), mkdocs build --strict clean.
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
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.
What changed
Counts were stale in every hardcoded place, and the browse page had drifted far out of sync with
docs/.Stats
Source of truth is
hooks/stats.py- the same counter the build feeds intostats.js.docs/index.mdserver-rendered fallbackThe
docs/index.mdfallback mattered:stats.jsoverwrites it in the browser, so anything that does not run JS - crawlers, LLM scrapers - was reading a number 66 articles behind.Navigation
audio-voice,go,llm-memoryandwritinghad no browse block at all.scripts/sync_indexes.pynow appends every unlinked article to its domain MOC and to the browse page, recomputes per-domain counts, converts leftover plain-text entries into working links, and adds blocks for missing domains. Idempotent.lint.pyorphans: 104 -> 0.Ambiguous slugs
Seven slugs exist in more than one domain (
error-handlingin five,concurrencyin three, and five others).hooks/wikilinks.pyresolves[[slug]]through one global map and strips any domain prefix, so every reference landed on whichever file won the map - the Go index linked to the C++ article. 111 references are now relative Markdown links pinned to their own domain; 2 genuinely cross-domain ones stay as wiki-links.[[ACE++]]never rendered at all - the resolver refuses any slug containing+, so three pages shipped a literal[[ACE++]]token to the live site. Now Markdown links.New articles (4)
cpptesting-qatesting-qaimage-generationThe WinHTTP article is verified against
winhttp.hfrom Windows SDK 10.0.26100.0 plus first-party documentation; the flag-expansion table is quoted from the header, not from memory.Also
generate_llms_txt.pystrips wiki-link syntax from descriptions - 18 entries were carrying raw[[slug]]tokens into the LLM-facing index.scripts/sync_stats.pypropagates counts to all six hardcoded places; both stats rules now point at the scripts instead of a hand-edit checklist.architecture/happyin-knowledge-space.md.Verification