What Is Markdown? A Plain-English Guide

The first time someone showed me a Markdown file, I thought it looked unfinished — like notes a person meant to clean up later. Hash marks in front of headings, asterisks hugging a word here and there, a few dashes starting lines. Then they ran it through a previewer and the scruffy-looking text snapped into a clean, formatted page: real headings, bold where the asterisks were, a proper bulleted list. The notes were the document. Nothing had to be cleaned up.

That's the whole idea of Markdown, and it's worth understanding on its own terms before you ever worry about tools or flavors.

Markdown is formatting you can read as plain text

Markdown is a lightweight markup language: a small set of punctuation conventions that stand in for formatting. You write a heading by starting a line with #. You make a word bold by wrapping it in **double asterisks**. You build a list by starting lines with -. A link is [the text](the-url). That's most of it.

The point John Gruber was chasing when he designed it in 2004 was simple: the source should be at least as readable as the output. Compare it to the alternative. In HTML, a bulleted list looks like this:

<ul>
  <li>First</li>
  <li>Second</li>
</ul>

In Markdown, the same list is just:

- First
- Second

One of those you can read comfortably without rendering it. That readable-in-the-raw quality is the thing that made Markdown spread.

Think of it like sheet music

A useful way to picture Markdown is sheet music. The notation on the page isn't the song — it's a compact set of marks a musician reads and turns into sound. Anyone who knows the symbols can follow the page directly, and the same sheet produces the same performance wherever it's played. Markdown works the same way: the marks on the page aren't the formatted document, they're instructions a processor performs into one, and the source stays legible to a human who knows the handful of symbols.

Where the formatting actually happens

Markdown doesn't format anything by itself. A Markdown processor reads your text and converts it into HTML, and HTML is what your browser, your README viewer, or your chat app actually renders. So the pipeline is always: you write Markdown → a processor turns it into HTML → something displays the HTML. If you want to see that step with your own eyes, paste text into a Markdown previewer and watch the raw marks become a formatted page, or run it through a Markdown to HTML converter to see the exact tags it produces.

This is also why Markdown and HTML aren't competitors — one is built out of the other. If you want the full picture of when to reach for each, I wrote about Markdown versus HTML separately, because the short version is that Markdown handles the prose and hands off to raw HTML for anything it can't express.

The core syntax, in one pass

You can get productive with a tiny vocabulary:

• Headings — one to six # marks: # Title, ## Section, ### Subsection.
• Bold and italic — **bold** and *italic* (or underscores, __bold__ and _italic_).
• Lists — - or * for bullets, 1. 2. 3. for numbered.
• Links and images — [text](url) for a link, ![alt text](url) for an image.
• Code — backticks for inline code, and three backticks to fence a whole block.
• Quotes — a leading > turns a line into a blockquote.

That really is the large majority of what day-to-day writing needs. Tables are the one common thing the original spec left out, which is why most tools adopted the GitHub table syntax as an add-on rather than it being part of the core.

Why it's everywhere now

Once you can recognize Markdown, you start seeing it in every text box you type into. GitHub renders READMEs, issues, and pull-request comments as Markdown. Reddit, Stack Overflow, Slack, Discord, Notion, Obsidian, and most static-site blog engines all accept some version of it. That ubiquity is the practical payoff: the same #, **, and - you learn once work in nearly every place a developer writes.

The catch is that these places don't all implement the exact same Markdown. The original 2004 spec deliberately left some corners undefined, so platforms filled them in differently. GitHub Flavored Markdown adds tables, task lists (- [ ] and - [x]), and strikethrough; CommonMark is an effort to pin down a strict, unambiguous standard; other tools add their own touches. These variants are called flavors, and the differences almost always live in the extras, not the basics. Headings and bold work the same everywhere; whether a table or a footnote renders depends on the flavor.

Getting started

The fastest way to learn Markdown is to stop reading about it and type some. Write a few lines — a heading, a bit of bold text, a list, a link — and drop them into a Markdown previewer to watch them render live. When you need to hand the result to something that only takes HTML, like an email template or a CMS field, convert it and tidy the output with an HTML formatter so you can read the structure. And when a table you need started as rows in a spreadsheet, skip the hand-typing and generate the Markdown from the data with a CSV to Markdown table converter.

Markdown isn't a tool you install or a language you study. It's a small, shared habit of writing — a few marks that turn plain text into a formatted page, readable at both ends of the process. Learn the six symbols and you can write for most of the modern web without ever opening a formatting menu again.