MD045 - Add Descriptive Text to Images¶

Aliases: no-alt-text

What this rule does¶

Ensures all images include alternative text (alt text) that describes the image content for accessibility and fallback display.

Why this matters¶

Accessibility: Screen readers need alt text to describe images to visually impaired users
Broken images: Alt text displays when images fail to load
SEO benefits: Search engines use alt text to understand and index images
Professional quality: Missing alt text looks like an oversight

Examples¶

✅ Correct¶

![Company logo](images/logo.png)

![Graph showing 40% increase in sales](charts/q4-sales.png)

![Screenshot of the login page with username and password fields](screenshots/login.png)

![Team photo from the 2024 company retreat](photos/team-retreat-2024.jpg)

❌ Incorrect¶

![](images/logo.png)                <!-- Empty alt text -->

![ ](charts/q4-sales.png)           <!-- Just spaces -->

![  ](screenshots/login.png)        <!-- Still just spaces -->

![](photos/team-retreat-2024.jpg)   <!-- No description at all -->

No automatic fix¶

This rule is diagnostic-only and does not offer auto-fix. Meaningful alt text requires human judgment — automated placeholders are harmful for accessibility because screen readers would read fabricated text to users.

Writing good alt text¶

Be concise but descriptive
Describe the content, not just "image of..."
Include relevant data from charts or graphs
Mention important text shown in screenshots

Special cases¶

Decorative images might use empty alt text in HTML, but Markdown requires some text
The rule only checks Markdown image syntax, not HTML <img> tags
Reference-style images are also checked

Learn more¶

MD033 - Control HTML usage in Markdown
MD042 - Avoid empty links
MD052 - Validate reference links and images