Implement Eleventy-based build system

[kfranqueiro]

My first project for W3C has been to develop a replacement for the Ant/XSLT-based build system, to give us something that is more flexible to modify and hopefully easier to maintain, since XSLT can be very hard to follow and is not something many people are well-versed in.

The primary building blocks of this PR are Eleventy, as a basis for static site generation and includes, and Cheerio, for in-place markup modifications to take the place of much of what the XSLT was doing in the old build system. TypeScript is also used, as there is a significant amount of custom logic that warrants typings to be easier to work with.

In addition to being able to test this locally (see below), you can now also see the output deployed at:

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

(A new github action is on a separate branch for after this PR.)

Goals

The primary goal of the new build system is to replicate the techniques and understanding output of the existing process as closely as possible to give us a starting point for further improvements. However, there are a couple of noticeable changes and many fixes, noted below.

An additional goal is to avoid the need to touch any input files at this point, given the large number of existing open PRs.

Expected benefits include easier local previewing, and no longer having to worry about HTML doubling as valid XML in order to build successfully.

Files in this PR

• _includes directory: contains as much markup as is feasible to isolate for reusable pieces of pages
  • Note: most include directives currently exist within a Liquid extension class where in-place transformations are performed, in order to avoid modifying source files
• 11ty directory: contains all customizations and data retrieval for the Eleventy build
• A few new top-level files are added to configure Eleventy, TypeScript, and formatting
• One *.11tydata.json file is added to each of the techniques and understanding directories with common data used for processing files in each directory

How to test-run this locally

• First, add a remote pointing to the fork, and checkout the branch:
  git remote add kgf https://github.com/kfranqueiro/wcag.git
git checkout kgf-11ty

There is a README file in the 11ty directory that explains setup and available commands. The short version is:

• npm i
• npm start
• Browse to localhost:8080/techniques or /understanding

I suggest Node 20 (LTS) in the README, but I've now performed test-runs on Node 18, 20, and 22; any of these should work.

Significant changes in this PR

I discussed these changes with @alastc, @mbgower, and @bruce-usab during the weeks leading up to this PR.

About this Technique and Applicability merged

These two sections within individual technique pages were partially redundant of each other. Rather than have to implement 2 sets of wording logic for the same data, this PR incorporates the bulleted-list version of related SC into the About box, followed by any prose originally appearing at the top of the applicability section.

This eliminates various punctuation issues currently observed in the About this Technique box.

"Other sources" h3 replaced with "Related Resources" h2

Techniques pages often have a top-level resources section, which has typically been coded as an h2 in the source files. For some reason, as of #2874, this is transformed into an h3 in the XSLT process, even though it is still a top-level section, still appears in the table of contents (which otherwise only reflects level-2 headings), and the same section remains an h2 for Understanding pages. Furthermore, due to varying content between files, what it ultimately becomes a "subheading" of is not consistent (it is typically after/under Examples, but in at least one instance, there are none, so it is after/under Description). Even if it consistently appeared under Examples, the links in this section are not always related to examples.

This was simpler to revert back to the original h2 behavior, as part of the process of ensuring that consistently-recurring sections and headings are at the correct level, and ensuring that the table of contents is consistently constructed from h2s in every document.

Fixes in this PR

I inevitably found and fixed some behaviors during this effort (sometimes because they were easier to fix than to reproduce as-is).

• Understanding navigation banner:
  • No longer interleaves the guidelines pages in between Other Understanding Documents
  • Includes both previous and next links between Other Understanding Documents (previous was always missing in XSLT process)
• Key Terms DOM is fixed to include parent dl
• Definition links from Techniques pages to TR are fixed to use correct IDs present in TR
• Definition link lookup is now resilient to leading/trailing whitespace inside the <a> tag
• Fixes various trailing-parenthetical issues with applicability lists, e.g. previously seen in G197, ARIA11, H83, H102, T1, T2
• Fixes Understanding Parsing heading to no longer include "(Level )"
• Implements full note paragraph format in Techniques documents (previously "Note" was only seen in Understanding, even though the note class is used in both)
• In Techniques pages, expands links to other techniques under Related Techniques to include both shortcode and title (Show technique titles, not just technique numbers, for related techniques #3583; this expansion was done elsewhere in the XSLT process, but not for this section)
• In Understanding pages, links to obsolete techniques (e.g. Flash, or other techniques removed from source) are removed during the build process
• Automatically fixes incorrectly-cased section IDs (e.g. in H99), which were not detected by the XSLT process
• Fixes titles of Other Understanding documents which seemingly intended to include WCAG version number but didn't
• Table of Contents will no longer contain links to nonexistent sections; the new process generates each page's ToC directly from its h2 elements (after operations to ensure those are consistent)
• Table of Contents for Guideline pages now includes Guideline and Advisory Techniques, which were previously missing
• Does not insert spurious id="" attribute values
• New process is more selective about which links are made to point to TR, fixing various same-page anchor links that previously incorrectly linked to TR
• Restores entire Examples section in Understanding Conformance which XSLT process dropped (likely due to overlapping logic with section of the same name in Techniques pages)
• Renders Key Terms section in Understanding Conformance
• Fixes "New in WCAG 22" to read "WCAG 2.2" (also noted in Fix display of “New in WCAG 22” text #3912, which I also plan to comment on)
• pointer-accessible special case for guidelines version data corrected to input-modalities
• Works around some bugs in content:
  • Skips hard-coded redundant Applicability information in F102 and F105
  • Avoids dropping subsequent h3s within top-level sections (e.g. Intent subheadings in Understanding pages, and examples headings not nested in a sub-section e.g. Textarea in H91)
  • Includes the correct benefits section in 2.5.3, whereas the XSLT process chooses the first of two, which is repeating content from Intent
  • Fixes incorrect example subheadings in some Techniques pages which end up partially dropped in the XSLT process, e.g. C18, SCR33, G57

How I've tested this PR

I have performed multiple rounds of checks on this PR:

• Initial directory-level diffing to ensure the resulting file set completely overlaps with the XSLT process output
• Various DOM-level diffs to compare e.g. headings, section IDs, and links, to ensure no unexpected discrepancies between the XSLT and Eleventy output
• Screenshot diffs as an additional pass to spot unexpected differences
• Compared Eleventy-produced "About this technique" boxes side-by-side with XSLT-produced boxes + applicability sections to check for wording edge cases
• At various steps between commits, diffed before and after changes to make sure each incremental change only changed what is expected and did not introduce regressions
• I verified the cp-cvs script by modifying it to run against the Ant/XSLT-produced output directory and comparing the changes/output between ant publish-w3c (the old copy task) and npm run publish-w3c (the new one)

[w3cbot]

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

[bruce-usab]

Thank you Ken!
I really appreciate having you on the project and the clear communications as much as your technical expertise. I will not be attempting my own local build, so I am picking "comment" rather than "approve" for this review.