Markdown

Markdown is plain text with a few punctuation conventions: # for headings, * or - for lists, **bold**, [links](https://example.com) and backtick code spans. The text stays readable as is, and tools convert it to HTML. It’s the standard format for README files, documentation, wikis, static site generators, chat messages, note-taking apps and LLM output.

There is no single Markdown. The original 2004 description was informal, so implementations disagreed on edge cases. CommonMark is the precise, tested specification that most modern parsers follow. GitHub Flavored Markdown (GFM) is CommonMark plus tables, task lists, strikethrough, autolinks and HTML filtering. Many tools add their own extensions: footnotes, front matter, math, definition lists, admonitions.

When to use Markdown#

• Use for README files, documentation, notes, blog posts and any text that people write by hand and that ends up as HTML.
• Use when the source should be readable and diffable in version control.
• Avoid for layout-heavy documents (columns, precise positioning, page breaks): use HTML, PDF or a word processor format.
• Avoid assuming that every renderer shows the same output: write to CommonMark or GFM and test with your target renderer.

Syntax#

The core CommonMark syntax:

# Heading 1
## Heading 2

Paragraphs are separated by blank lines. Lines next to each other
join into one paragraph.

*italic* or _italic_, **bold**, `inline code`, [link](https://example.com "title"),
![image alt text](picture.png), <https://autolink.example>

- bullet list
- second item
  1. nested numbered list
  2. second

> block quote

    indented code block (4 spaces)

```python
fenced code block with a language
```

---  (thematic break)

Line ends with a backslash\
for a hard line break. <span>Raw HTML</span> is allowed.

GFM adds:

| Column | Aligned right |
|--------|--------------:|
| cell   |            42 |

- [x] done task
- [ ] open task

~~strikethrough~~, www.example.com and https://example.com become links

Common extensions outside the specs: footnotes (text[^1] and [^1]: note, supported by GitHub), YAML front matter between --- lines at the top of the file, math ($x^2$, $$...$$), heading IDs (## Title {#id}), definition lists, and GitHub alerts (> [!NOTE]).

File structure#

A Markdown file is plain text, normally UTF-8. A CommonMark parser works in two phases:

1. Block structure: the input is split into lines and grouped into blocks: paragraphs, headings (ATX # or setext underlines), block quotes, lists and list items, code blocks (indented or fenced), HTML blocks, thematic breaks, and link reference definitions ([id]: https://url "title"). Containers (quotes, list items) nest.
2. Inlines: the text inside paragraphs and headings is parsed for emphasis, code spans, links, images, autolinks, raw HTML, entities, backslash escapes and line breaks.

The result is an abstract syntax tree (document, block and inline nodes) that renderers turn into HTML, or back into normalized Markdown. Raw HTML passes through unchanged, which is why renderers for untrusted input either escape it or sanitize the output.

Front matter#

Static site generators (Hugo, Jekyll, Astro, Docusaurus) put metadata at the top of the file. It’s not part of CommonMark; parsers need an extension to skip or read it:

---
title: Release notes
date: 2026-11-05
tags: [docs, release]
---

# Release notes

Variants#

Converting Markdown#

# to HTML with the CommonMark reference implementation
cmark --to html README.md > README.html

# GFM with cmark-gfm
cmark-gfm -e table -e strikethrough -e autolink -e tasklist README.md > README.html

# to PDF, DOCX, EPUB and many more with Pandoc
pandoc README.md -o README.pdf
pandoc README.md -o README.docx
pandoc notes.docx -t gfm -o notes.md   # Word to Markdown

Specifications and documentation#

• CommonMark specification 0.31.2: the precise syntax with 650+ examples
• CommonMark home page: reference implementations, 10-minute tutorial, dingus to try the syntax
• GitHub Flavored Markdown spec: CommonMark plus GFM extensions
• GitHub docs: basic writing and formatting syntax: alerts, footnotes, math and other GitHub features
• RFC 7763: the text/markdown media type; RFC 7764: variants
• Original Markdown syntax
• Pandoc’s Markdown
• Babelmark 3: compare the output of many Markdown implementations

Software that opens Markdown files#

Libraries#

Every language has CommonMark-compliant parsers. See all Markdown libraries for a comparison.

Related formats#

• TXT: Markdown is plain text, with the same encoding and line-ending concerns
• RTF: formatted text for word processors
• EPUB: convert Markdown to eBooks with Pandoc
• PDF: convert Markdown for printing and sharing