Markdown was born with one goal: make writing formatted content for the web as easy as writing an email. Before Markdown, publishing on blogs or forums required writing raw HTML (<p>text</p>) or using slow WYSIWYG editors with messy output.
The syntax is deliberately minimal. Headers marked with #, bold with **text**, lists with dashes. A parser converts that to semantically correct HTML. Example:
## Title\n- Item 1\n- Item 2
Becomes:
<h2>Title</h2>\n<ul>\n <li>Item 1</li>\n <li>Item 2</li>\n</ul>
Today GitHub, Reddit, Discord, Stack Overflow, Notion and virtually every documentation tool supports Markdown. README.md files in open-source projects are written in Markdown. Even WhatsApp uses a simplified variant (*bold*, _italic_).
Gruber's original spec is intentionally loose, which spawned dialects. CommonMark (2014) standardized the core syntax:
- Headers:
# H1,## H2, up to###### H6. - Emphasis:
*italic*or_italic_,**bold**or__bold__. - Lists:
- Item(unordered) or1. Item(ordered). - Links:
[text](url)or[text](url "title"). - Images:
. - Inline code:
`code`. Blocks: three backticks or 4-space indentation. - Quotes:
> Quoted text. - Horizontal rule:
---or***.
Popular extensions (GitHub Flavored Markdown, GFM) add tables (| col1 | col2 |), checkboxes (- [ ] task), strikethrough (~~crossed~~) and syntax highlighting with ```javascript.
Common parsers: marked (JavaScript), markdown-it (JS with plugins), Python-Markdown, kramdown (Ruby). Most support extensions via plugins.
Technical documentation: READMEs, internal wikis, API docs. Markdown is readable raw (unrendered), ideal for `git diff` and code review.
Blogs and headless CMSs: static sites generated with Next.js, Gatsby or Hugo often use Markdown for posts. YAML frontmatter (---\ntitle: Post\n---) adds metadata.
Forums and collaborative platforms: Reddit, Discord, Slack use Markdown so users can format without buttons. Reduces editor complexity and prevents XSS (HTML is server-generated, not user-supplied).
Note-taking: Obsidian, Notion (partial), Roam Research and Logseq use Markdown as underlying format. Total portability: your notes are .md files you can open in any editor.
Don't use for: complex layouts (Markdown lacks grids or flexbox), HTML emails (better use MJML or direct HTML with inline CSS), or content requiring interactivity (forms, widgets).
Markdown vs HTML: Markdown is faster to write and read. HTML gives total control but is verbose. Many projects embed HTML inside Markdown for special cases (<details>, iframes).
Markdown vs reStructuredText (RST): RST is more powerful (supports complex directives, advanced footnotes) but syntax is more cryptic. Python and Sphinx use RST; the rest of the world uses Markdown.
Markdown vs AsciiDoc: AsciiDoc is more mature for long-form documentation (technical books, manuals). Markdown doesn't scale well for projects with hundreds of interconnected pages without extensions like MDX.
Markdown vs WYSIWYG (Notion, Google Docs): WYSIWYG editors are friendlier for non-technical users but generate proprietary HTML. Markdown is plain text, versionable with Git and portable across tools.
Current trend: MDX (Markdown + JSX), allowing React components embedded in Markdown. Used by Next.js, Docusaurus and Gatsby for interactive docs.
Examples
# Main title\n## Subtitle\nText with **bold** and *italic*.[Link to Genfy](https://genfy.io)\n```javascript\nconst x = 42;\nconsole.log(x);\n```- [ ] Pending task\n- [x] Completed task> Famous quote\n> — Author
FAQ
Can I use HTML inside Markdown?
Yes. Most parsers allow embedding raw HTML when Markdown isn't enough. For example, <details>, <video> or complex tables. The HTML passes unmodified to final output.
What is CommonMark?
A strict Markdown specification created in 2014 to resolve ambiguities in Gruber's original spec. It defines exact behavior for edge cases and is the basis for GitHub Flavored Markdown (GFM) and many modern parsers.
Does Markdown support tables?
The original spec doesn't, but GitHub Flavored Markdown (GFM) and other extensions do. Syntax: | Col1 | Col2 | followed by |------|------| then rows. Not all parsers support it without configuration.