Lint Markdown in CI with a GitHub Action + Validate API (2026)
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.
Documentation rots when nothing checks it. Broken heading hierarchies, inconsistent bullets, missing alt text, and malformed tables slip in one PR at a time until the docs look unmaintained. The fix is the same one you use for code: lint it in CI and fail the build on real problems.
This guide gives you a complete GitHub Action that validates only the Markdown files changed in a pull request, using the Markdown Viewer validate API — no local toolchain to install, consistent rules across every repo, and inline annotations on the diff.
Why a hosted validate API?
You can run markdownlint locally, and for many teams that's perfect. A hosted validate endpoint adds three things:
- Zero install. No Node toolchain, plugin versions, or config drift across repos — one
curlcall. - Consistent rules everywhere. The same conservative ruleset (heading-space, heading-increment, consistent-bullets, multiple-blank-lines, trailing-whitespace, missing-alt-text) applies to every repo and every contributor.
- A matching browser tool. Authors can pre-check the same rules in the GFM checklist and heading audit before they push.
The endpoint never modifies your files — it only reports issues with a line, rule, and severity.
What the validate API returns
curl -sf -X POST https://trymarkdownviewer.com/api/v1/validate \
-H "Authorization: Bearer $MDV_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "##Heading\n\n\n\n* bullet"}'
{
"data": {
"valid": false,
"issueCount": 2,
"issues": [
{ "line": 1, "message": "Missing space after `#` in heading.", "rule": "heading-space", "severity": "warning" },
{ "line": 5, "message": "Use `-` for unordered list items.", "rule": "consistent-bullets", "severity": "info" }
]
}
}
Each issue has a stable rule id, so you can gate CI on a subset (fail on warning+, ignore info) rather than the whole linter.
Step 1: Add your API key as a secret
- Create a free key in your Markdown Viewer dashboard.
- In your repo: Settings → Secrets and variables → Actions → New repository secret.
- Name it
MDV_API_KEYand paste the key.
Never hard-code the key in the workflow file.
Step 2: The workflow
Create .github/workflows/markdown-lint.yml:
name: Markdown lint
on:
pull_request:
paths:
- "**/*.md"
- "**/*.markdown"
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Find changed Markdown files
id: changed
run: |
base="${{ github.event.pull_request.base.sha }}"
head="${{ github.event.pull_request.head.sha }}"
files=$(git diff --name-only --diff-filter=ACM "$base" "$head" \
| grep -E '\.(md|markdown)$' || true)
echo "files<<EOF" >> "$GITHUB_OUTPUT"
echo "$files" >> "$GITHUB_OUTPUT"
echo "EOF" >> "$GITHUB_OUTPUT"
- name: Validate Markdown
if: steps.changed.outputs.files != ''
env:
MDV_API_KEY: ${{ secrets.MDV_API_KEY }}
run: |
fail=0
while IFS= read -r f; do
[ -z "$f" ] && continue
payload=$(jq -Rs '{markdown: .}' < "$f")
resp=$(curl -sf -X POST https://trymarkdownviewer.com/api/v1/validate \
-H "Authorization: Bearer $MDV_API_KEY" \
-H "Content-Type: application/json" \
-d "$payload")
# Emit GitHub annotations for warnings and errors
echo "$resp" | jq -r --arg f "$f" '
.data.issues[]
| select(.severity == "warning" or .severity == "error")
| "::error file=\($f),line=\(.line)::[\(.rule)] \(.message)"'
count=$(echo "$resp" | jq '[.data.issues[]
| select(.severity=="warning" or .severity=="error")] | length')
if [ "$count" -gt 0 ]; then fail=1; fi
done <<< "${{ steps.changed.outputs.files }}"
exit $fail
What it does
- Triggers only on Markdown changes (
paths:filter) — no wasted runs. - Diffs base vs head to validate only changed files, so a 500-file repo doesn't re-lint everything.
- Emits
::errorannotations so issues appear inline on the PR's Files changed tab, pinned to the exact line. - Fails the job when any
warning/errorissue exists, but letsinfothrough. Adjust theselect(...)filter to change your threshold.
Step 3: Make it a required check
In Settings → Branches → Branch protection rules, add Markdown lint to Require status checks to pass before merging. Now no PR with a heading jump or malformed list can merge.
Going further
Also score your README
Gate the repo's root README.md on a minimum health score:
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')
echo "README score: $score"
[ "$score" -ge 70 ] || { echo "README below threshold"; exit 1; }
The browser equivalent is the README health score tool.
Check GFM compliance and links
- GFM audit — fence languages, table parse, H1 count.
- Extract links — feed results into a broken-link check.
Pre-commit, not just CI
Catch issues before they reach the PR with a local hook — see Markdown linting on pull requests for a pre-commit setup that mirrors this Action.
GitLab, Bitbucket, and others
The same curl works in any CI. For GitLab CI:
markdown-lint:
image: alpine:latest
before_script: [apk add --no-cache curl jq git]
script:
- |
for f in $(git diff --name-only --diff-filter=ACM origin/$CI_DEFAULT_BRANCH...HEAD | grep -E '\.md$'); do
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")"
done
rules:
- changes: ["**/*.md"]
See the GitLab Markdown guide for GLFM-specific notes.
Common pitfalls
1. Linting every file on every push. Diff base vs head and only validate changed files — faster and cheaper.
2. Failing on info. Info-level rules (like bullet style) are often too noisy to block merges. Gate on warning/error.
3. Leaking the API key. Always use repo/org secrets; never inline the key.
4. No annotations. Without ::error file=...,line=..., contributors hunt for the issue. Emit annotations so it's pinned to the diff.
5. Forgetting fetch-depth: 0. Shallow clones can't diff against the base SHA.
Related articles
- Markdown linting on pull requests — pre-commit + CI strategy
- Docs-as-code guide — version-controlled docs workflow
- GitLab Markdown guide — GLFM + CI validation
- LLM Markdown output validation — same API, AI use case
- Validate API reference
Quick reference
| Endpoint | Use in CI |
|---|---|
/api/v1/validate | Lint changed .md files |
/api/v1/audit/gfm | GFM compliance gate |
/api/v1/audit/readme-score | README quality threshold |
/api/v1/extract/links | Feed a broken-link check |
Treat docs like code: lint them on every PR. Drop the workflow above into .github/workflows/, add the MDV_API_KEY secret, mark the check required, and your Markdown stays clean without anyone remembering to check it manually.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
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.
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.