Anchor detail pages /anchor/<id> are HTTP 404s — invisible to search engines despite being advertised in sitemap and JSON-LD

[raifdmueller]

Problem

Every anchor detail URL (/anchor/<id>) returns HTTP 404. The page "works" only through the GitHub-Pages 404.html SPA fallback, which requires JavaScript and still carries the 404 status code.

This hurts SEO and AI discoverability threefold:

1. Search engines do not index 404s — the status code wins, regardless of what the fallback renders. None of the 161 anchors can rank individually.
2. sitemap.xml advertises all 161 URLs (priority 0.6) — crawlers are offered 161 dead links: wasted crawl budget, Search Console errors, a negative quality signal.
3. The DefinedTerm JSON-LD (feat: Extend JSON-LD — standalone Organization + DefinedTerm/DefinedTermSet markup for anchors #579/feat(seo): structured data (Organization + DefinedTermSet) and pre-render the article #592) points at these 404 URLs — "url": ".../anchor/<id>" on every term. The structured data we added for entity resolution references non-existent pages.

Shared deep links (social posts, the planned card QR codes) inherit the 404 as well.

Expected

Each anchor gets a real pre-rendered page at /anchor/<id>/index.html (HTTP 200) with its rendered content, own <title>, meta description, self-canonical URL — and a German variant under /de/anchor/<id> where a .de.adoc translation exists (155 of 161), with honest hreflang pairs.

With JavaScript, behavior is unchanged: the SPA hydrates and shows the anchor as a modal, exactly as today.

Why now

#596 built all the needed machinery (per-route applyHead, fragment rendering, hreflang/lang handling, the /de router rule — /de/anchor/<id> already resolves client-side). This is the follow-up flagged in that PR.

[raifdmueller]

Analysis

Building blocks already in place (from #595/#596)

• scripts/prerender-routes.js has applyHead() (title/description/canonical/hreflang/lang) and writeRouteVariant() (fragment → dist/<path>/index.html), both language-aware.
• The router resolves /de/anchor/<id> → German modal already (language-prefix rule from fix: make the website navigable and readable without JavaScript (EN + DE) #596).
• scripts/generate-jsonld.js#extractDescription() already derives a short description per anchor from the first Core-Concepts definition — reusable for the meta description.

Plan

1. Render fragments (scripts/render-docs.js): loop docs/anchors/*.adoc (160 EN + 155 DE) → website/public/docs/anchors/<id>(.de).html, same Asciidoctor options as the other docs. public/docs/ is gitignored and copied into dist/ by Vite.
2. Pre-render pages (scripts/prerender-routes.js): for every entry in anchors.json, write dist/anchor/<id>/index.html via writeRouteVariant() — title "<Anchor Title> — Semantic Anchors", description from extractDescription() (generic fallback), self-canonical; plus dist/de/anchor/<id>/index.html where the .de fragment exists, with hreflang pairs on both. Export extractDescription from generate-jsonld.js.
3. Home catalog links: the static catalog (fix: make the website navigable and readable without JavaScript (EN + DE) #596) currently links to /all-anchors#<id>; point it at /anchor/<id> instead (DE grid → /de/anchor/<id> where available) — real internal links onto the new pages.
4. Sitemap: the existing 161 /anchor/<id> entries become valid; add /de/anchor/<id> entries where the translation exists.
5. Version bump + changelog.

Non-changes

• JSON-LD DefinedTerm URLs stay as they are — they become honest once the pages exist.
• SPA behavior unchanged (boot → home + anchor modal, deep-linkable, Back closes).
• anchors.json has 161 entries but only 160 .adoc files — missing files are skipped with a build log line, not an error.

Verification

• Full build; assert dist/anchor/mece/index.html (200-served) contains rendered content, correct canonical, hreflang; dist/de/anchor/mece/index.html is German.
• Playwright javaScriptEnabled: false: open /anchor/mece/, content readable; JS run: same URL boots SPA with modal, no errors.
• Unit + E2E suites stay green.