Merge branch 'main' into F103

.github/workflows/11ty-publish.yaml

@@ -1,4 +1,4 @@
-name: CI
+name: Push to gh-pages branch
 
 # Reference documentation: https://docs.github.com/en/actions/reference
 

11ty/CustomLiquid.ts

@@ -1,4 +1,3 @@
-import type { Cheerio, Element } from "cheerio";
 import { Liquid, type Template } from "liquidjs";
 import type { RenderOptions } from "liquidjs/dist/liquid-options";
 import compact from "lodash-es/compact";
@@ -8,9 +7,10 @@ import { basename } from "path";
 
 import type { GlobalData } from "eleventy.config";
 
-import { flattenDom, load } from "./cheerio";
+import { biblioPattern, getBiblio } from "./biblio";
+import { flattenDom, load, type CheerioAnyNode } from "./cheerio";
 import { generateId } from "./common";
-import { getTermsMap } from "./guidelines";
+import { getAcknowledgementsForVersion, getTermsMap } from "./guidelines";
 import { resolveTechniqueIdFromHref, understandingToTechniqueLinkSelector } from "./techniques";
 import { techniqueToUnderstandingLinkSelector } from "./understanding";
 
@@ -21,6 +21,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])";
 
@@ -61,7 +62,7 @@ const normalizeTocLabel = (label: string) =>
  * expand to a link with the full technique ID and title.
  * @param $el a $()-wrapped link element
  */
-function expandTechniqueLink($el: Cheerio<Element>) {
+function expandTechniqueLink($el: CheerioAnyNode) {
   const href = $el.attr("href");
   if (!href) throw new Error("expandTechniqueLink: non-link element encountered");
   const id = resolveTechniqueIdFromHref(href);
@@ -89,7 +90,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);
@@ -306,6 +307,14 @@ export class CustomLiquid extends Liquid {
     if (indexPattern.test(scope.page.inputPath)) {
       // Remove empty list items due to obsolete technique link removal
       if (scope.isTechniques) $("ul.toc-wcag-docs li:empty").remove();
+
+      // Replace acknowledgements with pinned content for older versions
+      if (process.env.WCAG_VERSION && $("section#acknowledgements").length) {
+        const pinnedAcknowledgements = await getAcknowledgementsForVersion(scope.version);
+        for (const [id, content] of Object.entries(pinnedAcknowledgements)) {
+          $(`#${id} h3 +`).html(content);
+        }
+      }
     } else {
       const $title = $("title");
 
@@ -399,7 +408,7 @@ export class CustomLiquid extends Liquid {
       // Process defined terms within #render,
       // where we have access to global data and the about box's HTML
       const $termLinks = $(termLinkSelector);
-      const extractTermName = ($el: Cheerio<Element>) => {
+      const extractTermName = ($el: CheerioAnyNode) => {
         const name = $el
           .text()
           .toLowerCase()
@@ -424,7 +433,7 @@ export class CustomLiquid extends Liquid {
         });
       } else if (scope.isUnderstanding) {
         const $termsList = $("section#key-terms dl");
-        const extractTermNames = ($links: Cheerio<Element>) =>
+        const extractTermNames = ($links: CheerioAnyNode) =>
           compact(uniq($links.toArray().map((el) => extractTermName($(el)))));
 
         if ($termLinks.length) {
@@ -494,20 +503,22 @@ export class CustomLiquid extends Liquid {
     // (This is also needed for techniques/about)
     $("div.note").each((_, el) => {
       const $el = $(el);
-      $el.replaceWith(`<div class="note">
+      const classes = el.attribs.class;
+      $el.replaceWith(`<div class="${classes}">
 				<p class="note-title marker">Note</p>
 				<div>${$el.html()}</div>
 			</div>`);
     });
     // Handle p variant after div (the reverse would double-process)
     $("p.note").each((_, el) => {
       const $el = $(el);
-      $el.replaceWith(`<div class="note">
+      const classes = el.attribs.class;
+      $el.replaceWith(`<div class="${classes}">
 				<p class="note-title marker">Note</p>
 				<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);
@@ -520,13 +531,19 @@ export class CustomLiquid extends Liquid {
     // Handle new-in-version content
     $("[class^='wcag']").each((_, el) => {
       // Just like the XSLT process, this naively assumes that version numbers are the same length
-      const classVersion = +el.attribs.class.replace(/^wcag/, "");
-      const buildVersion = +scope.version;
+      const classMatch = el.attribs.class.match(/\bwcag(\d\d)\b/);
+      if (!classMatch) throw new Error(`Invalid wcagXY class found: ${el.attribs.class}`);
+      const classVersion = +classMatch[1];
       if (isNaN(classVersion)) throw new Error(`Invalid wcagXY class found: ${el.attribs.class}`);
+      const buildVersion = +scope.version;
+
       if (classVersion > buildVersion) {
         $(el).remove();
       } else if (classVersion === buildVersion) {
-        $(el).prepend(`<span class="new-version">New in WCAG ${scope.versionDecimal}: </span>`);
+        if (/\bnote\b/.test(el.attribs.class))
+          $(el).find(".marker").append(` (new in WCAG ${scope.versionDecimal})`);
+        else
+          $(el).prepend(`<span class="new-version">New in WCAG ${scope.versionDecimal}: </span>`);
       }
       // Output as-is if content pertains to a version older than what's being built
     });
@@ -540,6 +557,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/README.md

@@ -49,12 +49,17 @@ but may be useful if you're not seeing what you expect in the output files.
 
 ### `WCAG_VERSION`
 
-**Usage context:** currently this should not be changed, pending future improvements to `21` support
+**Usage context:** for building older versions of techniques and understanding docs
 
 Indicates WCAG version being built, in `XY` format (i.e. no `.`).
-Influences base URLs for links to guidelines, techniques, and understanding pages.
-
-**Default:** `22`
+Influences which pages get included, guideline/SC content,
+and a few details within pages (e.g. titles/URLs, "New in ..." content).
+Also influences base URLs for links to guidelines, techniques, and understanding pages.
+Explicitly setting this causes the build to reference guidelines and acknowledgements
+published under `w3.org/TR/WCAG{version}`, rather than using the local checkout
+(which is effectively the 2.2 Editors' Draft).
+
+Possible values: `22`, `21`
 
 ### `WCAG_MODE`
 

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;
+}

11ty/cheerio.ts

@@ -5,6 +5,9 @@ import { dirname, resolve } from "path";
 
 export { load } from "cheerio";
 
+/** Superset of the type returned by any Cheerio $() call. */
+export type CheerioAnyNode = ReturnType<ReturnType<typeof load>>;
+
 /** Convenience function that combines readFile and load. */
 export const loadFromFile = async (
   inputPath: string,