Markdown Explained: Why Plain Text Took Over Documentation

//: # ()

Want to see Markdown rendered right now? Use our free Markdown to HTML Live Preview — write or paste Markdown and see it rendered instantly, entirely in your browser.

A format designed to be readable before it's rendered

John Gruber created Markdown in 2004 with one explicit goal: a plain-text formatting syntax that's readable as plain text, without being rendered first. Compare the same content in HTML versus Markdown:

<h2>Features</h2>
<ul>
  <li><strong>Fast</strong> setup</li>
  <li>Works <em>everywhere</em></li>
</ul>

## Features

- **Fast** setup
- Works *everywhere*

The Markdown version is legible without a browser — you can read it in a terminal, an email, a commit message, or a raw GitHub file view and still understand the structure. That single property is why it spread everywhere developers write text: READMEs, pull request descriptions, issue trackers, chat apps (Slack, Discord), static site generators, and note-taking apps (Obsidian, Notion's plain-text mode).

The syntax that covers 95% of real usage

# Heading 1
## Heading 2

**bold**, *italic*, `inline code`

- bullet list
- another item

1. numbered list
2. second item

> a blockquote

[link text](https://example.com)
![alt text](image.png)

```
a fenced code block
```

| Table | Header |
|---|---|
| cell | cell |

That's the entire practical vocabulary most people ever need — a handful of prefix characters (#, -, >, `) and two wrapping characters (*, `) do almost everything.

CommonMark and GFM: standardizing an ambiguous spec

Gruber's original Markdown description was prose, not a formal grammar, and different implementations disagreed on edge cases (nested lists, mixing HTML with Markdown, when a _ mid-word counts as emphasis). Two things fixed this:

CommonMark — a strict, unambiguous specification with a test suite, so any two compliant parsers produce identical output for the same input.
GitHub Flavored Markdown (GFM) — CommonMark plus GitHub's popular extensions: tables, strikethrough (~~text~~), automatic URL linking, and task lists (- [ ] todo).

Nearly every modern Markdown renderer (including the one behind this tool) implements GFM, which is why it's the safe default to write against.

Where Markdown intentionally stops

Markdown deliberately doesn't try to replace HTML/CSS for layout, styling, or anything visually complex — columns, custom colors, precise spacing. The convention (and CommonMark's own design) is that raw HTML is allowed inline for anything Markdown's syntax doesn't cover, which is also exactly why any tool that renders untrusted Markdown needs to sanitize the output — raw HTML support means a malicious <script> or onerror handler pasted into a Markdown field will render unless it's explicitly stripped before display.

Try it

Write or paste Markdown into the Markdown to HTML Live Preview to see it rendered instantly, and copy the sanitized HTML output for use anywhere.