Andreas/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2025-09-22 05:40:48 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

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

Browse source
This commit is contained in:
David Anson 2025-04-27 18:42:25 -07:00
parent faf96d513b
commit b611eba684
7 changed files with 70 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc-build/md045.md
View file

@ -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

10
doc/Rules.md
View file

@ -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

10
doc/md045.md
View file

@ -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

4
lib/md045.mjs
View file

@ -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,

12
test/no-alt-text.md
View file

@ -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

28
test/snapshots/markdownlint-test-scenarios.mjs.md
View file

@ -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␊

BIN
test/snapshots/markdownlint-test-scenarios.mjs.snap
View file

Binary file not shown.