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¶
❌ Incorrect¶
 <!-- Empty alt text -->
 <!-- Just spaces -->
 <!-- Still just spaces -->
 <!-- No description at all -->
🔧 Fixed¶
 <!-- Default placeholder added -->
 <!-- Needs meaningful description -->
 <!-- Needs meaningful description -->
 <!-- Needs meaningful description -->
Configuration¶
Options¶
- placeholder-text (default:
"TODO: Add image description") - The text to insert when fixing images with missing alt text. You can customize this to match your team's conventions.
Example custom configuration¶
This would change the fix behavior to:
Automatic fixes¶
When enabled, this rule will:
- Add generic "Image" text for missing alt text
- You must replace this with meaningful descriptions
- Consider what information the image conveys
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