feat(seo): pre-render the landing answer block for AI/search discoverability (#593)

The home page rendered its hero client-side, so crawlers and LLM fetchers saw
only the empty skeleton — the worst case for the query "What is Semantic
Anchors?". prerender-routes.js now fills the home #page-content with the hero
copy (title + definition + emphasis), single-sourced from the EN translations
so it never drifts from the live hero. The SPA overwrites #page-content with
the full interactive hero + card grid on boot, so users are unaffected; the
home is written separately so other routes keep their empty-skeleton assumption.

Implements the landing-block half of #580; the per-anchor answer-block sweep is
intentionally skipped — anchor definitions already ship crawlable via
/all-anchors.

Verified with a full build: the home #page-content carries the definition plus
the DefinedTermSet/Organization, and a control route (/about) neither leaks the
home block nor loses its own doc content.

Co-authored-by: Ralf D. Müller <ralf.d.mueller@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

docs/changelog.adoc

@@ -8,6 +8,7 @@ A chronological record of all semantic anchors added to the catalog. Community c
 
 * *Structured data* — added a standalone `Organization` entity and a `DefinedTermSet` with a `DefinedTerm` for every anchor (name, canonical URL, and a definition where available), generated at build time from `anchors.json`. Lets search engines and retrieval-grounded AI resolve "Semantic Anchors" as a distinct entity and each anchor as a defined term (#579).
 * *Fixed:* the _An Anchor Delivers Only as Far as the Prior Reaches_ article was not pre-rendered and was therefore invisible to search engines and LLM crawlers. It is now pre-rendered like every other doc page.
+* *Landing answer block* — the home page rendered its hero (the "what are Semantic Anchors?" definition) only client-side, so crawlers and LLM fetchers saw an empty shell. The hero copy is now pre-rendered into the static home page, single-sourced from the translations so it never drifts from the live hero (#580).
 
 == 2026-06-09
 

scripts/prerender-routes.js

@@ -264,7 +264,50 @@ function prerenderRoute(shell, route) {
 }
 
 /**
- * Entry point: read the shell once, then pre-render every route in ROUTES.
+ * Pre-render a crawlable "answer block" into the home page (dist/index.html).
+ *
+ * The landing page renders its hero client-side, so crawlers and LLM fetchers
+ * see only the empty skeleton — the worst case for the query "What is Semantic
+ * Anchors?". This fills the empty #page-content with the hero copy (title +
+ * definition + emphasis), single-sourced from the EN translations so it never
+ * drifts from the live hero. On boot the SPA's home route overwrites
+ * #page-content with the full interactive hero + card grid, so users are
+ * unaffected. See issue #580.
+ *
+ * Runs after the ROUTES loop and writes only dist/index.html, so the other
+ * routes (already written from the cached shell) keep their empty-skeleton
+ * assumption.
+ */
+function prerenderHome() {
+  const enPath = path.join(__dirname, '..', 'website', 'src', 'translations', 'en.json')
+  const en = JSON.parse(fs.readFileSync(enPath, 'utf-8'))
+  const title = en['hero.title'] || ''
+  const intro = en['hero.intro'] || ''
+  const emphasis = en['hero.introEmphasis'] || ''
+
+  const block = `
+      <section class="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
+        <h1 class="text-3xl sm:text-4xl font-bold mb-3 leading-tight">${escapeHtml(title)}</h1>
+        <p class="mb-2 max-w-3xl">${escapeHtml(intro)}</p>
+        <p class="font-semibold max-w-3xl">${escapeHtml(emphasis)}</p>
+      </section>
+    `
+
+  let html = fs.readFileSync(SHELL, 'utf-8')
+  const pageContentRegex = /(<div\s+id="page-content"[^>]*>)\s*(<\/div>)/
+  if (!pageContentRegex.test(html)) {
+    throw new Error(
+      'Home #page-content div not found (or not empty) in dist/index.html — cannot inject the landing answer block.'
+    )
+  }
+  html = html.replace(pageContentRegex, `$1${block}$2`)
+  fs.writeFileSync(SHELL, html, 'utf-8')
+  console.log('  ✓ pre-rendered / (home answer block)')
+}
+
+/**
+ * Entry point: read the shell once, then pre-render every route in ROUTES,
+ * plus a crawlable answer block on the home page.
  * Throws (via prerenderRoute) if any fragment is missing, so the build
  * fails non-zero instead of shipping an incomplete set of static pages.
  */
@@ -274,7 +317,8 @@ function main() {
     prerenderRoute(shell, route)
     console.log(`  ✓ pre-rendered ${route.path}`)
   }
-  console.log(`\n✓ Pre-rendered ${ROUTES.length} routes to dist/<route>/index.html`)
+  prerenderHome()
+  console.log(`\n✓ Pre-rendered ${ROUTES.length} routes + home to dist/<route>/index.html`)
 }
 
 main()