Markdown Guide: Complete Syntax Reference
Markdown is the most widely used lightweight markup language — used in GitHub, Notion, Reddit, documentation tools, and static site generators. Here's the complete syntax reference.
Advertisement
What Is Markdown?
Markdown is a lightweight plain-text formatting syntax created by John Gruber in 2004. It is designed to be readable as plain text while being convertible to HTML. The idea: write with plain text characters like `#` for headings and `**` for bold, and the text renders as formatted HTML. Markdown files use `.md` or `.markdown` extensions and are stored as plain text — they can be version-controlled, diffed, and edited in any text editor.
Basic Syntax
| Element | Syntax | Rendered Output |
|---|---|---|
| Heading 1 | # Heading | <h1>Heading</h1> |
| Heading 2 | ## Heading | <h2>Heading</h2> |
| Bold | **bold** or __bold__ | <strong>bold</strong> |
| Italic | *italic* or _italic_ | <em>italic</em> |
| Bold + Italic | ***text*** | <strong><em>text</em></strong> |
| Strikethrough | ~~text~~ | <del>text</del> |
| Inline code | `code` | <code>code</code> |
| Blockquote | > quote text | <blockquote> |
| Horizontal rule | --- | <hr> |
| Link | [text](url) | <a href='url'>text</a> |
| Image |  | <img alt src> |
Extended Syntax (GFM)
GitHub Flavored Markdown (GFM) extends standard Markdown with tables, task lists, fenced code blocks, and footnotes. Most modern Markdown parsers support GFM.
| Element | Syntax |
|---|---|
| Fenced code block | ```language\n code \n``` |
| Table | | Col1 | Col2 |\n|---|---|\n| data | data | |
| Task list | - [x] Done\n- [ ] Todo |
| Footnote | Text[^1]\n\n[^1]: Footnote content |
| Emoji | :rocket: :heart: |
Where Markdown Is Used
- GitHub — README files, issues, pull request descriptions, wiki pages
- Notion — all text editing is Markdown-based
- Reddit — post and comment formatting
- Static site generators — Hugo, Jekyll, Gatsby, Next.js (with MDX)
- Documentation tools — GitBook, Docusaurus, MkDocs
- Note-taking apps — Obsidian, Bear, Typora, Joplin
- Slack and Discord — partial Markdown support for messages
- Jupyter Notebooks — cell text formatting
Convert Markdown to HTML
Preview Markdown and export as formatted HTML — live editor with instant preview.
Frequently Asked Questions
Is Markdown the same on all platforms?
No. There is a standard Markdown spec, but most platforms implement a superset with their own extensions. GitHub Flavored Markdown (GFM) adds tables, task lists, and @ mentions. CommonMark is a standardised strict spec. Pandoc Markdown adds citations and other academic extensions. The core syntax (headings, bold, italic, links) is consistent across all platforms; extended features vary.
Can I use HTML inside Markdown?
In most Markdown parsers, yes — raw HTML is allowed within Markdown and is passed through to the output. This means you can use HTML elements not supported by Markdown syntax (e.g., <div>, <span>, <sup>). However, HTML within Markdown is processed differently on some platforms (GitHub strips most HTML for security). Check your specific platform's documentation.