Skip to content
All posts

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:

  1. Zero install. No Node toolchain, plugin versions, or config drift across repos — one curl call.
  2. 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.
  3. 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

  1. Create a free key in your Markdown Viewer dashboard.
  2. In your repo: Settings → Secrets and variables → Actions → New repository secret.
  3. Name it MDV_API_KEY and 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 ::error annotations so issues appear inline on the PR's Files changed tab, pinned to the exact line.
  • Fails the job when any warning/error issue exists, but lets info through. Adjust the select(...) 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.

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

Quick reference

EndpointUse in CI
/api/v1/validateLint changed .md files
/api/v1/audit/gfmGFM compliance gate
/api/v1/audit/readme-scoreREADME quality threshold
/api/v1/extract/linksFeed 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.