Markdown is a solved problem that people keep re-solving. John Gruber created it in 2004, and two decades later there are at least 30 flavors of it — CommonMark, GFM, MDX, MultiMarkdown, Obsidian's variant — and they all disagree on edge cases. The core syntax is universal. The extensions are where things get interesting and incompatible.
CommonMark (2014) finally standardized the syntax after years of incompatible parsers. GitHub Flavored Markdown (GFM) extended it with tables, task lists, strikethrough, and autolinking. Because GitHub is where most developers write Markdown, GFM features have become de facto standards even outside GitHub. That's the context you need to understand what will and won't work on any given platform.
What works everywhere
The following syntax is supported by virtually every Markdown implementation and is safe to use everywhere:
# Heading 1
## Heading 2
### Heading 3
**Bold text** and *italic text* and ***bold italic***
[Link text](https://example.com)
- Unordered list item
- Another item
- Nested item
1. Ordered list item
2. Another item
> Blockquote text
> Can span multiple lines
`inline code` for short snippets
```javascript
// Fenced code block with language hint
const greeting = "Hello, World!";
```
---
Horizontal rule (three or more dashes)GitHub Flavored Markdown (GFM) Extensions
GFM adds several features that have become de facto standards across most modern Markdown implementations, even outside GitHub:
| Column A | Column B | Column C |
|----------|:--------:|---------:|
| Left | Center | Right |
- [x] Completed task
- [ ] Incomplete task
~~Strikethrough text~~
Autolinked URL: https://example.com
Footnote reference[^1]
[^1]: Footnote content appears at the bottom.Tables, task lists, strikethrough, autolinking, and footnotes are widely supported but not universal. Always test your Markdown on the target platform before assuming a feature works.
What Markdown actually compiles to
The core purpose of Markdown is conversion to HTML. The mapping is direct: # becomes <h1>, **text** becomes <strong>text</strong>, - items become <ul><li> elements, and so on. Understanding this mapping helps you predict how your Markdown will render and debug formatting issues.
Markdown HTML
─────────────────────────────────────────────────
# Heading 1 <h1>Heading 1</h1>
**Bold** <strong>Bold</strong>
*Italic* <em>Italic</em>
[Link](url) <a href="url">Link</a>
 <img src="src" alt="Alt" />
- Item <ul><li>Item</li></ul>
1. Item <ol><li>Item</li></ol>
> Quote <blockquote><p>Quote</p></blockquote>
`code` <code>code</code>
```lang ... ``` <pre><code class="language-lang">...</code></pre>Popular Markdown Parsers and Libraries
If you're picking a parser in 2026, here are the ones that actually get used in production:
- marked (JavaScript): Fast, lightweight, widely used. Supports GFM. Good default for client-side rendering and simple server-side use cases.
- remark/unified (JavaScript): Plugin-based ecosystem that parses Markdown into an AST. Powers MDX, Gatsby, and most documentation tooling. More setup, more flexibility.
- markdown-it (JavaScript): CommonMark-compliant, plugin-extensible. Used by VS Code's built-in Markdown preview. Good when you need custom syntax rules.
- Python-Markdown (Python): The standard Python library. Used by MkDocs and Pelican. Covers most use cases with minimal config.
- goldmark (Go): Default parser in Hugo. Fast, CommonMark-compliant — worth knowing if you work with Go static sites.
MDX: Markdown with React Components
MDX (Markdown + JSX) extends Markdown to allow embedding React components directly alongside Markdown content. This enables rich, interactive documentation where static text, live code examples, and interactive widgets coexist in a single file. MDX is used by Docusaurus, Next.js documentation, Storybook, and many modern documentation platforms.
---
title: Getting Started
---
# Welcome
Here is a standard Markdown paragraph.
<CodeExample language="javascript">
const x = 42;
</CodeExample>
And here is an interactive component:
<ColorPicker defaultColor="#3B82F6" />Markdown as your content layer
Many modern websites use Markdown files as the content layer, with a static site generator or framework rendering them to HTML at build time. The pattern is: Markdown files with YAML frontmatter (title, date, tags, author) are stored in a content directory, a build step parses them into HTML with metadata, and the framework renders the HTML within a template/layout component.
This approach has significant advantages over traditional CMS databases: content is version-controlled in Git, diffs are readable, content is portable across platforms, and there is no database to maintain or migrate. For developer-focused sites, documentation projects, and blogs, Markdown-as-content is now the dominant paradigm.
What trips people up
Personal take: the most common Markdown mistake isn't syntax — it's using it somewhere it doesn't belong. Markdown inside a JSON string, Markdown in an email template, Markdown in a mobile app without a parser. Always verify your rendering environment actually processes Markdown before committing to it as a format.
- Blank lines matter: Markdown requires a blank line before lists, code blocks, and blockquotes to parse correctly. Missing blank lines are the most common source of rendering bugs.
- Indentation is meaningful: Nested list items require 2-4 spaces of indentation (implementation-dependent). Inconsistent indentation breaks nesting.
- HTML is valid Markdown: You can embed raw HTML in Markdown files for features Markdown does not support natively (like <details> for collapsible sections). The HTML passes through to the output unchanged.
- Escape special characters: Use backslash to escape Markdown syntax characters when you want them displayed literally: \*, \#, \[, \]
- Use reference-style links for readability: For documents with many links, [text][ref] with [ref]: url at the bottom keeps the prose readable.