Markdown is a lightweight markup language created by John Gruber in 2004 with the goal of being readable as plain text while also convertible to HTML. Today it powers GitHub READMEs, technical documentation sites (MkDocs, Docusaurus), note-taking apps (Obsidian, Notion), and most modern content management systems.
This guide covers Markdown syntax from basics to advanced features including tables, task lists, code blocks, and GitHub Flavored Markdown (GFM) extensions.
Basic Markdown Syntax
Headings use pound signs:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4Emphasis:
*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~Lists:
- Unordered item
- Another item
- Nested item (indent 2 spaces)
1. Ordered item
2. Second item
1. Nested orderedLinks and images:
[Link text](https://example.com)
[Link with title](https://example.com "Hover title")

Blockquotes:
> This is a blockquote
> It can span multiple lines
>
> With empty lines for paragraphsHorizontal rules:
---
***
___Code Blocks and Syntax Highlighting
Inline code uses single backticks: const x = 1
Fenced code blocks use triple backticks with optional language identifier:
function greet(name) {
return Hello, ${name}!;
}
Supported language identifiers include: javascript, typescript, python, rust, go, java, sql, bash, yaml, json, xml, css, html, and many more.
Indented code blocks (4 spaces) are an older syntax:
This is an indented code block
It preserves whitespaceMost renderers support syntax highlighting for fenced blocks with a language tag. GitHub, GitLab, and most documentation tools process these using highlight.js or Prism.js.
GitHub Flavored Markdown (GFM) Extensions
GitHub extended standard Markdown with several useful features, now widely adopted by other platforms.
Tables:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Left | Center | Right |
| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| A | B | C |Task lists (checkboxes):
- [x] Completed task
- [ ] Pending task
- [x] Another done item
- [ ] Nested taskAutolinks:
https://example.com (automatically linked)
[email protected] (email autolinked)Footnotes (supported by many renderers):
This sentence has a footnote[^1].
[^1]: This is the footnote content.Definition lists (supported by Pandoc, MkDocs):
Term
: Definition of the term
Another term
: Another definitionAdvanced: Escaping, HTML, and Edge Cases
Escaping special characters -- backslash before any Markdown character:
\*Not italic\*
\[Not a link\](https://example.com)Inline HTML is allowed in most Markdown renderers:
This has <span style="color:red">red text</span>.
<details>
<summary>Click to expand</summary>
Content that is hidden by default.
</details>Embedding images with size control (HTML required):
<img src="image.png" alt="Alt text" width="400">Common Markdown gotchas:
- Two spaces at end of line = line break; empty line = paragraph break
- Four-space indent = code block (even inside lists)
- Links can use reference style: [text][ref] and [ref]: url
- Nested lists require consistent indentation (2 or 4 spaces)
- Some renderers require blank lines before/after lists and headings
Markdown Variants and Tooling
There is no single Markdown standard -- different implementations vary:
CommonMark -- the most strictly specified standard, used as a base by GitHub, Reddit, Stack Overflow, and Discourse. The spec at commonmark.org resolves all ambiguities in the original Markdown.
GitHub Flavored Markdown (GFM) -- CommonMark + tables, strikethrough, task lists, autolinks.
Pandoc Markdown -- the most feature-rich variant, adding citations, definition lists, superscript, subscript, and multi-format output (PDF, DOCX, LaTeX).
MDX -- Markdown + JSX components, used with React documentation tools like Docusaurus and Nextra.
Popular Markdown tools:
- Obsidian -- note-taking with graph view
- Typora -- WYSIWYG Markdown editor
- MkDocs / Docusaurus -- documentation site generators
- Marked.js / markdown-it -- JavaScript Markdown parsers
- Pandoc -- universal document converter
# Convert Markdown to PDF with Pandoc:
pandoc input.md -o output.pdf --pdf-engine=xelatex
# Convert Markdown to DOCX:
pandoc input.md -o output.docx