Add build support for linking to bibliographical references

11ty/CustomLiquid.ts

@@ -8,6 +8,7 @@ import { basename } from "path";
 
 import type { GlobalData } from "eleventy.config";
 
+import { biblioPattern, getBiblio } from "./biblio";
 import { flattenDom, load } from "./cheerio";
 import { generateId } from "./common";
 import { getTermsMap } from "./guidelines";
@@ -21,6 +22,7 @@ const indexPattern = /(techniques|understanding)\/(index|about)\.html$/;
 const techniquesPattern = /\btechniques\//;
 const understandingPattern = /\bunderstanding\//;
 
+const biblio = await getBiblio();
 const termsMap = await getTermsMap();
 const termLinkSelector = "a:not([href])";
 
@@ -89,7 +91,7 @@ export class CustomLiquid extends Liquid {
       const isIndex = indexPattern.test(filepath);
       const isTechniques = techniquesPattern.test(filepath);
       const isUnderstanding = understandingPattern.test(filepath);
-      
+
       if (!isTechniques && !isUnderstanding) return super.parse(html);
 
       const $ = flattenDom(html, filepath);
@@ -507,7 +509,7 @@ export class CustomLiquid extends Liquid {
 				<p>${$el.html()}</p>
 			</div>`);
     });
-    
+
     // Add header to example sections in Key Terms (aside) and Conformance (div)
     $("aside.example, div.example").each((_, el) => {
       const $el = $(el);
@@ -540,6 +542,21 @@ export class CustomLiquid extends Liquid {
       });
     }
 
+    // Link biblio references
+    if (scope.isUnderstanding) {
+      $("p").each((_, el) => {
+        const $el = $(el);
+        const html = $el.html();
+        if (html && biblioPattern.test(html)) {
+          $el.html(
+            html.replace(biblioPattern, (substring, code) =>
+              biblio[code]?.href ? `[<a href="${biblio[code].href}">${code}</a>]` : substring
+            )
+          );
+        }
+      });
+    }
+
     // Allow autogenerating missing top-level section IDs in understanding docs,
     // but don't pick up incorrectly-nested sections in some techniques pages (e.g. H91)
     const sectionSelector = scope.isUnderstanding ? "section" : "section[id]:not(.obsolete)";

11ty/biblio.ts

@@ -0,0 +1,35 @@
+import axios from "axios";
+import { readFile } from "fs/promises";
+import { glob } from "glob";
+import uniq from "lodash-es/uniq";
+
+export const biblioPattern = /\[\[([\w-]+)\]\]/g;
+
+/** Compiles URLs from local biblio + specref for linking in Understanding documents. */
+export async function getBiblio() {
+  const localBiblio = eval(
+    (await readFile("biblio.js", "utf8"))
+      .replace(/^respecConfig\.localBiblio\s*=\s*/, "(")
+      .replace("};", "})")
+  );
+
+  const refs: string[] = [];
+  for (const path of await glob(["guidelines/**/*.html", "understanding/*/*.html"])) {
+    const content = await readFile(path, "utf8");
+    let match;
+    while ((match = biblioPattern.exec(content))) if (!localBiblio[match[1]]) refs.push(match[1]);
+  }
+  const uniqueRefs = uniq(refs);
+
+  const response = await axios.get(`https://api.specref.org/bibrefs?refs=${uniqueRefs.join(",")}`);
+  const fullBiblio = {
+    ...response.data,
+    ...localBiblio,
+  };
+
+  const resolvedRefs = Object.keys(fullBiblio);
+  const unresolvedRefs = uniqueRefs.filter((ref) => !resolvedRefs.includes(ref));
+  if (unresolvedRefs.length) console.warn(`Unresolved biblio refs: ${unresolvedRefs.join(", ")}`);
+
+  return fullBiblio;
+}

package.json

@@ -15,6 +15,7 @@
   "license": "W3C",
   "dependencies": {
     "@11ty/eleventy": "^3.0.0",
+    "axios": "^1.7.7",
     "cheerio": "^1.0.0",
     "glob": "^10.3.16",
     "gray-matter": "^4.0.3",