From fe942fad163f53478dc7e214c0453f94a27d6000 Mon Sep 17 00:00:00 2001 From: "Kenneth G. Franqueiro" Date: Fri, 20 Dec 2024 15:07:22 -0500 Subject: [PATCH] Allow running builds against a custom local guidelines folder --- 11ty/README.md | 19 +++++++++++++++++-- 11ty/guidelines.ts | 30 +++++++++++++++++++----------- eleventy.config.ts | 22 ++++++++++++++++++---- 3 files changed, 54 insertions(+), 17 deletions(-) diff --git a/11ty/README.md b/11ty/README.md index a1b7d063b2..3bcf6d1cfd 100644 --- a/11ty/README.md +++ b/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 diff --git a/11ty/guidelines.ts b/11ty/guidelines.ts index 27cc3fd8ff..a5d556c801 100644 --- a/11ty/guidelines.ts +++ b/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; -/** - * 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 remoteGuidelines$: Partial> = {}; @@ -299,3 +300,10 @@ 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)); diff --git a/eleventy.config.ts b/eleventy.config.ts index d579a657ff..c82ab5ff97 100644 --- a/eleventy.config.ts +++ b/eleventy.config.ts @@ -15,6 +15,7 @@ import { getPrinciples, getPrinciplesForVersion, getTermsMap, + getTermsMapForVersion, scSlugOverrides, type FlatGuidelinesMap, type Guideline, @@ -56,10 +57,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) */ @@ -104,7 +111,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 = {