CommonMark vs GitHub Flavored Markdown

CommonMark defines a precise core Markdown syntax. GitHub Flavored Markdown, or GFM, is a strict superset of CommonMark that adds tables, task list items, strikethrough, extended autolinks, and filtering for certain raw HTML tags.

Why Markdown has flavors

The original Markdown description prioritized readable source but left edge cases open to interpretation. Different parsers made different choices about nested lists, punctuation, blank lines, HTML, and ambiguous emphasis.

CommonMark addressed that problem with a detailed specification and thousands of examples. It describes exactly how a conforming parser should interpret the core language. Products can then build extensions on a predictable base instead of inventing another almost-compatible parser.

CommonMark vs GFM at a glance

The syntax both flavors share

GFM inherits CommonMark's block and inline elements. The following source is portable across both:

# Release notes

This release fixes **three important issues**.

1. Open the application.
2. Select a local file.
3. Check the rendered preview.

Read the [installation guide](docs/install.md).

```powershell
winget list
```

The shared core includes ATX and Setext headings, paragraphs, hard and soft line breaks, thematic breaks, blockquotes, ordered and unordered lists, code blocks, inline code, emphasis, strong emphasis, links, images, autolinks written inside angle brackets, and defined forms of raw HTML.

GFM extension 1: tables

GFM turns pipe-delimited rows into a table when the header is followed by a delimiter row:

| Mode | Best for |
|:-----|:---------|
| Edit | Drafting |
| Preview | Reading |
| Split | Revising |

Colons in the delimiter row set alignment. The outer pipes are optional in the formal syntax, but including them usually makes the source easier to scan.

A CommonMark-only parser treats this as ordinary paragraph text. If the table contains essential information, confirm the destination supports GFM or provide an alternative list.

GFM extension 2: task list items

Add [ ] or [x] after a list marker:

- [x] Draft the release notes
- [ ] Verify every link
- [ ] Publish the installer

The GFM specification defines how task-list markers are recognized. Whether a checkbox is interactive depends on the product and context. Hashdraft renders clickable task-list checkboxes; other readers may display a disabled checkbox or a text symbol.

GFM extension 3: strikethrough

Two tildes mark deleted or obsolete text:

The release date is ~~Friday~~ Monday.

Strikethrough is useful for visible revisions and completed options, but it is not a substitute for version history or tracked changes.

GFM extension 4: extended autolinks

CommonMark supports autolinks inside angle brackets, such as <https://example.com> and <name@example.com>. GFM additionally recognizes many plain URLs and email addresses without the angle brackets.

CommonMark form: <https://example.com/docs>
GFM also detects: https://example.com/docs

Explicit links are still better in polished prose because [installation guide](https://example.com/docs) gives the destination a useful name.

GFM extension 5: disallowed raw HTML

CommonMark defines how raw HTML blocks and tags interact with Markdown. GFM filters tags that could change how surrounding HTML is interpreted, including <script>, <style>, <iframe>, <textarea>, and <title>.

This filtering is about safe rendering, not Markdown syntax convenience. A local or server-side renderer may impose even stricter rules. Hashdraft never executes embedded scripts.

GFM vs “Markdown on GitHub”

The formal GFM specification is narrower than everything GitHub renders. GitHub adds context-aware product features on top of GFM, including:

• mentions such as @username;
• issue and pull-request references;
• emoji codes;
• footnotes;
• alert blocks;
• mathematical expressions;
• automatic heading anchors;
• repository-aware relative links.

These features may be documented as GitHub Markdown, but that does not make them part of the GFM specification. This distinction matters when another app says “GFM compatible”: it may correctly support the five formal extensions without reproducing every GitHub product behavior.

Common features that are not GFM

Which flavor should you use?

Choose a CommonMark baseline when…

• the document moves between unknown tools;
• you are defining a public interchange format;
• tables and checkboxes are not essential;
• you want the smallest set of compatibility assumptions.

Use GFM extensions when…

• the document targets GitHub or a GFM-compatible renderer;
• tables make structured data easier to understand;
• task lists belong naturally in the document;
• strikethrough or plain URL detection improves the workflow.

In practice, many documentation projects use CommonMark core plus a carefully chosen subset of GFM. That is a strong portability compromise.

How to keep Markdown portable

1. Declare the expected flavor. Put it in the contributor guide or project documentation.
2. Use extensions intentionally. Do not assume every feature seen on GitHub belongs to GFM.
3. Test in the final renderer. Previewing in one app cannot guarantee another app's output.
4. Prefer relative project links. They survive clones and folder moves better than computer-specific paths.
5. Keep source readable. A fallback reader should still understand the message even if an extension is not rendered.
6. Add automated checks where possible. Lint Markdown and validate internal links in documentation repositories.

What Hashdraft supports

Hashdraft covers the everyday CommonMark/GFM-style elements used in documents, including tables, task lists, links, automatic links, and code fences. It also implements separate extensions such as footnotes, wiki links, YAML front matter, and LaTeX math. Those extra features should not be mistaken for GFM itself.

Frequently asked questions