Markdown Image Audit
Audit every image in a Markdown file — alt text, duplicates, path style
List every image reference with its alt text, line number, and source type. Spot missing alt, duplicated URLs, oversized data URIs, and mixed absolute / relative paths before you publish.
6
Total
2
Missing alt
2
External
3
Relative
1
Data URI
2
Duplicates
| Line | Alt | Kind | URL |
|---|---|---|---|
| L3 | Logo | external | https://example.com/logo.png |
| L4 | missing | relative | missing-alt.png |
| L5 | Diagram | relative | /static/diagram.png |
| L6 | Repeated image | external | https://example.com/logo.png |
| L7 | Inline base64 | data | data:image/png;base64,abc |
| L8 | missing | ref | (ref: ref-style) |
How to use the image auditor
- Paste Markdown or open a
.mdfile. - Read the summary cards — total images, how many lack alt text, how they're sourced, and how many duplicates exist.
- Use the filter pills to narrow to missing alt, external only, relative only, or data URIs.
- Fix issues in your editor and re-paste.
What gets flagged
| Issue | Why it matters |
|---|---|
| Missing alt text | Accessibility + SEO. Screen readers skip image. |
| Duplicate URLs | Often a copy-paste accident; consolidate refs. |
Data URIs (data:image/png;base64,...) | Bloat document size; consider hosting instead. |
| Mixed absolute / relative paths | Breaks when moving files; pick one style. |
Why accessibility matters even for engineers
A README isn't just public-facing copy — it's the entry point for new contributors, customers, and search engines. A screen-reader user reading "image", "image", "image" instead of "Architecture diagram", "Build status", "Logo" can't tell if they're missing crucial context. Alt text takes 30 seconds and dramatically improves the experience.
Companion tools
- Markdown Link Checker — verifies link and anchor integrity alongside images.
- GFM Compliance Checklist — single-page pre-publish gate.
- README Health Score — aggregate score combining link, image, and heading audits.
Privacy & data
The audit runs inside your browser. We don't upload or log image URLs or document content.
Frequently asked questions
- Missing alt text breaks screen readers, hurts accessibility audits, and leaves a blank space when images fail to load. Duplicate URLs and inconsistent path styles (some absolute, some relative) cause broken links after restructuring. An image audit surfaces all of this in one place.
- External — `https://…` URL. Relative — a path inside the project (`/images/foo.png` or `./diagram.png`). Data — an inline base64 data URI. Ref — a reference-style image (`![alt][ref]`) whose definition is elsewhere in the document.
- It detects the syntax, not the disk. Use the [Markdown Link Checker](/tools/markdown-link-checker) to attempt external pings. Local file existence is best verified by your build pipeline.
- Yes. Screen readers read alt text in place of the image. Search engines use it as a strong signal for image search ranking. Browsers fall back to alt text when an image fails to load. Three audiences, one fix.
- Describe what the image conveys, not what it looks like. For decorative images, leave alt empty intentionally with `![]()` so screen readers skip it (still allowed by WCAG when context makes it obvious). For informational images, keep alt under 125 characters.
- No. The audit is a small parser that runs inside your browser tab.