Skip to content
All posts

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

LayerWhenCatchesCost of a miss
EditorAs you typeObvious structure issuesLow
Pre-commit hookBefore commitMost issues, fastLow
CI on PROn every pushEverything, enforcedHigh (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:

CheckWhy it mattersTool / API
Heading hierarchyOne H1, no skipped levels — SEO & a11yheading audit / /audit/headings
GFM complianceFence languages, table parseGFM checklist / /audit/gfm
General lintBullets, blank lines, trailing space/validate
Broken linksDead internal/external URLslink checker / /extract/links
Missing alt textAccessibilityimage audit / /extract/images
README qualityFirst impression of the repoREADME 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:

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:

  1. Trigger only on **/*.md changes.
  2. Validate changed files only (diff base...head).
  3. Emit ::error file=…,line=… annotations.
  4. 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 rule id 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.

Quick reference

LayerSetupEnforced?
EditorBrowser tools / VS Code extNo
Pre-commitpre-commit hook + validate APINo (skippable)
CI on PRGitHub Action + required checkYes

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.