Eleventy build: Support generating WCAG 2.1 docs from main branch

[kfranqueiro]

Background

There has long been interest in re-generating updated versions of the informative docs for WCAG 2.1. Previously, this relied upon a separate WCAG-2.1 branch, but the ideal outcome is to be able to build directly from main, altering/pruning content as appropriate.

Changes

This adds more functionality to the Eleventy-based build system to support building content targeting WCAG 2.1 in addition to 2.2, specifically when WCAG_VERSION=21 is set in environment variables:

• Guidelines are pulled from the web so as to not pick up information and alterations from newer WCAG versions (e.g. addition of new SC and removal of 4.1.1)
  • Parsing/processing is augmented as necessary to support both source and pre-processed guidelines
• Acknowledgements are also pulled from the web, pinned to 2.1
• target-size-enhanced is output to target-size for 2.1
• Detects what techniques only apply to later WCAG versions, and prunes them from associations
• Avoids emitting pages for techniques and understanding documents that exclusively pertain to later WCAG versions
• Further updates hard-coded version numbers in titles and level-1 headings, as well as throughout pages (especially refer-to-wcag) via Liquid expressions
• Adds support for setting both note and wcagXY class on the same element
• Conditionalizes a couple of 2.2-specific notes that were not within elements with wcag22 class
• Unchanged but worth noting: Obsolete technique data includes version information, so anything marked obsolete as of 2.2 will not contain an obsolete banner when publishing for 2.1

Preview

Do not use the Netlify preview for this, as it always builds 2.2 docs. (I've done a pass to verify that this PR doesn't visibly affect 2.2 output.)

I have set up a preview of this branch on my fork for the lifetime of this PR:

• https://kfranqueiro.github.io/wcag/techniques/
• https://kfranqueiro.github.io/wcag/understanding/

I have done quick-ish passes over both folders to try to spot and resolve any surprises. The Techniques pages largely only changed with respect to Test Rules (due to updated act-mapping.json) or the de-listing of obsolete techniques. I particularly looked over the Understanding pages since those align parallel with the guidelines and seem to have more meaningful updates. It is still possible that I have missed additional cases, e.g. of 2.2-specific wording that isn't properly enclosed in a class="wcag22" element. This ideally warrants a thorough review.

The following Understanding pages inherit notable changes: (checkboxes included for review tracking purposes)

• Use of Color (2.2, 2.1)
• Contrast (Minimum) (2.2, 2.1)
• Resize Text (2.2, 2.1)
• Reflow (2.2, 2.1)
• Non-text Contrast (2.2, 2.1)
• Text Spacing (2.2, 2.1)
• Keyboard (No Exception) (2.2, 2.1)
• Character Key Shortcuts (2.2, 2.1)
• Timing Adjustable (2.2, 2.1)
• Three Flashes or Below Threshold (2.2, 2.1)
  • Removes a 2.2-specific note
• Page Titled (2.2, 2.1)
• Focus Visible (2.2, 2.1)
• Pointer Gestures (2.2, 2.1)
• Label in Name (2.2, 2.1)
• Target Size (2.2, 2.1)
• Reading Level (2.2, 2.1)
  • Restores content that the XSLT build had suppressed
• Error Identification (2.2, 2.1)
• Labels or Instructions (2.2, 2.1)
• Parsing (2.2, 2.1)
  • No longer discusses removal, since it was only removed in 2.2 and there was seemingly some dedicated change on the WCAG-2.1 branch; do we still want a more prominent note here that is 2.1-specific? (The WCAG-2.1 branch also ends up repeating the SC a second time in this section even though it is still presented as usual in the box above Intent)
• Name, Role, Value (2.2, 2.1)
  • Removes a link that 404s
• Understanding Techniques (2.2, 2.1)
  • Updates “Techniques Submission Form” link to GitHub repo link
• Understanding Conformance (2.2, 2.1)
  • Examples no longer suppressed from build (content already existed)
  • Key Terms section is now properly generated
• How to Refer to WCAG from Other Documents (2.2, 2.1)
  • Version numbers consistently updated (examples were previously referencing 2.0)

[netlify]

✅ Deploy Preview for wcag2 ready!

Name	Link
🔨 Latest commit	d9bd774
🔍 Latest deploy log	https://app.netlify.com/sites/wcag2/deploys/673e491f48f9bf000806a9fa
😎 Deploy Preview	https://deploy-preview-4007--wcag2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[w3cbot]

kfranqueiro marked as non substantive for IPR from ash-nazg.

[alastc]

I'm fairly sure we didn't include anything 2.2 specific in 2.1 docs without that markup, it was very rare.

[stevefaulkner]

@mbgower - use of color, contrast (minimum), resize text
@patrickhlauke - reflow, non-text contrast, text spacing
@alastc - keyboard (no exception), character key shortcuts, timing adjustable
@scottaohara - three flashes or below threshold, page titled, focus visible
@dbjorge - pointer gestures, label in name, target size
@stevefaulkner - reading level, error identification, labels or instructions
@bruce-usab - parsing, name role value, understanding techniques

[bruce-usab]

Discussed on backlog call 11-1 and review divided up (as above).

[mbgower]

@kfranqueiro, the files for changed understanding docs (for instance use-of-color) are not generally showing up in the Files changed tab's list; however, I have confirmed that modifications to notes and the addition of paragraphs from 2.2 have been incorporated into the 2.1 preview (e.g., where the note or paragraph is missing from the current 2.1 Understanding doc).

[mbgower]

@kfranqueiro while the contrast minimum material has been updated, I assume the double-square bracket references in all 3 versions of this understanding document (2.0, 2.1, 2.2) were intended to be linked references, but did not generate properly. It looks like this is covered by #2535 so just flagging again here.

[kfranqueiro]

@kfranqueiro, the files for changed understanding docs (for instance use-of-color) are not generally showing up in the Files changed tab's list; however, I have confirmed that modifications to notes and the addition of paragraphs from 2.2 have been incorporated into the 2.1 preview (e.g., where the note or paragraph is missing from the current 2.1 Understanding doc).

Right, the actual source files for informative docs won't change. The difference is this builds 2.1 docs from main rather than from the variably-out-of-date WCAG-2.1 branch, which is what's responsible for all of the backports, the idea being that updates to informative docs on main will impact both versions. The only thing the WCAG-2.1 branch will still be used for is things directly impacting the TR doc itself.

@kfranqueiro while the contrast minimum material has been updated, I assume the double-square bracket references in all 3 versions of this understanding document (2.0, 2.1, 2.2) were intended to be linked references, but did not generate properly. It looks like this is covered by #2535 so just flagging again here.

Right, this doesn't affect that, and those have been an issue for as long as these docs have existed in their current form; there's a separate PR I opened this Tuesday that addresses as much of that as can currently be addressed with the information available in specref and our local biblio.js.

[mbgower]

@kfranqueiro I am now reviewing understanding/conformance.

IMO, for both 2.2 and 2.1, "which includes techniques for providing Conforming Alternate Version" should be lower case, to read:

See also Understanding Conforming Alternate Versions which includes techniques for providing conforming alternate versions.

The rationale is that the definition itself (2 paragraphs earlier) is lower case, so while it is fine to leave the heading link in camel case, the final term should be lc.

---

I'm also trying to understand whether "conforming alternative version" and "conforming alternate version" are accidental differences, or if there are actually two different terms. There are 31 occurrences of the former and 5 of the latter. I'm 90% sure this is supposed to all be the same thing; you'll note that under the title "Understanding Conforming Alternate Versions" both terms are used in the next paragraph, seemingly as synonyms.

IMO, these should all be alternative. That means "another option", while alternate implies a vacillation between two options.

I just had a look at WCAG 2.2, and its use of the two terms is almost opposite that in the Understanding section: 52 occurrences of "alternative" and 14 of "alternate"; however, there continues to be, within the normative text, use of the term "conforming alternate version" including in a definition.

@alastc do we just leave all these conflicts in place in the normative text, or do we try to incorporate this into the CFC?

PS When I just checked various files, I seemed to come up with different counts (48, 25). I'm not sure if I was doing a search with match case last time or what

[mbgower]

@kfranqueiro
In the understanding/conformance document, an opening quotation mark has ended up before the word "Note" rather than in front of the word "If"

[mbgower]

@kfranqueiro potentially the same issue in the Technical Definition of "Accessibility Supported" section; however, it is also like this on the 2.2 version, so maybe this is intentional?!

IMO, since there is styling showing the WHOLE thing is a quote, the quotation marks in front of note are not correct.