Audit Markdown Quality: Links, Images, MDX & a Health Score (2026)
A tutorial for auditing Markdown quality — catch broken links and missing alt text, validate MDX before builds fail, extract every URL, and roll it all into a single README health score.
Writing Markdown is easy; keeping it correct is the hard part. Links rot, images lose their alt text, MDX breaks the build, and READMEs drift from "great" to "good enough" to "neglected." This tutorial covers the audit & quality tool group — a quality-control bench that catches problems before your readers (or your CI) do.
The audit toolkit
| Check | Tool |
|---|---|
| Broken links & anchors | Link checker |
| Image alt text & paths | Image audit |
| MDX syntax | MDX validator |
| Every URL in a doc | URL extractor |
| Smart quotes & whitespace | Typography cleaner |
| Overall quality | README health score |
Part 1: Link integrity
The link checker audits every link and image in a document:
- Broken internal anchors —
#sectionlinks that don't match any heading. - Empty targets —
[text]()with no URL. - Malformed mailto links.
- Missing alt text on images.
- Optionally pings external URLs to find 404s.
Run it before every publish. Broken links are the most common — and most visible — Markdown quality failure. For just the URLs (no validation), the URL extractor pulls every link as a list, CSV, or JSON, handy for building a link inventory or feeding a separate checker.
Part 2: Image accessibility
The image audit lists every image with:
- Its alt text (or a flag if missing).
- Its source type — external URL, relative path, or data URI.
- Duplicate detection for repeated images.
Missing alt text is both an accessibility failure and an SEO miss. External image sources are a link-rot risk (the host may disappear); data URIs bloat your document. The audit surfaces all three in one view. See the images guide for alt-text best practices.
Part 3: MDX validation
If you use MDX (Markdown + JSX, common in Next.js, Docusaurus, Astro), a single unclosed tag breaks the whole build. The MDX validator catches:
- Unclosed JSX tags.
- Missing component imports.
- Unbalanced expression braces
{ }.
Validate before you commit, and a red build over a typo becomes a thing of the past. This complements the frontmatter editor for the YAML half of MDX files.
Part 4: Typography cleanup
Content pasted from Word, Google Docs, or email carries smart quotes, em dashes, ellipses, and invisible whitespace. The typography cleaner normalizes (or, if you prefer, adds) typographically correct characters — important because a smart quote inside a code span or URL silently breaks it.
Part 5: The README health score
The README health score rolls multiple checks into one 0–100 grade with a letter:
- Heading hierarchy (from the heading audit)
- GFM compliance (from the GFM checklist)
- Image alt text
- Link integrity
- Task completion
It's the single number to track over time. A repo's README is its front page — a low score is the first thing a potential contributor or customer notices.
A complete quality gate
Before publishing or merging docs, run this audit pass:
- Links — link checker (fix broken anchors and 404s).
- Images — image audit (add missing alt text).
- MDX (if applicable) — MDX validator.
- Typography — typography cleaner.
- Score — README health score (require a minimum grade).
Automating the audit in CI
Every check maps to an endpoint, so you can enforce quality on every PR:
| Check | Endpoint |
|---|---|
| Links | /api/v1/extract/links |
| Images | /api/v1/extract/images |
| URLs | /api/v1/extract/urls |
| GFM | /api/v1/audit/gfm |
| Headings | /api/v1/audit/headings |
| README score | /api/v1/audit/readme-score |
Gate your PRs on a minimum README score and zero broken links — the full setup is in Lint Markdown in CI and linting on pull requests.
score=$(curl -sf -X POST https://trymarkdownviewer.com/api/v1/audit/readme-score \
-H "Authorization: Bearer $MDV_API_KEY" -H "Content-Type: application/json" \
-d "$(jq -Rs '{markdown: .}' < README.md)" | jq '.data.score')
[ "$score" -ge 80 ] || { echo "README score $score < 80"; exit 1; }
Common mistakes
1. Publishing without a link check. Broken links are the most visible quality failure.
2. Images with no alt text. Fails accessibility and SEO — audit every image.
3. Committing MDX blind. One unclosed tag breaks the build — validate first.
4. Smart quotes in code/URLs. They silently break things — clean typography.
5. No quality metric. Track the README score so quality is measurable, not a guess.
Related articles
- Markdown images guide — alt-text best practices
- Lint Markdown in CI — enforce quality on PRs
- Format & clean up tutorial
- GitHub README guide — what a great README needs
- Analyze & extract tutorial
Quick reference
| Check | Tool |
|---|---|
| Links | link checker |
| Images | image audit |
| MDX | MDX validator |
| URLs | URL extractor |
| Typography | typography cleaner |
| Overall | README health score |
Quality doesn't happen by accident. Run the audit tools before every publish — and the API versions in CI — so broken links, missing alt text, and MDX typos are caught automatically. Track the README score and watch your docs quality become a number that goes up.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
A tutorial on bridging Markdown to and from other markup formats — Atlassian Confluence/Jira wiki markup, forum BBCode, AsciiDoc, and reStructuredText — with migration tips and gotchas.
A tutorial on Markdown as a data format — convert JSON to tables or lists, sort and transpose tables, extract every code block as a file, and track task-list progress for content pipelines.
A tutorial on adding diagrams and equations to Markdown using ready-made libraries — browse and copy Mermaid templates and KaTeX/LaTeX equations, then validate them before you commit.