MD045 - Add Descriptive Text to Images
August 5, 2026 · View on GitHub
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 -->
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
- Wiki embeds (
![[image.png]],![[note]]) are not checked. The syntax has no alt-text slot:![[note]]transcludes the target's content, and the pipe in![[image.png|300]]sets the rendered dimensions, not a description - Image syntax inside a template shortcode tag (
{{% note  %}}) is not checked. It is a parameter the template reads, not an image the document emits, so there is no alt-text slot to fill