Markdown Linting on Pull Requests: Pre-commit to CI Gate (2026)
A layered strategy for catching Markdown problems — editor checks, a pre-commit hook, and a CI gate on every PR — so broken headings, dead links, and bad tables never reach main.
The best place to catch a Markdown problem is before it's written; the second best is before it's committed; the worst is after it's merged. A good linting strategy uses all three layers — editor, pre-commit, and CI — so each one catches what the previous missed, and nothing broken reaches main.
This guide lays out that layered approach with concrete, copy-paste setups, and explains what to lint (and what to ignore) on pull requests.
The three layers
| Layer | When | Catches | Cost of a miss |
|---|---|---|---|
| Editor | As you type | Obvious structure issues | Low |
| Pre-commit hook | Before commit | Most issues, fast | Low |
| CI on PR | On every push | Everything, enforced | High (blocks merge) |
Editor and pre-commit are advisory and fast; CI is the enforced gate. You want all three because contributors skip hooks (--no-verify), and CI is the only layer you fully control.
What to lint on a pull request
Focus on portability and correctness, not style nitpicks that start arguments:
| Check | Why it matters | Tool / API |
|---|---|---|
| Heading hierarchy | One H1, no skipped levels — SEO & a11y | heading audit / /audit/headings |
| GFM compliance | Fence languages, table parse | GFM checklist / /audit/gfm |
| General lint | Bullets, blank lines, trailing space | /validate |
| Broken links | Dead internal/external URLs | link checker / /extract/links |
| Missing alt text | Accessibility | image audit / /extract/images |
| README quality | First impression of the repo | README score / /audit/readme-score |
Severity discipline: gate the PR on error/warning; let info (e.g., bullet-character style) through as suggestions. Blocking merges on cosmetic rules trains people to ignore the linter.
Layer 1: Editor checks
Give authors instant feedback before they commit. The fastest path with no setup is the browser tools:
- Paste a draft into the GFM checklist for a compliance pass.
- Run the heading audit to catch skipped levels.
- Use the link checker for dead links and missing alt text.
Writing in VS Code? Add a Markdown lint extension so problems underline as you type.
Layer 2: Pre-commit hook
Stop issues from entering history. A simple hook validates staged Markdown via the validate API before each commit.
Create .git/hooks/pre-commit (or manage it with the pre-commit framework / Husky):
#!/usr/bin/env bash
set -euo pipefail
staged=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(md|markdown)$' || true)
[ -z "$staged" ] && exit 0
fail=0
for f in $staged; do
resp=$(curl -sf -X POST https://trymarkdownviewer.com/api/v1/validate \
-H "Authorization: Bearer $MDV_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -Rs '{markdown: .}' < "$f")")
issues=$(echo "$resp" | jq -r --arg f "$f" '
.data.issues[] | select(.severity!="info")
| "\($f):\(.line) [\(.rule)] \(.message)"')
if [ -n "$issues" ]; then echo "$issues"; fail=1; fi
done
[ "$fail" -eq 0 ] || { echo "✗ Fix Markdown issues or commit with --no-verify"; exit 1; }
Make it executable: chmod +x .git/hooks/pre-commit. Export MDV_API_KEY in your shell profile.
Reality check: hooks are local and skippable. They reduce noise but are not your enforcement layer — CI is.
Layer 3: CI gate on the PR
This is the enforced layer. The complete, annotated GitHub Actions workflow — diffing changed files, emitting inline annotations, and failing the build — is in the dedicated guide:
➡️ Lint Markdown in CI with a GitHub Action + Validate API
The essentials:
- Trigger only on
**/*.mdchanges. - Validate changed files only (diff base...head).
- Emit
::error file=…,line=…annotations. - Fail on
warning/error; mark the check required in branch protection.
Layered CI: validate + audit
A robust PR gate chains several checks:
# 1. Lint changed files
curl ... /api/v1/validate
# 2. GFM compliance on changed files
curl ... /api/v1/audit/gfm
# 3. README score (only if README changed)
curl ... /api/v1/audit/readme-score # require >= 70
Run them as separate steps so a failure tells the contributor which check failed.
Handling false positives and exceptions
- Generated files (changelogs, API docs): exclude via the workflow
paths-ignore:or a path filter in your diff command. - Intentional rule breaks: if a file legitimately needs, say, multiple H1s, narrow the gate by
ruleid rather than disabling linting wholesale. - Vendored docs: skip third-party Markdown you don't own.
Because every issue carries a stable rule id, you can select(.rule != "consistent-bullets") to mute a single noisy rule without losing the rest.
Measuring impact
After a month, you should see fewer "fix typo in docs" follow-up PRs and a higher README health score trend. Track it: run the readme-score API on main weekly and chart the number — docs quality becomes a metric, not a vibe.
Common mistakes
1. CI-only, no pre-commit. Every issue becomes a failed build and a re-push. A pre-commit hook shortens the loop.
2. Pre-commit-only, no CI. Hooks are skippable. Without a required CI check, broken docs still merge.
3. Blocking on cosmetic rules. Gate on warning/error; demote style rules to info.
4. Linting unchanged files. Diff against the base so PRs only fail on what they touched.
5. No README threshold. The README is the repo's front page — gate it with a minimum score.
Related articles
- Lint Markdown with a GitHub Action — the full CI workflow
- Docs-as-code guide — the broader workflow
- LLM Markdown output validation — validating AI-generated docs
- GitLab Markdown guide — GLFM + GitLab CI
- Validate API reference
Quick reference
| Layer | Setup | Enforced? |
|---|---|---|
| Editor | Browser tools / VS Code ext | No |
| Pre-commit | pre-commit hook + validate API | No (skippable) |
| CI on PR | GitHub Action + required check | Yes |
Catch Markdown problems early and enforce them late. Editor and pre-commit keep the feedback loop tight; a required CI gate on every PR is what actually keeps main clean. Layer all three and your docs stay healthy without anyone policing them by hand.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
A complete, copy-paste GitHub Action that lints changed Markdown on every pull request using the Markdown Viewer validate API — fail builds on real issues, annotate the diff, and keep docs clean.
Ship documentation from Git with Markdown — repo structure, Hugo, Docusaurus, MDX, review workflows, CI linting, API automation, and patterns documentation teams use at scale.
Master GitLab Flavored Markdown — issues, merge requests, wikis, task lists, Mermaid, math, cross-references, alerts, and differences from GitHub GFM.