In 2004, John Gruber wanted to write for the web without writing HTML. His answer was Markdown: a way to format text using punctuation you can read as-is. A # becomes a heading, *words* become italic, and the source stays perfectly readable if the formatting is ever stripped away.
Twenty years later, Markdown quietly runs a huge share of the web's text — README files, documentation, chat apps, note-taking tools, static-site generators. If you write anything that ends up on a screen, ten minutes with Markdown pays for itself many times over.
Why Markdown exists
HTML is powerful but noisy. Writing
Title
and bold by hand breaks your flow and buries your words in tags. Markdown's founding rule was that the source should be readable as plain text: an email-style document that also happens to convert cleanly to HTML when you want it to.That convertibility is the superpower. One Markdown file can become a web page, a PDF, a slide deck or a Word document, because the format describes structure (this is a heading, this is a list) rather than appearance. You stop reformatting the same content for every destination.
The basics: headings, emphasis and paragraphs
Everything common fits in a handful of marks:
- Headings: # Heading 1, ## Heading 2, down to ######. More hashes, smaller heading.
- Bold and italic: **bold** with double asterisks, *italic* with single. ___Both___ works too.
- Strikethrough: ~~removed~~ renders with a line through it.
- Paragraphs: just write, separated by a blank line. A single line break is ignored unless you end the line with two spaces.
- Horizontal rule: three or more dashes --- on their own line draws a divider.
Lists, links, images and quotes
The everyday structures of documents:
- Bullet lists: start lines with - or *. Indent two spaces for a nested level.
- Numbered lists: 1. 2. 3. — most renderers number correctly even if you write 1. every time, which makes reordering painless.
- Task lists: - [ ] todo and - [x] done render as checkboxes on GitHub.
- Links: [visible text](https://example.com). Reference-style links keep long URLs out of your sentences.
- Images:  — the same as a link with a ! in front.
- Blockquotes: > at the start of a line, the email-style quote that Markdown borrowed deliberately.
Code and tables
For technical writing, two more constructs matter. Inline code uses backticks: `npm install`. Fenced code blocks use triple backticks, optionally with a language name for highlighting:
Tables use pipes and dashes. The syntax looks fussy until you have written two of them, then it becomes mechanical:
- ```js / console.log('hello'); / ``` — a fenced block (shown here with slashes standing in for line breaks).
- | Name | Price | — header row, then | --- | --- | as the divider, then one row per line.
- Colons in the divider control alignment: |:---| left, |---:| right, |:--:| centered.
Where Markdown actually lives
Once you can read it, you start seeing it everywhere. GitHub renders README.md files automatically, which is why open-source projects document themselves in Markdown. Static-site generators turn Markdown posts into blogs. Note apps like Obsidian, Notion's editor and Bear store or accept it. Chat platforms — Slack, Discord, WhatsApp — support a subset for everyday messages.
The practical advice: write anything longer than a paragraph in Markdown by default. Notes, drafts, documentation, even emails you compose in a text editor first. The file you produce today will still be readable in thirty years, which is more than can be said for most proprietary formats.
Mistakes beginners make
Three errors account for most beginner frustration. First, forgetting the blank line: Markdown needs an empty line before a heading or list, or it treats your # as literal text. Second, inconsistent indentation in nested lists — one space too few and your sub-item pops back to the top level. Third, pasting rich text from Word or Google Docs, which smuggles invisible formatting that breaks code blocks and tables.
The fix for all three is the same: write in a plain-text editor, preview often, and when something renders wrong, look at the raw characters around it. Markdown's failures are almost always whitespace you cannot see.
- Missing blank lines before headings, lists and code fences — the most common cause of “why isn't this formatting”.
- Tabs vs spaces in nested lists: pick spaces (two per level) and stay consistent.
- Unescaped special characters: a literal * or # at a line start needs a backslash: \*not italic\*.
- Overlong lines in tables: keep cell content short; wide tables render badly on phones.
Frequently asked questions
Is Markdown standardized?
Mostly, now. The original spec was loose, which spawned dialects. CommonMark (2014) nailed down the core, and GitHub Flavored Markdown adds tables, task lists and strikethrough on top. For everyday writing they agree; differences only bite with exotic constructs.
Can I use HTML inside Markdown?
Yes — raw HTML passes straight through in most renderers. It is the official escape hatch for anything Markdown cannot express, like embedded videos or styled divs. Use it sparingly; heavy HTML defeats the readability that makes Markdown worth using.
How do I force a line break?
End the line with two spaces before hitting return, or use a backslash at the end of the line. A single plain line break is treated as a space in standard Markdown — a deliberate choice inherited from the format's email roots.
Markdown vs rich text — which should I write in?
Write in Markdown when the text has a future: documentation, notes, anything version-controlled or published. Use rich text for one-off messages where formatting is the point. Markdown's edge is that the source is the backup — readable forever, convertible to anything.
Conclusion
Markdown is a twenty-minute investment that compounds for years. Learn the dozen marks above, write everything in a plain-text editor, and stop thinking about formatting software. Your words become portable, future-proof, and publishable anywhere — which was the whole idea.