Eleventy build: Support generating WCAG 2.1 docs from main branch

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,9 @@ import { basename } from "path";
 
 import type { GlobalData } from "eleventy.config";
 
-import { flattenDom, load } from "./cheerio";
+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";
 
@@ -61,7 +60,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 +88,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 +305,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 +406,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 +431,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 +501,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 +529,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
     });

11ty/README.md

@@ -49,12 +49,14 @@ 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.
+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.
 
-**Default:** `22`
+Possible values: `22` **(default)**, `21`
 
 ### `WCAG_MODE`
 

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,