Markdown: The Writing Format That Took Over the Web

What if you could write formatted text that looks good before it's rendered? That's the core idea behind Markdown — a plain-text formatting syntax invented by John Gruber in 2004. It was designed so that the source file is just as readable as the output. Two decades later, Markdown is the default writing format for developers, technical writers, and anyone who documents software.

The philosophy: readable as-is

Before Markdown, writing for the web meant writing HTML. A bold word required <strong>word</strong>. A link required an <a href="..."> tag. The markup overwhelmed the content. Gruber (with contributions from Aaron Swartz) created Markdown to solve this: a syntax that uses punctuation characters people already understand.

An asterisk for emphasis. A hash for headings. Indentation for code. The conventions came from decades of plain-text email formatting, not from any formal specification.

The essential syntax

Here are the building blocks of Markdown, shown side by side with the HTML they produce:

Headings

# Heading 1       →  <h1>Heading 1</h1>
## Heading 2      →  <h2>Heading 2</h2>
### Heading 3     →  <h3>Heading 3</h3>

Emphasis

*italic*           →  <em>italic</em>
**bold**           →  <strong>bold</strong>
***bold italic***  →  <strong><em>bold italic</em></strong>
~~strikethrough~~  →  <del>strikethrough</del>

Links and images

[Link text](https://example.com)
→ <a href="https://example.com">Link text</a>

![Alt text](image.png)
→ <img src="image.png" alt="Alt text" />

Code

Inline: `const x = 42`
→ <code>const x = 42</code>

Block (fenced):
```javascript
function hello() {
  console.log("world")
}
```
→ <pre><code class="language-javascript">...</code></pre>

Lists

- Unordered item      →  <ul><li>Unordered item</li></ul>
1. Ordered item       →  <ol><li>Ordered item</li></ol>
- [ ] Task (unchecked) →  checkbox (GFM extension)
- [x] Task (checked)   →  checkbox (GFM extension)

Flavors: not all Markdown is the same

Gruber's original Markdown was intentionally ambiguous in edge cases. This led to different implementations parsing the same input differently. Over time, several “flavors” emerged to add features and resolve ambiguities:

Where Markdown is used

• GitHub — READMEs, issues, pull request descriptions, comments, and wikis all render Markdown.
• Reddit and Discord — Both support a subset of Markdown for formatting messages.
• Documentation — Most open-source docs (Docusaurus, MkDocs, VitePress) are written in Markdown or MDX.
• Note-taking apps — Obsidian, Notion, Bear, and Typora use Markdown as their native format.
• Static site generators — Hugo, Jekyll, Eleventy, and Astro convert Markdown files into full websites.

Why developers love it

Markdown files are plain text. They work with git diff. They don't lock you into a proprietary editor. They're tiny compared to Word documents. And they render beautifully on platforms like GitHub without any extra tooling.

The syntax is also fast to type. Once you learn the dozen or so conventions, you can format text without ever touching a toolbar or memorizing HTML tags. It's the closest thing to “what you type is what you get” for structured text.

Markdown won because it optimized for the right thing: the writing experience. The output format (HTML) was already solved. Markdown made the input format pleasant.