Remove unnecessary code class and pre xml:space attributes from informative docs #4611

kfranqueiro · 2025-09-12T13:32:58Z

This removes:

All xml:space attributes from pre elements, which are no longer needed since the XSLT build system was retired
All att, el, obj, prop, and propval classes from code elements, which don't have any associated styles
All language-* classes from inline code elements, which have no effect because highlight.js does not run on them
Most language-* classes on code elements inside pre, except where highlight.js guesses incorrectly without it

This fixes the following highlight.js instances, which had been manually overridden to the wrong values:

html incorrectly overridden to css in C35 (2x), C36, F2, F100
html incorrectly overridden to javascript in SCR14, F3, F37, F50
css incorrectly overridden to html in ARIA24 (2x), G188
php-template incorrectly overridden to html in C29 (2x)
php-template (with HTML also highlighted) incorrectly overridden to php (HTML not highlighted) in SVR3, SVR4

All other instances are unaffected, as auto-detection matches the removed override.

Note this will also benefit from #4520, which will further prevent slightly-inaccurate-but-mostly-harmless auto-detection of CSS as Less (which is present in the external highlight.js loaded in those files, but not present in our own highlight.min.js).

How I determined where language-* classes were required

Add some logging to highlight.js before running highlightAll:

hljs.addPlugin({
  "after:highlightElement": ({ result, text }) => {
    console.log(`hljs: ${result.language} ${result.relevance} ${JSON.stringify(text.slice(0, 30))}`);
  }
});

Run all pages with pre code through playwright:

import { load } from "cheerio";
import { readFile } from "fs/promises";
import { join } from "path";
import { chromium, devices } from "playwright";
import { glob } from "tinyglobby";

const baseUrl = "http://localhost:8080/";
const cwd = "../wcag/_site";
const paths = (
  await glob(["techniques/**/*.html", "understanding/**/*.html"], { cwd })
).sort();

const browser = await chromium.launch();
const context = await browser.newContext(devices["Desktop Chrome"]);

for (const path of paths) {
  // Skip files that don't actively use hljs (cuts run time in half)
  const $ = load(await readFile(join(cwd, path)));
  if (!$("pre code").length) continue;

  const page = await context.newPage();
  page.on("console", (message) => {
    const text = message.text();
    if (text.startsWith("hljs: ")) console.log(path, text);
  });
  await page.goto(baseUrl + path);
  await page.close();
}

await context.close();
await browser.close();

Pipe the above script to a file, run before and after the changes, and compare the results:
- For diffs where the "before" was correct, I restored the override (backed out the removal)
- For diffs where the "after" is correct, the override was incorrect and removing it fixes highlighting (see list of fixes above)

netlify · 2025-09-12T13:33:49Z

✅ Deploy Preview for wcag2 ready!

Name	Link
🔨 Latest commit	`9434d3c`
🔍 Latest deploy log	https://app.netlify.com/projects/wcag2/deploys/68c82af84cb77b00086b91d7
😎 Deploy Preview	https://deploy-preview-4611--wcag2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

patrickhlauke · 2025-09-13T12:51:35Z

techniques/aria/ARIA12.html

   </head>
 	 <body>
-		<h1>Using <code class="language-html">role=heading</code> to identify headings</h1>
+		<h1>Using <code>role=heading</code> to identify headings</h1>


this may be one of those inline uses that would benefit from highlighting, if that's possible

patrickhlauke · 2025-09-13T12:52:02Z

techniques/aria/ARIA12.html

      <p>The purpose of this technique is to provide a way for Assistive Technologies (AT) to identify 
-a piece of content as a heading. Applying <code class="language-html">role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading. The <code class="language-html">role="heading"</code> property must be paired with the <code class="language-html">aria-level</code> property to define the heading level.</p>
-      <p>When possible, <a href="https://www.w3.org/TR/using-aria/#rule1">use native heading markup</a>. For example, it is preferable to use an <code class="language-html">h1</code> element, rather than using <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code>. Native <abbr title="HyperText Markup Language">HTML</abbr> elements have implicit styling and features that won't necessarily be replicated with ARIA equivalents. For instance, heading elements will have specific styling adjustments made when viewing a page in a browser's Reader Mode. Whereas a <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code> will not be styled as a heading, because the underlying element is a <code class="language-html">div</code>. ARIA only modifies the way an element is exposed to assistive technology, it does nothing to change the implicit style or functionality of the element it is applied to.</p>
+a piece of content as a heading. Applying <code>role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading. The <code>role="heading"</code> property must be paired with the <code>aria-level</code> property to define the heading level.</p>


the role ones may benefit from highlighting if possible

patrickhlauke · 2025-09-13T12:52:33Z

techniques/aria/ARIA12.html

-a piece of content as a heading. Applying <code class="language-html">role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading. The <code class="language-html">role="heading"</code> property must be paired with the <code class="language-html">aria-level</code> property to define the heading level.</p>
-      <p>When possible, <a href="https://www.w3.org/TR/using-aria/#rule1">use native heading markup</a>. For example, it is preferable to use an <code class="language-html">h1</code> element, rather than using <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code>. Native <abbr title="HyperText Markup Language">HTML</abbr> elements have implicit styling and features that won't necessarily be replicated with ARIA equivalents. For instance, heading elements will have specific styling adjustments made when viewing a page in a browser's Reader Mode. Whereas a <code class="language-html">&lt;div role="heading" aria-level="1"&gt;</code> will not be styled as a heading, because the underlying element is a <code class="language-html">div</code>. ARIA only modifies the way an element is exposed to assistive technology, it does nothing to change the implicit style or functionality of the element it is applied to.</p>
+a piece of content as a heading. Applying <code>role="heading"</code> to an element causes an AT (like a screen reader) to treat it as though it were a heading. The <code>role="heading"</code> property must be paired with the <code>aria-level</code> property to define the heading level.</p>
+      <p>When possible, <a href="https://www.w3.org/TR/using-aria/#rule1">use native heading markup</a>. For example, it is preferable to use an <code>h1</code> element, rather than using <code>&lt;div role="heading" aria-level="1"&gt;</code>. Native <abbr title="HyperText Markup Language">HTML</abbr> elements have implicit styling and features that won't necessarily be replicated with ARIA equivalents. For instance, heading elements will have specific styling adjustments made when viewing a page in a browser's Reader Mode. Whereas a <code>&lt;div role="heading" aria-level="1"&gt;</code> will not be styled as a heading, because the underlying element is a <code>div</code>. ARIA only modifies the way an element is exposed to assistive technology, it does nothing to change the implicit style or functionality of the element it is applied to.</p>


the examples with div role may benefit from highlighting if possible

patrickhlauke · 2025-09-13T12:52:50Z

techniques/aria/ARIA12.html

 			<h3>Simple headings</h3>
-			<p>This example demonstrates how to implement headings using <code class="language-html">role="heading"</code> and <code class="language-html">aria-level</code>.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;div role="heading" aria-level="2"&gt;Global News Items&lt;/div&gt;
+			<p>This example demonstrates how to implement headings using <code>role="heading"</code> and <code>aria-level</code>.</p>


role ones may benefit from highlighting

patrickhlauke · 2025-09-13T12:53:10Z

techniques/aria/ARIA12.html


-            <p>This example demonstrates how to implement a level 7 heading using <code class="language-html">role="heading"</code> and the <code class="language-html">aria-level</code> attribute. Since HTML only supports headings up to level 6, there is no native element to provide these semantics.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;h5&gt;Fruit Trees&lt;/h5&gt;
+            <p>This example demonstrates how to implement a level 7 heading using <code>role="heading"</code> and the <code>aria-level</code> attribute. Since HTML only supports headings up to level 6, there is no native element to provide these semantics.</p>


role one may benefit from highlighting

patrickhlauke · 2025-09-13T12:53:27Z

techniques/aria/ARIA12.html

 			<h3>Procedure</h3>
 			<ol>
-				<li>Examine each element with the attribute <code class="language-html">role="heading"</code>.</li>
+				<li>Examine each element with the attribute <code>role="heading"</code>.</li>


may benefit from highlighting

patrickhlauke · 2025-09-13T12:54:05Z

techniques/aria/ARIA14.html

+      <p>In some situations, elements can be given the attribute <code>aria-label</code> to provide an accessible name for situations when there is no visible label due to a chosen design approach or layout but the context and visual appearance of the control make its purpose clear.</p>

-      <p>In other situations, elements can be given the attribute <code class="language-html">aria-label</code> to provide an accessible name when the native HTML labeling element is not supported by the control - for example, when a <code class="language-html">div</code> set to <code class="language-html">contentEditable</code> is used instead of native form elements such as <code class="language-html">input type="text"</code> or <code class="language-html">textarea</code> in order to provide a richer text editing experience.</p>
+      <p>In other situations, elements can be given the attribute <code>aria-label</code> to provide an accessible name when the native HTML labeling element is not supported by the control - for example, when a <code>div</code> set to <code>contentEditable</code> is used instead of native form elements such as <code>input type="text"</code> or <code>textarea</code> in order to provide a richer text editing experience.</p>


input type may benefit from highlighting

patrickhlauke · 2025-09-13T12:54:20Z

techniques/aria/ARIA14.html


-            <p>On a page, a link displays a pop-up box (a <code class="language-html">div</code>) with additional information. The 'close' element is implemented as a <code class="language-html">button</code> containing merely the letter 'X'. The property <code class="language-html">aria-label="close"</code> is used to provide an accessible name to the <code class="language-html">button</code>.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;div id="box"&gt;
+            <p>On a page, a link displays a pop-up box (a <code>div</code>) with additional information. The 'close' element is implemented as a <code>button</code> containing merely the letter 'X'. The property <code>aria-label="close"</code> is used to provide an accessible name to the <code>button</code>.</p>


aria-label may benefit from highlighting

patrickhlauke · 2025-09-13T12:55:11Z

techniques/aria/ARIA17.html

-      <p>The group can be labeled using <code class="language-html">aria-labelledby</code>.</p>
-      <p>This technique is not meant for wrapping  all controls on a form within a single container with <code class="language-html">role="group"</code>.</p>
+      <p>The objective of this technique is to mark up a set of related controls within a form  as a group. Any label associated with the group also serves as a common label or qualifier for individual controls in the group. Assistive technologies can indicate the start and end of the group and the group's label as one navigates into and out of the group. This is a viable alternative for grouping form controls programmatically when the user interface's design makes it difficult to employ the <code>fieldset</code> / <code>legend</code> technique (<a href="../html/H71">H71</a>).</p>
+      <p>For a group of radio buttons, one should use <code>role="radiogroup"</code> instead of <code>role="group"</code>.</p>


role ones may benefit from highlighting

patrickhlauke · 2025-09-13T12:55:22Z

techniques/aria/ARIA17.html

+      <p>The objective of this technique is to mark up a set of related controls within a form  as a group. Any label associated with the group also serves as a common label or qualifier for individual controls in the group. Assistive technologies can indicate the start and end of the group and the group's label as one navigates into and out of the group. This is a viable alternative for grouping form controls programmatically when the user interface's design makes it difficult to employ the <code>fieldset</code> / <code>legend</code> technique (<a href="../html/H71">H71</a>).</p>
+      <p>For a group of radio buttons, one should use <code>role="radiogroup"</code> instead of <code>role="group"</code>.</p>
+      <p>The group can be labeled using <code>aria-labelledby</code>.</p>
+      <p>This technique is not meant for wrapping  all controls on a form within a single container with <code>role="group"</code>.</p>


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:11:27Z

techniques/aria/ARIA17.html

         <h3>Social Security Number</h3>
-         <p>Social security number fields which are nine digits long and broken up into three segments can be grouped using <code class="language-html">role="group"</code>.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;div role="group" aria-labelledby="ssn1"&gt;
+         <p>Social security number fields which are nine digits long and broken up into three segments can be grouped using <code>role="group"</code>.</p>


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:11:50Z

techniques/aria/ARIA17.html


-            <p>This example demonstrates use <code class="language-html">role=radiogroup</code>. Note also that the radio buttons are custom controls with <code class="language-html">role=radio</code>. One may optionally employ CSS to place a border around groups of such fields to visually reinforce the group relationship. The CSS properties are available below the form.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;h3&gt;Set Alerts for your Account&lt;/h3&gt;
+            <p>This example demonstrates use <code>role=radiogroup</code>. Note also that the radio buttons are custom controls with <code>role=radio</code>. One may optionally employ CSS to place a border around groups of such fields to visually reinforce the group relationship. The CSS properties are available below the form.</p>


roles may benefit from highlighting

patrickhlauke · 2025-09-13T13:12:10Z

techniques/aria/ARIA17.html

         <ol>
-            <li> Check that the group of logically related input or select elements are contained within an element with <code class="language-html">role=group</code>, or <code class="language-html">role=radiogroup</code> depending on the type of elements the group contains.</li>
-            <li> Check that this group has an accessible name defined using <code class="language-html">aria-label</code> or <code class="language-html">aria-labelledby</code>.</li>
+            <li> Check that the group of logically related input or select elements are contained within an element with <code>role=group</code>, or <code>role=radiogroup</code> depending on the type of elements the group contains.</li>


roles may benefit from highlighting

patrickhlauke · 2025-09-13T13:12:48Z

techniques/aria/ARIA18.html

      <p>Technologies that support <a href="https://www.w3.org/TR/wai-aria/">Accessible Rich Internet Applications (WAI-ARIA)</a>. </p>
   </section><section id="description"><h2>Description</h2>
-      <p>The purpose of this technique is to alert people that an input error has occurred. Using <code class="language-html">role="alertdialog"</code> creates a notification. This notification should be modal with the following characteristics:
+      <p>The purpose of this technique is to alert people that an input error has occurred. Using <code>role="alertdialog"</code> creates a notification. This notification should be modal with the following characteristics:


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:13:06Z

techniques/aria/ARIA18.html


-            <p>This example shows how a notification using <code class="language-html">role="alertdialog"</code> can be used to notify someone they have entered invalid information.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;div role="alertdialog" aria-labelledby="alertHeading"&gt;
+            <p>This example shows how a notification using <code>role="alertdialog"</code> can be used to notify someone they have entered invalid information.</p>


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:13:34Z

techniques/aria/ARIA19.html

      <section class="procedure"><h3>Procedure</h3>
         <ol>
-            <li>Determine that an empty error container <code class="language-html">role=alert</code> or <code class="language-html">aria-live=assertive</code> attribute is present in the DOM at page load.</li>
+            <li>Determine that an empty error container <code>role=alert</code> or <code>aria-live=assertive</code> attribute is present in the DOM at page load.</li>


role and aria-live may benefit from highlighting

patrickhlauke · 2025-09-13T13:13:56Z

techniques/aria/ARIA2.html

      <div class="note">
-         <p>Use of <code class="language-html">aria-required="true"</code> might be beneficial even when an asterisk or other text symbol is programmatically associated with the field as it may reinforce its <code class="language-html">required</code> property for some assistive technology users.</p>
-         <p>The fact that the element is required is often visually presented (such as a sign or symbol after the control). Using the <code class="language-html">aria-required</code> property in addition to the visual presentation makes it much easier for user agents to pass on this important information to the user in a user agent-specific manner. Refer to <a href="https://www.w3.org/TR/html-aria/">ARIA in HTML</a> for information on how to provide WAI-ARIA States and Properties with HTML. WAI-ARIA States and Properties are compatible with other languages as well; refer to documentation in those languages. </p>
+         <p>Use of <code>aria-required="true"</code> might be beneficial even when an asterisk or other text symbol is programmatically associated with the field as it may reinforce its <code>required</code> property for some assistive technology users.</p>


aria-required may benefit from highlighting

patrickhlauke · 2025-09-13T13:14:16Z

techniques/aria/ARIA2.html


-        <p>This example uses custom radio buttons with <code class="language-html">role=radio</code>. The CSS properties are available below the form.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;form&gt;
+        <p>This example uses custom radio buttons with <code>role=radio</code>. The CSS properties are available below the form.</p>


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:14:37Z

techniques/aria/ARIA20.html


-            <p>A section on the home page of a news website that contains a poll that changes every week is marked up with <code class="language-html">role="region"</code>. The <code class="language-html">h3</code> above the form is referenced as the region's name using <code class="language-html">aria-labelledby</code>.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;div role="region" aria-labelledby="pollhead"&gt;
+            <p>A section on the home page of a news website that contains a poll that changes every week is marked up with <code>role="region"</code>. The <code>h3</code> above the form is referenced as the region's name using <code>aria-labelledby</code>.</p>


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:14:53Z

techniques/aria/ARIA20.html


-            <p>A user can expand links on a bank website after logging in to see details of term deposit accounts. The details are within a <code class="language-html">span</code> marked up with <code class="language-html">region</code> role. The heading for the region has <code class="language-html">role=heading</code> and is included in the <code class="language-html">aria-labelledby</code> that names the region.</p>
-<pre xml:space="preserve"><code class="language-html">&lt;ol&gt;
+            <p>A user can expand links on a bank website after logging in to see details of term deposit accounts. The details are within a <code>span</code> marked up with <code>region</code> role. The heading for the region has <code>role=heading</code> and is included in the <code>aria-labelledby</code> that names the region.</p>


role may benefit from highlighting

patrickhlauke · 2025-09-13T13:15:09Z

techniques/aria/ARIA20.html

   </section><section id="tests"><h2>Tests</h2>
      <section class="procedure"><h3>Procedure</h3>
-         <p>For each section marked up with <code class="language-html">role="region"</code>:</p>
+         <p>For each section marked up with <code>role="region"</code>:</p>


role may benefit from highlighting

techniques/aria/ARIA21.html

This reverts commit e33ab7c. I indicated in the PR description why I intentionally did not change these.

This reverts commit c1b0821.

This reverts commit 64d99a6.

This reverts commit 603796e.

This reverts commit a31d8fc.

This reverts commit 053cf5d. (Java shouldn't be highlighted because we don't have the syntax installed for it)

This reverts commit 1247a8e. (Java shouldn't be highlighted because we don't have the syntax installed for it)

This reverts commit fe917ab. (I had intentionally removed these, because our highlight.js instance does not have syntax highlighting for the relevant languages)

This reverts commit 6ab4af6. (I had intentionally left these alone, because our highlight.js instance does not have the relevant languages and these techniques are obsolete)

And a few other fixes related to Patrick's edits

patrickhlauke · 2025-09-15T12:25:16Z

out of interest then ... why do we have those naked <pre>s ? they do contain code, so semantically they should have <code> wrappers?

kfranqueiro · 2025-09-15T12:28:47Z

@patrickhlauke I backed out a few of your changes, as some of them contradicted changes I intentionally did not make:

A few instances of class="language-html" are required, otherwise highlight.js incorrectly guesses CSS (as per the "Most ..." bullet in my PR description)
I intentionally did not touch Flash or Silverlight techniques both because they're obsolete and because our instances of highlight.js does not include support for e.g. ActionScript and C#. I left the SVR examples unhighlighted for the latter reason as well. (I really thought I'd left a note about this in my description but I don't see it there - edit: oops, I was thinking of my remark at the end of the description of Converge on default pre > code highlight.js usage #4604)

I've looked through some of your comments RE instances where syntax highlighting inline code tags may be useful. My suspicion is that in the majority of those cases, there won't be enough context for highlight.js to highlight properly even if we do specify language (e.g. role="foo" is an attribute inside of a tag, but the tag does not exist). I will test to see what happens...

Edit: I am also adding to my to-do list to investigate updating our build of highlight.js to support the languages I mention above that weren't in ours, in which case I can test un-reverting Patrick's Flash/Silverlight/SVR changes, either here or in a separate branch (because I am wary of increasing the scope of this PR).

kfranqueiro · 2025-09-15T14:07:12Z

I've performed some testing with regard to highlighting inline <code> elements:

HTML tag names without angle brackets, or attribute keys/values out-of-context, will not be accurately highlighted, even when language is forced to HTML
Entire HTML tags can be highlighted, but typically require explicit class="language-html"
JavaScript variables or function invocations (with () at the end) can be highlighted, but typically require explicit class="javascript"
- Note that function invocations will end up highlighted a different color than standalone variable names, which may look confusing out-of-context

As an example of the first bullet, see how every <code> element in this paragraph is the same color regardless of its content, even though they have class="language-html", because highlight.js doesn't find anything meaningful to latch onto:

The vast majority of cases of inline <code> tags involve a single word or key=value phrase. Even disregarding whether it is highlighted correctly, the addition of color will be negligible at best or confusing at worst. I have to figure there are reasons why highlight.js defaults to only focusing on full code blocks, and that its shipped styles are specifically designed only for that case.

I would much rather move ahead with removing classes from inline code tags to clean them up, than add highlight.js processing to them which opens a new can of worms with significant maintenance overhead. (Reminder: the cleanup causes no visual difference with what is currently published.)

