Generate IDs for sectionless headings, and improve/fix existing IDs (#4523)

Fixes #4425.

This adds IDs to headings that aren't the first under their respective
parent section, and relies on `@sindresorhus/slugify` to produce
headings, with counters when duplicate labels exist. (This library is an
existing dependency of Eleventy, so it does not increase `npm install`
size.)

This updates _all_ generated IDs to use `slugify` instead of the
previous logic that had been ported from the XSLT process. This means
some subsection IDs may change; it also means some which were previously
inaccessible due to duplicate IDs will be fixed. None of the standard
level-2 headings should be impacted.

I performed extra testing to check for headings that might've been
overlooked by the selector I used here, but all of the first-child cases
involve headings under sections which will already have IDs.

Author: kfranqueiro

11ty/CustomLiquid.ts

@@ -1,3 +1,4 @@
+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";
@@ -10,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";
@@ -640,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)";
@@ -650,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()))
@@ -674,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());
   }
 }

package-lock.json

@@ -18,6 +18,7 @@
   "license": "W3C",
   "dependencies": {
     "@11ty/eleventy": "^3.1.2",
+    "@sindresorhus/slugify": "^2.2.1",
     "axios": "^1.11.0",
     "cheerio": "^1.0.0",
     "glob": "^10.3.16",

package.json

@@ -44,7 +44,7 @@ <h2>Sufficient Techniques</h2>
 					<p>From an evaluator's perspective: If web content implements the sufficient techniques for a given criterion correctly and it is <a href="conformance#accessibility-support">accessibility-supported</a> for the content's users, it conforms to that success criterion. (The converse is not true; if content does not implement these sufficient techniques, it does not necessarily fail the success criteria, as explained in <a href="#testing-techniques">Testing Techniques</a> below.)</p>
 				</li>
 			</ul>
-			<p>There may be other ways to meet success criteria besides the sufficient techniques in W3C's <a href="../Techniques/">Techniques for WCAG {{ versionDecimal }}</a> document, as explained in <a href="#understanding-techniques-othertechs">Other Techniques</a> below. <em>(See also <a href="#understanding-techniques-informative">Techniques are Informative</a> above.)</em></p>
+			<p>There may be other ways to meet success criteria besides the sufficient techniques in W3C's <a href="../Techniques/">Techniques for WCAG {{ versionDecimal }}</a> document, as explained in <a href="#other-techniques">Other Techniques</a> below. <em>(See also <a href="#techniques-are-informative">Techniques are Informative</a> above.)</em></p>
 			<section>
 				<h3>Numbered Lists, "AND"</h3>
 				<p> The W3C-documented sufficient techniques are provided in a numbered list where each list item provides a technique or combination of techniques that can be used to meet the success criterion. Where there are multiple techniques on a numbered list item connected by "AND" then all of the techniques must be used to be sufficient. For example, <a href="info-and-relationships#techniques">Sufficient Techniques for 1.3.1</a> has: "G115: Using semantic elements to mark up structure AND H49: Using semantic markup to mark emphasized or special text (HTML)".</p>
@@ -87,7 +87,7 @@ <h2>General and Technology-specific Techniques</h2>
 		<section>
 			<h2>Other Techniques</h2>
 			<p>In addition to the techniques in W3C's <a href="../Techniques/">Techniques for WCAG {{ versionDecimal }}</a> document, <em>there are other ways to meet WCAG {{ versionDecimal }} success criteria</em>. W3C's techniques are not comprehensive and may not cover newer technologies and situations.</p>
-			<p><em>web content does not have to use W3C's published techniques in order to conform to WCAG {{ versionDecimal }}. (See also <a href="understanding-techniques-informative">Techniques are Informative</a> above.)</em></p>
+			<p><em>web content does not have to use W3C's published techniques in order to conform to WCAG {{ versionDecimal }}. (See also <a href="#techniques-are-informative">Techniques are Informative</a> above.)</em></p>
 			<p>Content authors can develop different techniques. For example, an author could develop a technique for HTML5, <a href="https://www.w3.org/WAI/intro/aria">WAI-ARIA</a>, or other new technology. Other organizations may develop sets of techniques to meet WCAG {{ versionDecimal }} success criteria.</p>
 			<p>Any techniques can be sufficient if:</p>
 			<ul>