Skip to content
All posts

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

CheckTool
Broken links & anchorsLink checker
Image alt text & pathsImage audit
MDX syntaxMDX validator
Every URL in a docURL extractor
Smart quotes & whitespaceTypography cleaner
Overall qualityREADME health score

The link checker audits every link and image in a document:

  • Broken internal anchors — #section links 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:

  1. Links — link checker (fix broken anchors and 404s).
  2. Images — image audit (add missing alt text).
  3. MDX (if applicable) — MDX validator.
  4. Typography — typography cleaner.
  5. 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:

CheckEndpoint
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.

Quick reference

CheckTool
Linkslink checker
Imagesimage audit
MDXMDX validator
URLsURL extractor
Typographytypography cleaner
OverallREADME 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.