Markdown was created by John Gruber in 2004 with a simple goal: a plain text format that is readable as-is but can be converted to valid HTML. Two decades later, Markdown has become the universal writing format for developers. GitHub uses it for READMEs and issues. Notion, Obsidian, and Confluence use it for documentation. Hugo, Gatsby, Astro, and Next.js use it for static site content. Slack, Discord, and Reddit use variants of it for message formatting.
Despite its ubiquity, Markdown has no single specification — the original definition left many edge cases ambiguous, leading to incompatible implementations. CommonMark (2014) standardized the syntax, and GitHub Flavored Markdown (GFM) added widely-used extensions. Understanding which features are portable across platforms and which are implementation-specific prevents frustrating formatting surprises.
Core Syntax: The Portable Subset
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.
Markdown to HTML Conversion
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
Choosing the right parser depends on your platform, performance requirements, and which extensions you need:
- marked (JavaScript): Fast, lightweight, and widely used. Supports GFM. Good for client-side rendering and simple server-side use cases. Minimal dependencies.
- remark/unified (JavaScript): A plugin-based ecosystem that parses Markdown into an AST (abstract syntax tree) for transformation. Powers MDX, Gatsby, and many documentation tools. Highly extensible but more complex to set up.
- markdown-it (JavaScript): Flexible, plugin-extensible parser with good CommonMark compliance. Used by VS Code's built-in Markdown preview. Supports custom syntax extensions.
- Python-Markdown (Python): The standard Python library for Markdown conversion. Supports extensions for tables, code highlighting, and table of contents. Used by MkDocs and Pelican.
- goldmark (Go): The default Markdown parser in Hugo. Fast, CommonMark-compliant, and extensible. Suitable for high-volume static site generation.
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 for Content Management
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.
Common Mistakes and Tips
- 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.