Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MD045 - Images Should Have Alt Text

Images should have alternate text (alt text).

Why This Rule Exists

Alt text is essential for accessibility. Screen readers use it to describe images to visually impaired users. It also displays when images fail to load.

Examples

Incorrect

![](image.png)

![][logo]

[logo]: logo.png

Correct

![Screenshot of the dashboard](image.png)

![Company logo][logo]

[logo]: logo.png "Company Logo"

Good Alt Text

![Bar chart showing sales growth from 2020 to 2024](sales-chart.png)

![Red error icon indicating a failed operation](error-icon.svg)

Configuration

This rule has no configuration options.

When to Disable

  • Decorative images that don't convey information
  • Documents where images are supplementary

Rule Details

  • Rule ID: MD045
  • Aliases: no-alt-text
  • Category: Images
  • Severity: Warning
  • Auto-fix: Yes (adds placeholder alt text)

Writing Good Alt Text

Image TypeAlt Text Approach
InformativeDescribe the content and purpose
DecorativeUse empty alt !["](decorative.png)
ChartsSummarize the data shown
ScreenshotsDescribe what the screenshot shows
IconsDescribe the action or meaning

Accessibility Standards

This rule helps comply with:

  • WCAG 2.1 Success Criterion 1.1.1 (Non-text Content)
  • Section 508 accessibility requirements
  • MD033 - No inline HTML
  • MD052 - Reference links and images