What is Markdown?

Updated April 26, 2026 · 5 min read · by Samuel Yoo

Markdown is a lightweight markup language. You write plain text with a handful of punctuation conventions (# for headings, ** for bold, - for lists, etc.); a Markdown parser converts it to formatted HTML.

If you’ve ever written a GitHub README, posted a comment on Stack Overflow, edited a Discord message, or written a blog post in Hugo or Jekyll, you’ve used Markdown. It’s quietly become the default format for technical writing on the web.

A complete example

Markdown source:

# Quarterly review

Q4 was strong. Highlights:

- Revenue grew **32%** year over year
- NPS climbed from 42 to **61**
- Two new product launches

See the [full report](https://example.com/report) for details.

Rendered output:

Quarterly review

Q4 was strong. Highlights:

• Revenue grew 32% year over year
• NPS climbed from 42 to 61
• Two new product launches

See the full report for details.

The source is readable as plain text. The rendered output is formatted HTML. That’s the design.

Where it came from

Markdown was created by John Gruber in 2004, with input from Aaron Swartz. The goal: a syntax that’s easy to write, easy to read in source form, and unambiguously convertible to HTML.

The original spec (daringfireball.net/projects/markdown) left some edge cases under-specified. In 2014, CommonMark formalized those edge cases into a strict standard. CommonMark is what modern parsers target.

GitHub then layered on extensions — tables, task lists, strikethrough, autolinks — collectively known as GitHub-Flavored Markdown (GFM). GFM is the de facto dialect for technical writing today. Our viewer renders GFM.

Why Markdown won

The web has had many writing formats. Markdown beat them because:

1. The source is readable

Compare the same content in three formats:

HTML:

<h2>Hello</h2>
<p>This is <strong>bold</strong>.</p>

RTF:

{\rtf1\ansi\\b Hello\b0\par This is \b bold\b0.\par}

Markdown:

## Hello

This is **bold**.

Even a non-technical reader can guess what the Markdown source means. That readability matters when you’re skimming git diffs, scrolling through a long doc, or fixing a typo at 2 AM.

2. Plain text everywhere

Markdown files are .md text files. They:

• Diff cleanly in git
• Open in any editor
• Survive copy-paste through any system
• Don’t require a viewer to read
• Convert to HTML, PDF, EPUB, or DOCX with pandoc

A Word .docx does none of these things.

3. Quick to write

Once you know the half-dozen common patterns, writing Markdown is faster than clicking through a WYSIWYG editor. Your hands stay on the keyboard.

4. The web infrastructure moved with it

GitHub renders Markdown in repos, issues, PRs, and gists. That single choice — by the platform that ate developer mind-share around 2010 — made Markdown the lingua franca of open-source documentation. Stack Overflow, GitLab, Bitbucket, Notion, Discord, Slack, and basically every modern writing tool followed.

Where Markdown is used

Technical writing

• README files (README.md is the de facto repo introduction)
• API documentation
• Engineering RFCs and design docs
• Internal wikis (Notion, Confluence, Outline)
• Blog posts on developer-focused platforms (dev.to, Hashnode)
• Books (with mdBook, GitBook)

Static sites

• Hugo, Jekyll, Astro, Gatsby, Next.js content sites
• This very documentation page is Markdown source under the hood

Communication

• GitHub / GitLab / Bitbucket comments
• Stack Overflow questions and answers
• Discord and Slack messages (a subset)
• Reddit posts
• Email (some clients)

Note-taking

• Obsidian, Logseq, Bear, iA Writer — Markdown is the file format
• VS Code’s notebook extension
• Vim / Emacs / Sublime Text — every editor has Markdown support

Markdown vs alternatives

For technical writing on the web in 2026, the answer is almost always Markdown, with MDX as a step up when you need embedded interactive components (this article is MDX).

Limitations

Markdown is intentionally simple. Things it doesn’t do:

• Underline — no syntax. Use HTML <u> if you must.
• Text color — no syntax. Use HTML inline styles.
• Layout — no columns, no flex, no grid. Use HTML or a richer format.
• Math — not in CommonMark. KaTeX or MathJax extensions exist.
• Diagrams — not in CommonMark. Mermaid is a popular extension.
• Variables / templates — not in standard Markdown. Templating happens at the layer above (Jinja, Liquid, MDX, etc.).

When you outgrow Markdown, the usual progression is:

• Need components or interactivity → MDX
• Need rich diagrams → keep Markdown, embed Mermaid / PlantUML
• Need complex layout → drop to HTML for that section
• Need print-quality typography → switch to Typst, LaTeX, or Pandoc with a custom template

Try it

• Markdown viewer — paste anything, see it rendered
• Cheat sheet — every syntax in one page
• Markdown → HTML — convert and copy
• HTML → Markdown — reverse direction

Further reading

• CommonMark spec — the formal standard
• GitHub Flavored Markdown spec — GitHub’s extensions
• Daring Fireball: original Markdown — Gruber’s 2004 announcement