Skip to content

Actualize counts, repair navigation, add four research articles - #25

Merged
AnastasiyaW merged 2 commits into
masterfrom
update/site/actualize-counts-and-indexes
Aug 28, 2026
Merged

Actualize counts, repair navigation, add four research articles#25
AnastasiyaW merged 2 commits into
masterfrom
update/site/actualize-counts-and-indexes

Conversation

@AnastasiyaW

Copy link
Copy Markdown
Owner

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 into stats.js.

before after
README / mkdocs.yml / AGENTS.md / welcome.md 847+ 851+
docs/index.md server-rendered fallback 785 851
GitHub repo description 785+ 851+
browse page header 771+ 851+
cross-references 3987+ (counted index pages too) 3344+ (wiki-links inside articles only)

The docs/index.md fallback mattered: stats.js overwrites it in the browser, so anything that does not run JS - crawlers, LLM scrapers - was reading a number 66 articles behind.

Navigation

  • 234 articles were linked from no domain index, and 438 were absent from the browse page. audio-voice, go, llm-memory and writing had no browse block at all.
  • The Image Generation block claimed 27 articles, listed 11 as plain text (not links), and the domain actually holds 77.
  • scripts/sync_indexes.py now 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.py orphans: 104 -> 0.

Ambiguous slugs

Seven slugs exist in more than one domain (error-handling in five, concurrency in three, and five others). hooks/wikilinks.py resolves [[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)

Article Domain
WinHTTP Asynchronous Client cpp
Three-State Check Aggregation testing-qa
Negative Controls for Verification testing-qa
Edge Softness and Compositing image-generation

The WinHTTP article is verified against winhttp.h from Windows SDK 10.0.26100.0 plus first-party documentation; the flag-expansion table is quoted from the header, not from memory.

Also

  • Language tags on the seven untagged code fences the build had been warning about.
  • generate_llms_txt.py strips wiki-link syntax from descriptions - 18 entries were carrying raw [[slug]] tokens into the LLM-facing index.
  • scripts/sync_stats.py propagates counts to all six hardcoded places; both stats rules now point at the scripts instead of a hand-edit checklist.
  • History row added to architecture/happyin-knowledge-space.md.

Verification

[stats] 851 articles across 26 domains
[validate] 878 articles checked, all clean
[link-checker] 881 files checked, all links OK
[public_check] Public files clean - no internal details leaked
mkdocs build --strict: Documentation built in 145.41 seconds
lint.py: orphans 0, broken_links 0, stale 0, too_short 0, empty 0
lint.link-check.py --strict: All links OK
hooks/freshness_check.py --ci: 0 issues, llms.txt in sync (851 URLs)

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.
@AnastasiyaW
AnastasiyaW merged commit 80b6852 into master Aug 28, 2026
4 checks passed
@AnastasiyaW
AnastasiyaW deleted the update/site/actualize-counts-and-indexes branch August 28, 2026 18:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant