Why Markdown exists
Markdown (John Gruber, 2004) was designed around one idea: plain text that's readable as plain text, without rendering. **bold** is legible in a raw text file the way <strong>bold</strong> isn't — the syntax was chosen to look like the formatting convention people already used in plain-text email, not to be a new thing to memorize. It has become the default authoring format for READMEs, technical blogs, documentation, and chat platforms precisely because it's fast to write and doesn't require a rendered preview to be understood.
Core syntax
# Heading 1
## Heading 2
**bold**, *italic*, `inline code`
- bullet item
- another item
1. numbered item
2. another
> blockquote
[link text](https://example.com)
```
code block
```
This covers the vast majority of real-world Markdown usage. Everything else — tables, footnotes, task lists (- [ ]), strikethrough (~~text~~) — is an extension, not part of the original spec, which is the root of most Markdown compatibility confusion.
CommonMark: the standard Gruber's original spec never was
The original Markdown "spec" was a prose description with genuine ambiguities — different implementations (PHP Markdown, Python-Markdown, Showdown) resolved edge cases differently, so the same source file could render differently depending on which parser processed it. CommonMark (2014) is a community-driven effort to formally specify Markdown's exact behavior, including edge cases, with a test suite over a thousand cases deep. Most modern tools (GitHub, GitLab, many static site generators) now build on CommonMark or a close variant, which is why compatibility has improved significantly — but variance still exists at the edges.
Why the same file renders differently in different places
| Feature | GitHub Flavored Markdown | CommonMark core | Plain original Markdown |
|---|---|---|---|
| Tables | Yes | No (extension) | No |
Task lists (- [ ]) |
Yes | No | No |
Strikethrough (~~text~~) |
Yes | No | No |
| Autolinking bare URLs | Yes | No | No |
| Fenced code blocks | Yes | Yes | No (indent-based only) |
GitHub Flavored Markdown (GFM) is a superset that adds tables, task lists, and strikethrough on top of CommonMark. A file relying on GFM tables will render as a literal pipe-delimited paragraph, not a table, on a parser that only implements bare CommonMark — this is the single most common "why does my Markdown look broken here" complaint.
Common mistakes
- Assuming Markdown syntax is universal. It's closer to a family of dialects sharing a common core; tables, footnotes, and definition lists are extensions that not every renderer supports.
- Mixing tabs and spaces in nested lists. Indentation-sensitive constructs (nested lists, code blocks inside list items) behave inconsistently across parsers when tabs and spaces are mixed — spaces only is the safer default.
- Forgetting a blank line before a list or heading. Many parsers require a blank line separating a paragraph from a following list or heading, or they'll merge the two into one block unexpectedly.
- Writing raw HTML and expecting consistent escaping. Markdown generally passes raw HTML through untouched, but exactly how much (inline-only vs. block-level, sanitized vs. not) varies by renderer — a real security consideration if you're rendering user-supplied Markdown.
FAQ
Is Markdown a replacement for HTML?
No — Markdown is a shorthand that compiles to HTML (or another output format); anything Markdown syntax can't express, you drop into raw HTML directly, which most renderers pass through.
Why do GitHub-style tables not render on my static site?
Tables are a GitHub Flavored Markdown extension, not part of bare CommonMark — your site's Markdown processor needs the GFM extension (or an equivalent) enabled to support them.
What is CommonMark, exactly?
A precise, test-suite-backed specification of Markdown's exact parsing behavior, created to resolve the ambiguities in the original informal spec — most modern tools build on it as a base, then add their own extensions on top.
Can Markdown files contain raw HTML?
Yes, in most implementations — Markdown generally passes HTML through untouched, though sanitization and exactly which HTML is allowed varies by renderer, which matters a lot if the content comes from untrusted users.