Allow running builds against a custom local guidelines folder (#4182)

This adds logic to `getPrinciples` and `getTermsMap` code flows to allow
explicitly specifying a local `guidelines/index.html` path when building
for a specific version, to be used in place of requesting the latest
published recommendation for the specified `WCAG_VERSION`. This allows
us to directly reuse the build process from the `main` branch for
generating preview builds against `WCAG-2.1`, rather than needing to
copy the entire Eleventy build process to that branch and keep it in
sync.

11ty/README.md

@@ -49,18 +49,33 @@ but may be useful if you're not seeing what you expect in the output files.
 
 ### `WCAG_VERSION`
 
-**Usage context:** for building older versions of techniques and understanding docs
+**Usage context:** for building informative docs pinned to a publication version
 
 Indicates WCAG version being built, in `XY` format (i.e. no `.`).
 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).
+(which is effectively the 2.2 Editors' Draft). Note this behavior can be further
+altered by `WCAG_FORCE_LOCAL_GUIDELINES`.
 
 Possible values: `22`, `21`
 
+### `WCAG_FORCE_LOCAL_GUIDELINES`
+
+**Usage context:** Only applicable when `WCAG_VERSION` is also set;
+should not need to be set manually
+
+When building against a fixed publication version, this overrides the behavior of
+loading data from published guidelines, to instead load an alternative local
+`guidelines/index.html` (e.g. from a separate git checkout of another branch).
+This was implemented to enable preview builds of pull requests targeting the
+`WCAG-2.1` branch while reusing the existing build process from `main`.
+
+Possible values: A path relative to the project root, e.g. `../guidelines/index.html`
+
 ### `WCAG_MODE`
 
 **Usage context:** should not need to be set manually except in specific testing scenarios

11ty/guidelines.ts

@@ -165,11 +165,11 @@ function processPrinciples($: CheerioAPI) {
 }
 
 /**
- * Resolves information from guidelines/index.html;
+ * Resolves information from a local guidelines/index.html source file;
  * comparable to the principles section of wcag.xml from the guidelines-xml Ant task.
  */
-export const getPrinciples = async () =>
-  processPrinciples(await flattenDomFromFile("guidelines/index.html"));
+export const getPrinciples = async (path = "guidelines/index.html") =>
+  processPrinciples(await flattenDomFromFile(path));
 
 /**
  * Returns a flattened object hash, mapping shortcodes to each principle/guideline/SC.
@@ -199,14 +199,7 @@ interface Term {
 }
 export type TermsMap = Record<string, Term>;
 
-/**
- * Resolves term definitions from guidelines/index.html organized for lookup by name;
- * comparable to the term elements in wcag.xml from the guidelines-xml Ant task.
- */
-export async function getTermsMap(version?: WcagVersion) {
-  const $ = version
-    ? await loadRemoteGuidelines(version)
-    : await flattenDomFromFile("guidelines/index.html");
+function processTermsMap($: CheerioAPI) {
   const terms: TermsMap = {};
 
   $("dfn").each((_, el) => {
@@ -231,6 +224,14 @@ export async function getTermsMap(version?: WcagVersion) {
   return terms;
 }
 
+/**
+ * Resolves term definitions from guidelines/index.html (or a specified alternate path)
+ * organized for lookup by name;
+ * comparable to the term elements in wcag.xml from the guidelines-xml Ant task.
+ */
+export const getTermsMap = async (path = "guidelines/index.html") =>
+  processTermsMap(await flattenDomFromFile(path));
+
 // Version-specific APIs
 
 const guidelinesCache: Partial<Record<WcagVersion, string>> = {};
@@ -302,6 +303,13 @@ export const getAcknowledgementsForVersion = async (version: WcagVersion) => {
 export const getPrinciplesForVersion = async (version: WcagVersion) =>
   processPrinciples(await loadRemoteGuidelines(version));
 
+/**
+ * Resolves term definitions from a WCAG 2.x publication,
+ * organized for lookup by name.
+ */
+export const getTermsMapForVersion = async (version: WcagVersion) =>
+  processTermsMap(await loadRemoteGuidelines(version));
+
 /** Parses errata items from the errata document for the specified WCAG version. */
 export const getErrataForVersion = async (version: WcagVersion) => {
   const $ = await loadFromFile(join("errata", `${version}.html`));

eleventy.config.ts

@@ -16,6 +16,7 @@ import {
   getPrinciples,
   getPrinciplesForVersion,
   getTermsMap,
+  getTermsMapForVersion,
   scSlugOverrides,
   type FlatGuidelinesMap,
   type Guideline,
@@ -57,10 +58,16 @@ const allPrinciples = await getPrinciples();
 /** Flattened Principles/Guidelines/SC across all versions (including later than selected) */
 const allFlatGuidelines = getFlatGuidelines(allPrinciples);
 
+async function resolveRelevantPrinciples() {
+  if (!process.env.WCAG_VERSION) return allPrinciples;
+  if (process.env.WCAG_FORCE_LOCAL_GUIDELINES)
+    return await getPrinciples(process.env.WCAG_FORCE_LOCAL_GUIDELINES);
+  assertIsWcagVersion(version);
+  return await getPrinciplesForVersion(version);
+}
+
 /** Tree of Principles/Guidelines/SC relevant to selected version */
-const principles = process.env.WCAG_VERSION
-  ? await getPrinciplesForVersion(version)
-  : allPrinciples;
+const principles = await resolveRelevantPrinciples();
 /** Flattened Principles/Guidelines/SC relevant to selected version */
 const flatGuidelines = getFlatGuidelines(principles);
 /** Flattened Principles/Guidelines/SC that only exist in later versions (to filter techniques) */
@@ -105,7 +112,14 @@ for (const [technology, list] of Object.entries(techniques)) {
 const understandingDocs = await getUnderstandingDocs(version);
 const understandingNav = await generateUnderstandingNavMap(principles, understandingDocs);
 
-const termsMap = process.env.WCAG_VERSION ? await getTermsMap(version) : await getTermsMap();
+function resolveRelevantTermsMap() {
+  if (!process.env.WCAG_VERSION) return getTermsMap();
+  if (process.env.WCAG_FORCE_LOCAL_GUIDELINES)
+    return getTermsMap(process.env.WCAG_FORCE_LOCAL_GUIDELINES);
+  assertIsWcagVersion(version);
+  return getTermsMapForVersion(version);
+}
+const termsMap = await resolveRelevantTermsMap();
 
 // Declare static global data up-front so we can build typings from it
 const globalData = {