Skip to content

Conversation

kfranqueiro
Copy link
Contributor

@kfranqueiro kfranqueiro commented Sep 19, 2025

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
    • Example of message logged for each missing class found:
      ./techniques/css/C45.html missing "language-*" or "no-highlight" class on <pre><code> starting with &lt;!DOCTYPE html&gt;\n&lt;html lang="en...
    • Example of message printed when build fails (for CI, in addition to the above message):
      [11ty] 1. Having trouble rendering liquid template ./techniques/css/C45.html (via TemplateContentRenderError)
      [11ty] 2. Please ensure all code blocks have a highlight.js class (language-* or no-highlight).
      
  • 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

Before switching from client-side to build-time, I verified (using the script I'd posted in #4611) that updating the bundle does not cause any syntax highlighting changes, other than adding it for the previously-missing languages.

I also performed screenshot diffs and have verified that the only changes caused by the update are fixes to syntax highlighting (primarily in terms of recognized CSS property names).

I performed screenshot diffs again after switching to build-time highlight.js, and there were only two diffs, in examples that specifically intended to include <span lang="..."> elements inside of <pre><code>. These have been adjusted to apply lang to the pre tag instead.

Note: The failure on the Check PR files check is an extremely rare false positive because I had updated it to consider script normative, but technically only script/wcag.js is involved in TR space; script/highlight.min.js is not. This should never be an issue again, since I'm removing highlight.min.js.

Copy link

netlify bot commented Sep 19, 2025

Deploy Preview for wcag2 ready!

Name Link
🔨 Latest commit a7d4e04
🔍 Latest deploy log https://app.netlify.com/projects/wcag2/deploys/68d43d262c8b4f00095f88c8
😎 Deploy Preview https://deploy-preview-4627--wcag2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@kfranqueiro kfranqueiro force-pushed the kgf-add-missing-hljs-overrides branch from 523d7a9 to 0f31306 Compare September 24, 2025 18:38
@kfranqueiro kfranqueiro changed the title Add missing highlight.js overrides and upgrade highlight.js Add missing highlight.js overrides, upgrade highlight.js, and run at build time Sep 24, 2025
@kfranqueiro kfranqueiro changed the title Add missing highlight.js overrides, upgrade highlight.js, and run at build time highlight.js: Add missing overrides, update version, and run at build time Sep 24, 2025
@kfranqueiro kfranqueiro merged commit dc61084 into main Sep 25, 2025
6 of 7 checks passed
@kfranqueiro kfranqueiro deleted the kgf-add-missing-hljs-overrides branch September 25, 2025 14:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants