Update MD045/no-alt-text to allow violations when an HTML IMG has aria-hidden set to true (fixes #1576).

doc-build/md045.md

@@ -1,4 +1,4 @@
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -23,12 +23,20 @@ Or with HTML as:
 <img src="image.jpg" alt="Alternate text" />
 ```
 
+Note: If the [HTML `aria-hidden` attribute][aria-hidden] is used to hide the
+image from assistive technology, this rule does not report a violation:
+
+```html
+<img src="image.jpg" aria-hidden="true" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 
 Rationale: Alternate text is important for accessibility and describes the
 content of an image for people who may not be able to see it.
 
+[aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
 [phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
 [w3c]: https://www.w3.org/WAI/alt/
 [wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

doc/Rules.md

@@ -1908,7 +1908,7 @@ Tags: `accessibility`, `images`
 
 Aliases: `no-alt-text`
 
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -1933,12 +1933,20 @@ Or with HTML as:
 <img src="image.jpg" alt="Alternate text" />
 ```
 
+Note: If the [HTML `aria-hidden` attribute][aria-hidden] is used to hide the
+image from assistive technology, this rule does not report a violation:
+
+```html
+<img src="image.jpg" aria-hidden="true" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 
 Rationale: Alternate text is important for accessibility and describes the
 content of an image for people who may not be able to see it.
 
+[aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
 [phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
 [w3c]: https://www.w3.org/WAI/alt/
 [wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

doc/md045.md

@@ -4,7 +4,7 @@ Tags: `accessibility`, `images`
 
 Aliases: `no-alt-text`
 
-This rule is triggered when an image is missing alternate text (alt text)
+This rule reports a violation when an image is missing alternate text (alt text)
 information.
 
 Alternate text is commonly specified inline as:
@@ -29,12 +29,20 @@ Or with HTML as:
 <img src="image.jpg" alt="Alternate text" />
 ```
 
+Note: If the [HTML `aria-hidden` attribute][aria-hidden] is used to hide the
+image from assistive technology, this rule does not report a violation:
+
+```html
+<img src="image.jpg" aria-hidden="true" />
+```
+
 Guidance for writing alternate text is available from the [W3C][w3c],
 [Wikipedia][wikipedia], and [other locations][phase2technology].
 
 Rationale: Alternate text is important for accessibility and describes the
 content of an image for people who may not be able to see it.
 
+[aria-hidden]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
 [phase2technology]: https://www.phase2technology.com/blog/no-more-excuses
 [w3c]: https://www.w3.org/WAI/alt/
 [wikipedia]: https://en.wikipedia.org/wiki/Alt_attribute

lib/md045.mjs

@@ -5,6 +5,7 @@ import { getHtmlTagInfo, getDescendantsByType } from "../helpers/micromark-helpe
 import { filterByTypesCached } from "./cache.mjs";
 
 const altRe = getHtmlAttributeRe("alt");
+const ariaHiddenRe = getHtmlAttributeRe("aria-hidden");
 
 /** @type {import("markdownlint").Rule} */
 export default {
@@ -40,7 +41,8 @@ export default {
         htmlTagInfo &&
         !htmlTagInfo.close &&
         (htmlTagInfo.name.toLowerCase() === "img") &&
-        !altRe.test(text)
+        !altRe.test(text) &&
+        (ariaHiddenRe.exec(text)?.[1].toLowerCase() !== "true")
       ) {
         const range = [
           startColumn,

test/no-alt-text.md

@@ -68,6 +68,18 @@ Uppercase image tag with no alt set <IMG SRC="cat.png" /> {MD045}
   <img src="image.png" /> {MD045}
 </p>
 
+No alt attribute is okay when the image is hidden from assistive technology:
+<img src="image.png" aria-hidden="true"/>
+<img src="image.png" ARIA-HIDDEN="TRUE" />
+
+But not when disabled: <img src="image.png" aria-hidden="false"/> {MD045}
+
+Multi-line image tag aria-hidden:
+<img
+  src="image.png"
+  aria-hidden="true"
+  />
+
 <!-- markdownlint-restore no-inline-html -->
 
 [notitle]: image.jpg

test/snapshots/markdownlint-test-scenarios.mjs.md

@@ -42681,6 +42681,22 @@ Generated by [AVA](https://avajs.dev).
             'no-alt-text',
           ],
         },
+        {
+          errorContext: null,
+          errorDetail: null,
+          errorRange: [
+            24,
+            42,
+          ],
+          fixInfo: null,
+          lineNumber: 75,
+          ruleDescription: 'Images should have alternate text (alt text)',
+          ruleInformation: 'https://github.com/DavidAnson/markdownlint/blob/v0.0.0/doc/md045.md',
+          ruleNames: [
+            'MD045',
+            'no-alt-text',
+          ],
+        },
       ],
       fixed: `# Images with and without alternate text␊
       ␊
@@ -42752,6 +42768,18 @@ Generated by [AVA](https://avajs.dev).
         <img src="image.png" /> {MD045}␊
       </p>␊
       ␊
+      No alt attribute is okay when the image is hidden from assistive technology:␊
+      <img src="image.png" aria-hidden="true"/>␊
+      <img src="image.png" ARIA-HIDDEN="TRUE" />␊
+      ␊
+      But not when disabled: <img src="image.png" aria-hidden="false"/> {MD045}␊
+      ␊
+      Multi-line image tag aria-hidden:␊
+      <img␊
+        src="image.png"␊
+        aria-hidden="true"␊
+        />␊
+      ␊
       <!-- markdownlint-restore no-inline-html -->␊
       ␊
       [notitle]: image.jpg␊