Skip to content
Markdown Viewer

GFM Compliance Checklist

Lint GitHub Flavored Markdown — five high-signal checks before you publish

Verify single H1, fence languages, alt text on images, no empty links, and a parseable first table — the five issues that most often break GitHub READMEs and docs. Runs in your browser, no signup.

Practice syntaxHeading auditorFormat the document
2 passing3 flagged

  • Single H1 (recommended)

    One H1.

  • Fenced code blocks specify a language when possible

    At least one ``` fence lacks a language tag.

  • No empty link labels ([])

    1 occurrences.

  • Images include alt text

    1 alt-empty images.

  • First pipe table parses correctly (if present)

    2 row(s) in first table.

How to use the GFM compliance checklist

  1. Paste your Markdown, or click Open .md to load a file.
  2. Read the five checks. Each item is passing (green tick) or flagged (amber) with a short detail explaining what was found.
  3. Fix the flagged items in your editor and re-paste — re-running takes a second.

The badge row above shows totals at a glance: how many checks pass and how many need attention.

The five checks explained

GitHub READMEs, docs pages, and blog posts almost always want exactly one H1 — the document title. The checklist counts ATX-style # Heading lines outside fenced code and flags zero (info) or more than one (warning) H1.

2. Fenced code blocks specify a language

```js
const a = 1
```

GitHub uses the language tag to syntax-highlight code. A fence opened with just ``````````` renders as plain monospace. The checklist flags any fence missing a language tag.

A link with empty label text ([]()) is invisible — it renders as nothing on GitHub. Empty labels are usually copy-paste accidents. The checklist counts and reports them.

4. Images include alt text

![Alt description](/img.png) is required for accessibility (screen readers) and shows up if the image fails to load. The checklist flags ![]() images so every image has a meaningful alt.

5. First pipe table parses

GFM tables break in subtle ways: missing alignment row, mismatched column counts, stray pipes. The checklist extracts the first table outside fenced code and confirms it has at least one row, surfacing a fast smoke test for documents that rely heavily on tables.

A practical pre-publish workflow

  1. Draft your document in the Markdown Editor.
  2. Run the Markdown Formatter for whitespace and structural cleanup.
  3. Run the Heading Auditor to fix outline jumps.
  4. Run this GFM Compliance Checklist for the final five gates.
  5. Optionally run the Diff tool against the previous version to confirm only intended changes shipped.

That sequence catches ~95% of the issues that show up in code review.

Beyond the five checks

If you want stricter linting, complement this tool with:

  • markdownlint — 50+ rules, CI-friendly.
  • remark-lint — plugin-based, integrates with the unified ecosystem.
  • Vale — prose-level style enforcement.

For everyday Markdown writing, though, the five-item checklist tends to be the right balance: high signal, no setup, runs anywhere.

Privacy & data

All checks run inside your browser as small regex / parser passes. We don't upload, log, or store your Markdown.

Frequently asked questions

What is the GFM compliance checklist?
It is a quick pre-publish sanity check for GitHub Flavored Markdown documents. The tool runs five high-signal checks: single H1, language tag on every fenced code block, no empty link labels, every image has alt text, and the first pipe table (if any) parses cleanly.
Why these particular checks?
They map to the issues that most often cause GitHub README and docs render problems: wrong heading count breaks SEO and TOCs, missing fence languages disable syntax highlighting, empty links and alt text fail accessibility, and broken tables silently fall back to plain text. Fixing these five things eliminates the bulk of 'looks broken on GitHub' complaints.
Does the checklist enforce a style guide?
No — it surfaces violations of GitHub's own rendering conventions, not opinions about prose style. Pair it with a Markdown formatter or a style-specific linter (markdownlint, remark-lint) for stricter house rules.
Will a passing checklist guarantee my README renders perfectly?
It will catch the high-impact issues, but it is not exhaustive. Specific GitHub quirks — relative image paths, raw HTML stripping, emoji shortcodes — are out of scope. Always preview on GitHub itself for final sign-off.
Is my Markdown uploaded?
No. Every check runs as a small regex / parser scan inside your browser tab. We never upload, log, or train on your document.
How is this different from markdownlint?
Markdownlint is a comprehensive rule engine with 50+ rules and CI integration. This checklist is a lightweight pre-flight that focuses on five high-signal items, runs in the browser without any setup, and is intended for one-off audits — for instance, before posting a README, a release note, or a docs PR.