Merge branch 'main' into giacomo-petri-3_3_2-non-text-label

Author: patrickhlauke

.eleventyignore

@@ -1,3 +1,5 @@
+import { type Options as SlugifyOptions, slugifyWithCounter } from "@sindresorhus/slugify";
+import hljs from "highlight.js";
 import { Liquid, type Template } from "liquidjs";
 import type { LiquidOptions, RenderOptions } from "liquidjs/dist/liquid-options";
 import compact from "lodash-es/compact";
@@ -9,7 +11,6 @@ import type { GlobalData } from "eleventy.config";
 
 import { biblioPattern, getBiblio, getXmlBiblio } from "./biblio";
 import { flattenDom, load, type CheerioAnyNode } from "./cheerio";
-import { generateId } from "./common";
 import { getAcknowledgementsForVersion, type TermsMap } from "./guidelines";
 import { resolveTechniqueIdFromHref, understandingToTechniqueLinkSelector } from "./techniques";
 import { techniqueToUnderstandingLinkSelector } from "./understanding";
@@ -153,6 +154,31 @@ export class CustomLiquid extends Liquid {
       // Add charset to pages that forgot it
       if (!$("meta[charset]").length) $('<meta charset="UTF-8">').prependTo("head");
 
+      const $missingHljsOverrides = $("pre code:not([class])");
+      if ($missingHljsOverrides.length) {
+        $missingHljsOverrides.each((_, el) => {
+          const code = $(el).html()!.replace(/\n/g, "\\n");
+          const excerpt = `${code.slice(0, 40)}${code.length > 40 ? "..." : ""}`;
+          console.log(
+            `${filepath} missing "language-*" or "no-highlight" class on <pre><code> starting with ${excerpt}`
+          );
+        });
+        if (process.env.ELEVENTY_RUN_MODE === "build") {
+          throw new Error(
+            "Please ensure all code blocks have a highlight.js class (language-* or no-highlight)."
+          );
+        }
+      }
+
+      $("pre code[class*='language-']").each((_, el) => {
+        const $el = $(el);
+        // Unescape any HTML entities (which were originally needed for client-side highlight.js)
+        const code = $el.html()!.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+        const language = $el.attr("class")!.replace(/^.*language-(\S+).*$/, "$1");
+        $el.html(hljs.highlight(code, { language }).value);
+        $el.addClass("hljs");
+      });
+
       const prependedIncludes = ["header"];
       const appendedIncludes = ["wai-site-footer", "site-footer"];
 
@@ -614,6 +640,9 @@ export class CustomLiquid extends Liquid {
       } else $("section#references").remove();
     }
 
+    const slugify = slugifyWithCounter();
+    const slugifyOptions: SlugifyOptions = { decamelize: false };
+
     // Allow autogenerating missing top-level section IDs in understanding docs,
     // but don't pick up incorrectly-nested sections in some techniques pages (e.g. H91)
     const sectionSelector = scope.isUnderstanding ? "section" : "section[id]:not(.obsolete)";
@@ -624,7 +653,8 @@ export class CustomLiquid extends Liquid {
       // when we have sections and sidebar skeleton already reordered
       const $tocList = $(".sidebar nav ul");
       $h2Sections.each((_, el) => {
-        if (!el.attribs.id) el.attribs.id = generateId($(el).find(sectionH2Selector).text());
+        if (!el.attribs.id)
+          el.attribs.id = slugify($(el).find(sectionH2Selector).text(), slugifyOptions);
         $("<a></a>")
           .attr("href", `#${el.attribs.id}`)
           .text(normalizeTocLabel($(el).find(sectionH2Selector).text()))
@@ -648,9 +678,14 @@ export class CustomLiquid extends Liquid {
     $(autoIdSectionSelectors.join(", "))
       .filter(`:has(${sectionHeadingSelector})`)
       .each((_, el) => {
-        el.attribs.id = generateId($(el).find(sectionHeadingSelector).text());
+        el.attribs.id = slugify($(el).find(sectionHeadingSelector).text(), slugifyOptions);
       });
 
+    // Also autogenerate IDs for any headings with no dedicated section nor explicit ID
+    $(":is(h3, h4, h5):not(:first-child):not([id])").each((_, el) => {
+      el.attribs.id = slugify($(el).text(), slugifyOptions);
+    });
+
     return stripHtmlComments($.html());
   }
 }

11ty/CustomLiquid.ts

@@ -183,6 +183,8 @@ Generates `_site/wcag.json`. (This is not done by default, as it adds to build t
 
 **Default:** Unset by default; `publish-w3c` scripts set this to a non-empty value.
 
+For more information on the output, see [11ty/json/README.md](json#readme).
+
 ### `GITHUB_REPOSITORY`
 
 **Usage context:** Automatically set during GitHub workflows; should not need to be set manually

11ty/README.md

@@ -0,0 +1,25 @@
+# JSON Serialization of WCAG 2
+
+The script in this folder serializes WCAG 2 information into JSON format, including:
+
+- Principles, guidelines, and success criteria
+- Glossary terms
+- Associations between (normative) success criteria and (informative) techniques
+
+The following JSON files are published monthly:
+
+- [WCAG 2.2 JSON](https://www.w3.org/WAI/WCAG22/wcag.json)
+- [WCAG 2.1 JSON](https://www.w3.org/WAI/WCAG21/wcag.json)
+
+For a history of structural changes to the JSON files, see the [list of merged wcag.json pull requests](https://github.com/w3c/wcag/pulls?q=is%3Apr+label%3Awcag.json), and in particular the "wcag.json Changes" section in each pull request description.
+
+## Permission to use with attribution
+
+You may use this data, in full or in part, provided you:
+
+- Clearly attribute the original source and include a link to it ([Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/),  [Techniques for WCAG 2.2](https://www.w3.org/WAI/WCAG22/Techniques/), [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21/), [Techniques for WCAG 2.1](https://www.w3.org/WAI/WCAG21/Techniques/))
+- Do not change the content
+
+If you include additional information, it must be clear what is from the W3C WCAG documents and what is added.
+
+See [W3C Document license](https://www.w3.org/copyright/document-license/) and [W3C Intellectual rights](https://www.w3.org/copyright/intellectual-rights/), particularly '[May I annotate one of your specifications?](https://www.w3.org/copyright/intellectual-rights/#annotate)'.