highlight.js: Add missing overrides, update version, and run at build time (#4627)

Changes in this PR:

- Adds `language-*` or `no-highlight` classes to code elements inside
pre elements where they were missing, to provide stability across
highlight.js upgrades in the event of changes to auto-detection logic
- This intentionally does not go through the trouble/noise of adding
syntax highlighting to obsolete Flash and Silverlight techniques
- Adds a build-time check which logs in dev / fails in CI if any code
blocks have no class specified
- Updates to use the latest version of highlight.js
- Switches to invoking `highlight.js` at build time and including it as
an npm dependency
- This means no more `highlight.min.js` bundle taking up more space in
the repo on each update
- This also means syntax highlighting no longer involves running
client-side JS on every visit to every page, better optimizing for
sustainability

Author: kfranqueiro

11ty/CustomLiquid.ts

@@ -1,3 +1,4 @@
+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";
@@ -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"];
 

_includes/waiscript.html

@@ -1,8 +1,5 @@
-{% if isTechniques %}{% assign hljsPath = "../" %}{% endif %}
-<link rel="stylesheet" href="{{ hljsPath }}a11y-light.css">
-<script src="{{ hljsPath }}highlight.min.js"></script>
+<link rel="stylesheet" href="{% if isTechniques %}../{% endif %}a11y-light.css">
 <script>
-  hljs.highlightAll();
-  var translationStrings = {}; /* fix WAI JS */
+  var translationStrings = {}; // prevent errors in WAI main.js t() calls
 </script>
 <script src="https://www.w3.org/WAI/assets/scripts/main.js"></script>

eleventy.config.ts

@@ -193,7 +193,6 @@ export default async function (eleventyConfig: any) {
   eleventyConfig.addPassthroughCopy({
     "css/base.css": "techniques/base.css",
     "css/a11y-light.css": "techniques/a11y-light.css",
-    "script/highlight.min.js": "techniques/highlight.min.js",
   });
 
   eleventyConfig.addPassthroughCopy("understanding/*.css");
@@ -225,10 +224,6 @@ export default async function (eleventyConfig: any) {
       join(dir.input, "css", "a11y-light.css"),
       join(dir.output, "understanding", "a11y-light.css")
     );
-    await copyFile(
-      join(dir.input, "script", "highlight.min.js"),
-      join(dir.output, "understanding", "highlight.min.js")
-    );
 
     // Output guidelines/index.html and dependencies for PR runs (not for GH Pages or W3C site)
     const sha = process.env.COMMIT_REF; // Read environment variable exposed by Netlify

package-lock.json

@@ -22,6 +22,7 @@
     "cheerio": "^1.0.0",
     "glob": "^10.3.16",
     "gray-matter": "^4.0.3",
+    "highlight.js": "^11.11.1",
     "liquidjs": "^10.21.0",
     "lodash-es": "^4.17.21",
     "mkdirp": "^3.0.1",

package.json

@@ -79,7 +79,7 @@ <h5><strong>- Instead of... -</strong></h5>
 			</section>
          	<section>
             <h5><strong>- Do... -</strong></h5>
-            <pre xml:space="preserve"><code>&lt;p&gt;
+            <pre><code class="language-html">&lt;p&gt;
   &lt;span class=&quot;icon icon-star-bg&quot; role=&quot;img&quot; aria-label=&quot;Favorite&quot;&gt;&lt;/span&gt;
 &lt;/p&gt;</code></pre>
          	</section>

script/highlight.min.js

@@ -22,7 +22,7 @@ <h3>An options button that opens a dialog</h3>
             <p>The triggering element is a button and the script is triggered from the onclick event. This sends the appropriate events to the operating system so that assistive technology is aware of the change in the DOM. </p>
             <p>In this example, the Submit and Reset buttons inside the dialog simply hide the <code>div</code>. </p>
 
-         <pre><code>...
+         <pre><code class="language-html">...
 &lt;button onclick="TogglePopup(event,true)"
   name="pop0001"&gt;Options&lt;/button&gt;
 
@@ -46,7 +46,7 @@ <h3>An options button that opens a dialog</h3>
 
             <p>The <code>div</code>, heading and <code>form</code> elements are styled with CSS to look like a dialog. </p>
 
-         <pre><code>...
+         <pre><code class="language-css">...
 a { color:blue; }
 a.clickPopup img { border:none; width:0; }
 
@@ -63,7 +63,7 @@ <h3>An options button that opens a dialog</h3>
 
             <p>The script toggles the display of the popup <code>div</code>, showing it and hiding it. </p>
 
-         <pre><code>...
+         <pre><code class="language-javascript">...
 function TogglePopup(evt,show) {
   HarmonizeEvent(evt);
   var src = evt.target;

techniques/aria/ARIA24.html

@@ -48,7 +48,7 @@ <h3>Link elements</h3>
 				<h3>Highlighting elements that receive focus</h3>
 				<p>In this example, the :focus pseudo-class is used to change the style applied to input fields when they receive focus by changing the background color.</p>
 
-<pre xml:space="preserve"><code class="language-">&lt;!doctype html&gt;
+<pre><code class="language-html">&lt;!doctype html&gt;
 &lt;html lang="en"&gt;
   &lt;head&gt;
     &lt;style&gt;

techniques/client-side-script/SCR37.html

@@ -30,7 +30,7 @@ <h3>Using CSS <code>scroll-padding</code> to un-obscure content</h3>
           <p>This example demonstrates a technique to un-obscure content underneath a fixed-position banner. To prevent the page becoming unusable at smaller screen sizes, the banner becomes un-fixed. To observe the <code>scroll-padding</code> effect you will need to use a viewport over 800px wide.</p>
         </aside>
 				<p>Working example: <a href="../../working-examples/css-padding-focus-not-obscured/">Using CSS <code>scroll-padding</code> to un-obscure content</a>.</p>
-<pre xml:space="preserve"><code>&lt;!doctype html&gt;
+<pre><code class="language-html">&lt;!doctype html&gt;
 &lt;html lang="en"&gt;
 &lt;head&gt;
   &lt;meta charset="utf-8"&gt;