Update deploy workflow to use Eleventy build process (#3955)

This replaces the existing files under `.github` (both `workflows` and
`scripts`) with a new workflow using the Eleventy build process.

- Current behavior RE `conformance-challenges`, `guidelines`, and
`requirements` directories is retained
  - Also ensures necessary CSS is updated under `guidelines`
- `techniques`, `understanding`, and `working-examples` are now
generated by the Eleventy build process

This has positive side effects over what's currently seen on github.io:
- Fixes broken styles
- Updates any auto-generated cross-links to guidelines to point to 2.2
editor's draft instead of 2.1
- All of the fixes mentioned in #3917

Author: kfranqueiro

.github/scripts/deploy.sh

@@ -0,0 +1,44 @@
+name: CI
+
+# Reference documentation: https://docs.github.com/en/actions/reference
+
+# See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestbranchestags
+on:
+  push:
+    branches: [main]
+
+jobs:
+  main:
+    name: deploy (11ty)
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v4
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: _site
+      - name: Install Node.js and dependencies
+        uses: actions/setup-node@v4
+        with:
+          cache: npm
+          node-version-file: '.nvmrc'
+      - name: Build
+        env:
+          WCAG_MODE: editors
+        run: |
+          npm i
+          npm run build
+          cp guidelines/guidelines.css guidelines/relative-luminance.html _site/guidelines/22
+          curl https://labs.w3.org/spec-generator/?type=respec"&"url=https://raw.githack.com/$GITHUB_REPOSITORY/main/guidelines/index.html -o _site/guidelines/22/index.html -f  --retry 3
+          curl https://labs.w3.org/spec-generator/?type=respec"&"url=https://raw.githack.com/$GITHUB_REPOSITORY/main/requirements/22/index.html -o _site/requirements/22/index.html -f  --retry 3
+          curl https://labs.w3.org/spec-generator/?type=respec"&"url=https://raw.githack.com/$GITHUB_REPOSITORY/main/conformance-challenges/index.html -o _site/conformance-challenges/index.html -f  --retry 3
+      - name: Push
+        working-directory: _site
+        run: |
+          git config user.email 87540780+w3cgruntbot@users.noreply.github.com
+          git config user.name w3cgruntbot
+          git add -A .
+          git commit -m ":robot: Deploy to GitHub Pages: $GITHUB_SHA from branch $GITHUB_REF"
+          git push origin gh-pages

.github/workflows/11ty-publish.yaml

@@ -40,16 +40,16 @@ Indicates top-level path of W3C CVS checkout, for WAI site updates (via `publish
 
 ### `WCAG_VERSION`
 
-**Usage context:** `publish-w3c` script only;
-this should currently not be changed, pending future improvements to `21` support.
+**Usage context:** currently this should not be changed, pending future improvements to `21` support
 
-Indicates WCAG version being built, in `XY` format (i.e. no `.`)
+Indicates WCAG version being built, in `XY` format (i.e. no `.`).
+Influences base URLs for links to guidelines, techniques, and understanding pages.
 
 **Default:** `22`
 
 ### `WCAG_MODE`
 
-**Usage context:** should not need to be used manually except in specific testing scenarios
+**Usage context:** should not need to be set manually except in specific testing scenarios
 
 Influences base URLs for links to guidelines, techniques, and understanding pages.
 Typically set by specific npm scripts or CI processes.
@@ -60,6 +60,15 @@ Possible values:
 - `editors` - Sets base URLs appropriate for `gh-pages` publishing; used by deploy action
 - `publication` - Sets base URLs appropriate for WAI site publishing; used by `publish-w3c` script
 
+### `GITHUB_REPOSITORY`
+
+**Usage context:** Automatically set during GitHub workflows; should not need to be set manually
+
+Influences base URLs for links to guidelines, techniques, and understanding pages,
+when `WCAG_MODE=editors` is also set.
+
+**Default:** `w3c/wcag`
+
 ## Other points of interest
 
 - The main configuration can be found in top-level `eleventy.config.ts`

.github/workflows/manual-publish.yml

@@ -1,14 +1,17 @@
 /** @fileoverview script to copy already-built output to CVS subfolders */
 
-import { copyFile, unlink } from "fs/promises";
 import { glob } from "glob";
 import { mkdirp } from "mkdirp";
 
+import { copyFile, unlink } from "fs/promises";
 import { dirname, join } from "path";
 
+import { assertIsWcagVersion } from "./guidelines";
+
 const outputBase = "_site";
 const cvsBase = process.env.WCAG_CVSDIR || "../../../w3ccvs";
 const wcagVersion = process.env.WCAG_VERSION || "22";
+assertIsWcagVersion(wcagVersion);
 const wcagBase = `${cvsBase}/WWW/WAI/WCAG${wcagVersion}`;
 
 // Map (git) sources to (CVS) destinations, since some don't match case-sensitively

11ty/README.md

@@ -8,7 +8,7 @@ import { flattenDomFromFile, load } from "./cheerio";
 import { generateId } from "./common";
 
 export type WcagVersion = "20" | "21" | "22";
-function assertIsWcagVersion(v: string): asserts v is WcagVersion {
+export function assertIsWcagVersion(v: string): asserts v is WcagVersion {
   if (!/^2[012]$/.test(v)) throw new Error(`Unexpected version found: ${v}`);
 }
 

11ty/cp-cvs.ts

@@ -3,7 +3,7 @@ import compact from "lodash-es/compact";
 import { copyFile } from "fs/promises";
 
 import { CustomLiquid } from "11ty/CustomLiquid";
-import { actRules, getFlatGuidelines, getPrinciples } from "11ty/guidelines";
+import { actRules, assertIsWcagVersion, getFlatGuidelines, getPrinciples } from "11ty/guidelines";
 import {
   getFlatTechniques,
   getTechniqueAssociations,
@@ -15,7 +15,8 @@ import { generateUnderstandingNavMap, getUnderstandingDocs } from "11ty/understa
 import type { EleventyContext, EleventyData, EleventyEvent } from "11ty/types";
 
 /** Version of WCAG to build */
-const version = "22";
+const version = process.env.WCAG_VERSION || "22";
+assertIsWcagVersion(version);
 
 const principles = await getPrinciples();
 const flatGuidelines = getFlatGuidelines(principles);
@@ -45,6 +46,8 @@ export type GlobalData = EleventyData &
     isUnderstanding?: boolean;
   };
 
+const [GH_ORG, GH_REPO] = (process.env.GITHUB_REPOSITORY || "w3c/wcag").split("/");
+
 const baseUrls = {
   guidelines: `https://www.w3.org/TR/WCAG${version}/`,
   techniques: "/techniques/",
@@ -53,9 +56,11 @@ const baseUrls = {
 
 if (process.env.WCAG_MODE === "editors") {
   // For pushing to gh-pages
-  baseUrls.guidelines = "https://w3c.github.io/wcag/guidelines/";
-  baseUrls.techniques = "https://w3c.github.io/wcag/techniques/";
-  baseUrls.understanding = "https://w3c.github.io/wcag/understanding/";
+  baseUrls.guidelines = `https://${GH_ORG}.github.io/${GH_REPO}/guidelines/${
+    version === "21" ? "" : `${version}/`
+  }`;
+  baseUrls.techniques = `https://${GH_ORG}.github.io/${GH_REPO}/techniques/`;
+  baseUrls.understanding = `https://${GH_ORG}.github.io/${GH_REPO}/understanding/`;
 } else if (process.env.WCAG_MODE === "publication") {
   // For pushing to W3C site
   baseUrls.guidelines = `https://www.w3.org/TR/WCAG${version}/`;