docs: assemble the generated API references at build time

package.json

@@ -14,7 +14,9 @@
     "test:integration": "vitest run src/__tests__",
     "migrate-data": "node scripts/migrate-data.mjs",
     "patch-content": "node scripts/patch-content.mjs",
-    "links": "lychee --config lychee.toml --root-dir \"$(pwd)/dist\" 'dist/**/*.html'"
+    "links": "lychee --config lychee.toml --root-dir \"$(pwd)/dist\" 'dist/**/*.html'",
+    "prebuild": "node scripts/fetch-api-reference.mjs",
+    "fetch:api": "node scripts/fetch-api-reference.mjs"
   },
   "dependencies": {
     "@astrojs/mdx": "^7.0.2",
@@ -46,4 +48,4 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }
-}
+}

scripts/fetch-api-reference.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Fetches the generated API references from the pubid repos (pubid#577)
+// into the content collection at build time, so the website assembles
+// the library reference without committing generated files. Pinned to
+// each repo's main; raw.githubusercontent serves the branch head.
+import { writeFileSync, mkdirSync } from "node:fs";
+
+const SOURCES = [
+  {
+    repo: "pubid/pubid",
+    file: "docs/api-reference.md",
+    out: "src/content/library/api-reference-ruby.md",
+    title: "API Reference — Ruby (pubid)",
+    description: "Generated from YARD over the pubid gem sources.",
+  },
+  {
+    repo: "pubid/pubid-ts",
+    file: "docs/api-reference.md",
+    out: "src/content/library/api-reference-ts.md",
+    title: "API Reference — TypeScript (pubid-ts)",
+    description: "Generated from TypeDoc over the pubid-ts sources.",
+  },
+];
+
+const frontmatter = (title, description) => `---
+title: "${title}"
+description: "${description}"
+---
+
+`;
+
+mkdirSync("src/content/library", { recursive: true });
+for (const { repo, file, out, title, description } of SOURCES) {
+  const url = `https://raw.githubusercontent.com/${repo}/main/${file}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(`${url}: ${res.status}`);
+    process.exit(1);
+  }
+  const body = await res.text();
+  writeFileSync(out, frontmatter(title, description) + body);
+  console.log(`${out}: ${body.split("\n").length} lines from ${repo}@main`);
+}

src/content/library/api.md

@@ -133,20 +133,14 @@ For example, ISO has:
 - `Pubid::Iso::Identifiers::Amendment`
 - etc.
 
-## Registry
+## Full Reference (generated)
 
-The `Pubid::IdentifierRegistry` provides lookup capabilities:
+The complete, generated references — every public entry point with its
+signature and docstring — are built from the sources themselves and
+cannot drift from the code (CI regenerates them on every change):
 
-```ruby
-# Find by flavor and type
-Pubid::IdentifierRegistry.find_by_type(:iso, :is)
-
-# Get all identifiers for a flavor
-Pubid::IdentifierRegistry.all_for_flavor(:iso)
-
-# Export as JSON
-Pubid::IdentifierRegistry.to_json
-```
+- [Ruby — the pubid gem (YARD)](/library/api-reference-ruby/)
+- [TypeScript — pubid-ts (TypeDoc)](/library/api-reference-ts/)
 
 ## See Also