Merge pull request #1004 from nteract/render-docs

Docs build: emit route JSON and prerender notes

Author: emeeks

docs/README.md

@@ -22,7 +22,7 @@ Build the production site:
 npm run website:build
 ```
 
-The Parcel website target uses `docs/public/index.html` as its source and writes the built site to `docs/build`.
+The Parcel website target uses `docs/public/index.html` as its source and writes the built site to `docs/build`. After Parcel emits the interactive SPA bundle, `scripts/prerender.mjs` creates one HTML file per route and embeds sanitized, route-specific machine-readable content in each page's `<noscript>` fallback. It also writes `docs/build/llms-routes.json`, a structured manifest with route text, headings, code blocks, and links for agents that prefer JSON over HTML.
 
 ## Current Structure
 
@@ -91,6 +91,7 @@ Some documentation artifacts are generated or synchronized from source files:
 
 - API JSON and component descriptions come from `npm run docs:api:json`.
 - AI behavior contract sections are checked with `npm run check:ai-contracts` and regenerated with `npm run docs:ai-contracts`.
+- Route-level machine-readable HTML and `llms-routes.json` are generated by `npm run website:build` after the Parcel docs build.
 - `CLAUDE.md` is the primary assistant instruction source and is synced into other AI instruction files during the build pipeline.
 
 Avoid hand-editing generated output unless the corresponding source cannot reasonably be updated.

docs/public/assets/gifs/incident-replay.gif

@@ -5,19 +5,19 @@
   <link rel="self" type="application/atom+xml" href="https://semiotic3.nteract.io/blog/feed.xml"/>
   <link rel="alternate" type="text/html" href="https://semiotic3.nteract.io/blog"/>
   <id>https://semiotic3.nteract.io/blog/</id>
-  <updated>2026-06-08T00:00:00Z</updated>
+  <updated>2026-06-07T00:00:00Z</updated>
   <author><name>Semiotic</name></author>
   <entry>
-    <title>Annotations That Adapt and Travel</title>
-    <id>https://semiotic3.nteract.io/blog/annotations-that-adapt-and-travel</id>
-    <link rel="alternate" type="text/html" href="https://semiotic3.nteract.io/blog/annotations-that-adapt-and-travel"/>
-    <link rel="enclosure" type="image/png" href="https://semiotic3.nteract.io/blog/og/annotations-that-adapt-and-travel.png"/>
-    <published>2026-06-08T00:00:00Z</published>
-    <updated>2026-06-08T00:00:00Z</updated>
+    <title>Annotations That Lead and Land</title>
+    <id>https://semiotic3.nteract.io/blog/annotations-that-lead-and-land</id>
+    <link rel="alternate" type="text/html" href="https://semiotic3.nteract.io/blog/annotations-that-lead-and-land"/>
+    <link rel="enclosure" type="image/png" href="https://semiotic3.nteract.io/blog/og/annotations-that-lead-and-land.png"/>
+    <published>2026-06-07T00:00:00Z</published>
+    <updated>2026-06-07T00:00:00Z</updated>
     <author><name>Elijah Meeks</name></author>
     <category term="case-study"/>
     <category term="roadmap"/>
-    <summary type="text">Placement (M2) and density (M3) decided where notes land and how many fit. M5 makes that adapt to space and house style. It sheds secondary notes as the plot narrows, and chooses whether notes blend into the chart or read as a distinct editorial layer. M6 adapts to the reader and to reuse: scale annotation amount by audience familiarity, and mark a note defensive so it survives every export with its source and confidence baked in.</summary>
+    <summary type="text">Semiotic already treated annotations as data-bound objects. Now it helps authors make design decisions with those objects: primary and secondary notes, inferred reading order from confidence, an accessibility audit hook, and an opt-in annotationLayout recipe that places notes near their targets while avoiding obvious collisions.</summary>
   </entry>
   <entry>
     <title>Semiotic 3.7.0</title>

docs/public/blog/feed.xml

@@ -10,10 +10,16 @@ export interface RequiredApiAsset {
   description: string
 }
 
+export interface RequiredMachineReadableRoute {
+  routePath: string
+  keyword: string
+}
+
 export interface DocsBuildValidationOptions {
   buildDir?: string
   routes?: RequiredDocsRoute[]
   apiAssets?: RequiredApiAsset[]
+  machineReadableRoutes?: RequiredMachineReadableRoute[]
 }
 
 export interface DocsBuildValidationResult {
@@ -25,6 +31,8 @@ export const REQUIRED_DOCS_ROUTES: RequiredDocsRoute[]
 
 export const REQUIRED_API_ASSETS: RequiredApiAsset[]
 
+export const REQUIRED_MACHINE_READABLE_ROUTES: RequiredMachineReadableRoute[]
+
 export function routeHtmlPath(buildDir: string, routePath: string): string
 
 export function validateDocsBuild(options?: DocsBuildValidationOptions): DocsBuildValidationResult

docs/public/ssr-gallery.html

@@ -54,6 +54,25 @@ export const REQUIRED_API_ASSETS = [
   },
 ]
 
+export const REQUIRED_MACHINE_READABLE_ROUTES = [
+  {
+    routePath: "",
+    keyword: "Streaming-First Visualization for React",
+  },
+  {
+    routePath: "getting-started",
+    keyword: "streaming-first visualization library",
+  },
+  {
+    routePath: "charts/line-chart",
+    keyword: "LineChart",
+  },
+  {
+    routePath: "blog/release-3-7-0",
+    keyword: "receivability release",
+  },
+]
+
 export function routeHtmlPath(buildDir, routePath) {
   return routePath ? resolve(buildDir, routePath, "index.html") : resolve(buildDir, "index.html")
 }
@@ -62,6 +81,7 @@ export function validateDocsBuild({
   buildDir = DEFAULT_BUILD_DIR,
   routes = REQUIRED_DOCS_ROUTES,
   apiAssets = REQUIRED_API_ASSETS,
+  machineReadableRoutes = REQUIRED_MACHINE_READABLE_ROUTES,
 } = {}) {
   const failures = []
 
@@ -81,6 +101,52 @@ export function validateDocsBuild({
     expectIncludes(failures, html, "AI / Machine-readable docs", route.routePath, "noscript AI docs fallback")
   }
 
+  const manifestPath = resolve(buildDir, "llms-routes.json")
+  let routeDocs = []
+  if (!existsSync(manifestPath)) {
+    failures.push(`Missing machine-readable route manifest at ${manifestPath}`)
+  } else {
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"))
+      routeDocs = Array.isArray(manifest.routes) ? manifest.routes : []
+      if (routeDocs.length === 0) {
+        failures.push(`Machine-readable route manifest has no routes at ${manifestPath}`)
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      failures.push(`Could not parse machine-readable route manifest at ${manifestPath}: ${message}`)
+    }
+  }
+
+  for (const route of machineReadableRoutes) {
+    const filePath = routeHtmlPath(buildDir, route.routePath)
+    if (!existsSync(filePath)) {
+      failures.push(`Missing machine-readable route HTML ${route.routePath || "/"} at ${filePath}`)
+      continue
+    }
+
+    const html = readFileSync(filePath, "utf8")
+    expectIncludes(failures, html, 'id="semiotic-route-doc"', route.routePath, "route JSON doc")
+    expectIncludes(failures, html, 'id="machine-readable-page"', route.routePath, "machine-readable noscript content")
+    expectIncludes(failures, html, route.keyword, route.routePath, "machine-readable keyword")
+
+    const routeKey = route.routePath || "/"
+    const routeDoc = routeDocs.find((doc) => doc?.route === routeKey)
+    if (!routeDoc) {
+      failures.push(`Missing ${routeKey} in llms-routes.json`)
+      continue
+    }
+    if (typeof routeDoc.text !== "string" || routeDoc.text.length < 200) {
+      failures.push(`Machine-readable text for ${routeKey} is too short in llms-routes.json`)
+    }
+    if (!routeDoc.text?.includes(route.keyword)) {
+      failures.push(`Machine-readable text for ${routeKey} is missing keyword: ${route.keyword}`)
+    }
+    if (!Array.isArray(routeDoc.headings) || routeDoc.headings.length === 0) {
+      failures.push(`Machine-readable headings for ${routeKey} are missing in llms-routes.json`)
+    }
+  }
+
   for (const asset of apiAssets) {
     const filePath = resolve(buildDir, asset.path)
     if (!existsSync(filePath)) {
@@ -131,5 +197,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     process.exit(1)
   }
 
-  console.log(`✅ docs route smoke check passed (${REQUIRED_DOCS_ROUTES.length} routes, ${REQUIRED_API_ASSETS.length} API assets)`)
+  console.log(
+    `✅ docs route smoke check passed (${REQUIRED_DOCS_ROUTES.length} routes, ${REQUIRED_API_ASSETS.length} API assets, ${REQUIRED_MACHINE_READABLE_ROUTES.length} machine-readable routes)`
+  )
 }

scripts/check-docs-routes.d.mts

@@ -14,10 +14,23 @@ export interface BlogEntryMeta {
   tags?: string[]
 }
 
+export interface MachineReadableRouteDoc {
+  route: string
+  url: string
+  html: string
+  text: string
+  headings?: Array<{ level: number; text: string }>
+  codeBlocks?: string[]
+  links?: Array<{ text: string; href: string }>
+}
+
 export function generatePage(
   shellHtml: string,
   routePath: string,
-  blogMeta?: BlogEntryMeta | null
+  blogMeta?: BlogEntryMeta | null,
+  machineDoc?: MachineReadableRouteDoc | null
 ): string
 
+export function sanitizeRouteHtml(renderedHtml: string, routePath: string): MachineReadableRouteDoc | null
+
 export function prerender(): Promise<void>