If you're curious, here's a full list of inline code tags' contents and classes currently found on the main branch. (Note that a few of the longer instances are actually <p><code>, which are better off as <pre><code>; Patrick identified a few of those when he looked at this PR, and I will take another pass at that.)

patrickhlauke · 2025-09-15T14:23:05Z

@kfranqueiro

intentionally did not touch Flash or Silverlight techniques both because they're obsolete and because our instances of highlight.js does not include support for e.g. ActionScript and C#. I left the SVR examples unhighlighted for the latter reason as well.

sure but semantically, those are code blocks, not just "there's some random preformatted content here, dunno". so from a markup point of view, regardless of highlighting or not, i feel like they should be wrapped in <code> (and yes, not that it makes a huge difference in practice, but just feels wrong not to)

patrickhlauke · 2025-09-15T14:24:48Z

and sure, the cases where there's methods/attributes with ="..." values etc probably don't really really need highlighting, happy to live with them not being highlighted. this was more a lengthy futile exercise in "but what IF we wanted to go for highlighting"

kfranqueiro · 2025-09-15T14:43:36Z

sure but semantically, those are code blocks, not just "there's some random preformatted content here, dunno". so from a markup point of view, regardless of highlighting or not, i feel like they should be wrapped in <code> (and yes, not that it makes a huge difference in practice, but just feels wrong not to)

From the perspective of functional repercussions of highlight.js, we effectively have 2 options for cases that should not get syntax highlighting:

Wrap in <pre><code> but then also add class="no-highlight" so that highlight.js processes it but doesn't (incorrectly) syntax highlight it
Leave without <code> so that highlight.js does not process it at all

In the case of #4604, the <code> elements I'd removed were specifically in text techniques and instances of plain (non-code) text formatting, so I suppose in those cases the removal ends up semantically making sense. I see your point RE the "unsupported syntax" cases, so I'll pull further on those threads to see if we can instead update to support them properly, and then add back your commits. (I'm going to want to do a before/after using the Playwright script I posted above to check for any other unintended auto-detection changes.)

Sorry for initially yanking them this morning - I was trying to preserve the intended scope of this PR. I might still argue not to bother touching up the fully-obsolete Flash and Silverlight pages, but I will at least do an initial test as it relates to the server-side script techniques.

And thanks for poking around on the inline cases - indeed that bit was an experiment for the both of us.

patrickhlauke · 2025-09-15T14:47:17Z

nah, all good. i think i fell down too much of a rabbithole on saturday and should have checked first before barging in all over your PR :)

kfranqueiro · 2025-09-18T15:20:53Z

I am planning to re-do this and split it into separate PRs:

PR 4621: Remove classes from inline code elements because they provide no benefit (see comment above; no visible changes)
- PR 4623 based on the above: Apply Patrick's phrasing changes to code elements (changes prose content, should be reviewed by TF/WG)
PR 4624: Fix incorrect hljs override classes pointed out in this PR's description (changes syntax highlighting in a few code blocks)
PR 4627: Add missing hljs override classes to <pre><code> instances, and fix any <p><code>...</code></p> or <pre>-only instances that should be <pre><code> (changes/adds syntax highlighting to a few code blocks)
- Within the same PR: update our hljs bundle to include missing languages that we reference (excluding C# and ActionScript, as there's no point in bloating the bundle only for obsolete Flash/SL techniques, which currently don't run through highlight.js)
PR: Remove xml:space="preserve" from pre elements (no visual changes)
- Wait until all of the above land before doing this

The most notable change from this PR to the sequence I just outlined is that I will not be removing classes from <code> inside <pre>, but rather adding it where it is missing or correcting it where it is wrong. When I tested upgrading highlight.js and/or expanding the languages it supports, I noticed many autodetect outcomes shift, which has me thinking we are better off erring on the safe side for future upgrades by specifying syntax, which we have already been doing in the majority of cases.

bruce-usab · 2025-09-19T18:34:01Z

Discussed on TF call 9/19/2025.

This removes classes from `code` elements that appear inline within prose. These classes have no effect, and based on local testing, it would be unrealistic to expect highlight.js to provide meaningful syntax highlighting in the vast majority of these cases due to insufficient context. See #4611 (comment) for more details. I have looked over this changeset and also ran screenshot diffs; this causes no visible changes.

This fixes instances where we had specified the wrong `language-...` class in `<pre><code class="...">`, causing highlight.js to highlight code incorrectly. (Originally fixed/reported in #4611, which is being split up and closed)

kfranqueiro added 2 commits September 12, 2025 05:06

Remove unnecessary class attributes from code elements

5fb4aa6

Remove xml:space attribute from pre elements

8240680

kfranqueiro added the Bug Fixes label Sep 12, 2025

kfranqueiro self-assigned this Sep 12, 2025

mbgower requested a review from patrickhlauke September 12, 2025 15:32

patrickhlauke reviewed Sep 13, 2025

View reviewed changes

techniques/aria/ARIA21.html Outdated Show resolved Hide resolved

patrickhlauke reviewed Sep 13, 2025

View reviewed changes

techniques/aria/ARIA21.html Outdated Show resolved Hide resolved

patrickhlauke reviewed Sep 13, 2025

View reviewed changes

techniques/aria/ARIA21.html Outdated Show resolved Hide resolved

patrickhlauke and others added 11 commits September 13, 2025 20:00

Update understanding/20/language-of-parts.html

2b63616

Revert "Fix naked <pre> blocks in flash techniques"

de0aaf0

This reverts commit e33ab7c. I indicated in the PR description why I intentionally did not change these.

Revert "Update techniques/flash/FLASH1.html"

094f535

This reverts commit c1b0821.

Revert "Update techniques/flash/FLASH1.html"

4e09e72

This reverts commit 64d99a6.

Revert "Update techniques/flash/FLASH1.html"

81683f2

This reverts commit 603796e.

Revert "Update techniques/flash/FLASH1.html"

2e1d68f

This reverts commit a31d8fc.

Revert "Update techniques/failures/F58.html"

520497f

This reverts commit 053cf5d. (Java shouldn't be highlighted because we don't have the syntax installed for it)

Revert "Update techniques/failures/F58.html"

06e7428

This reverts commit 1247a8e. (Java shouldn't be highlighted because we don't have the syntax installed for it)

Revert "Fix naked <pre> in server-side techniques"

5cd7884

This reverts commit fe917ab. (I had intentionally removed these, because our highlight.js instance does not have syntax highlighting for the relevant languages)

Revert "Fix naked <pre> blocks for Silverlight techniques"

2ab842b

This reverts commit 6ab4af6. (I had intentionally left these alone, because our highlight.js instance does not have the relevant languages and these techniques are obsolete)

Restore class="language-html" that I had intentionally not removed

87f8f56

And a few other fixes related to Patrick's edits

Remove remaining xml:space instances with newlines

65c7e2c

Fix syntax of first meta http-equiv in F40

9c3f45d

Fix code blocks in G208/G211

9434d3c

This was referenced Sep 18, 2025

Remove unnecessary classes from inline code tags #4621

Merged

Rephrase inline code elements #4623

Open

Fix incorrect highlight.js overrides #4624

Merged

kfranqueiro closed this Sep 19, 2025

kfranqueiro mentioned this pull request Sep 19, 2025

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

Merged

Remove unnecessary code class and pre xml:space attributes from informative docs #4611

Remove unnecessary code class and pre xml:space attributes from informative docs #4611

Uh oh!

Conversation

kfranqueiro commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How I determined where language-* classes were required

Uh oh!

netlify bot commented Sep 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for wcag2 ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

patrickhlauke commented Sep 15, 2025

Uh oh!

kfranqueiro commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kfranqueiro commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

patrickhlauke commented Sep 15, 2025

Uh oh!

patrickhlauke commented Sep 15, 2025

Uh oh!

kfranqueiro commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

patrickhlauke commented Sep 15, 2025

Uh oh!

kfranqueiro commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bruce-usab commented Sep 19, 2025

Uh oh!

Uh oh!

kfranqueiro commented Sep 12, 2025 •

edited

Loading

netlify bot commented Sep 12, 2025 •

edited

Loading

kfranqueiro commented Sep 15, 2025 •

edited

Loading

kfranqueiro commented Sep 15, 2025 •

edited

Loading

kfranqueiro commented Sep 15, 2025 •

edited

Loading

kfranqueiro commented Sep 18, 2025 •

edited

Loading