Markdown Explained: From Plain Text to Formatted HTML

Markdown is plain text written so a machine can turn it into HTML — and so a human can still read the source comfortably in the meantime. Every asterisk, hash, and dash has a job: the punctuation is the formatting, which is why a Markdown file reads like an organized text note and renders like a structured web page.

Where Markdown came from

John Gruber and Aaron Swartz released Markdown in 2004 as a two-part pitch: an easy-to-read, easy-to-write plain text format, and a converter that turns it into structurally valid HTML. Writers adopted it immediately because it solved a real annoyance — hand-tagging every paragraph in HTML meant typing more markup than prose. Markdown's conventions mostly predate the tool: *emphasis* was already how people added emphasis in plain-text email, so the source language was designed to be publishable as-is.

The core syntax

A dozen patterns cover most documents. Each is ordinary punctuation that names an HTML element:

# Heading one     →  <h1>Heading one</h1>
## Heading two    →  <h2>…
**bold**          →  <strong>bold</strong>
*italic*          →  <em>italic</em>
`code`            →  <code>code</code>
[text](url)       →  <a href="url">text</a>
![alt](img.png)   →  <img alt="alt" src="img.png">
- item            →  <ul><li>item</li></ul>
1. item           →  <ol><li>item</li></ol>
> quoted line     →  <blockquote>quoted line</blockquote>
---               →  <hr>

Headings count their hash marks: one through six map to h1 through h6. Inline patterns — bold, italic, code, links — wrap content in place, while block patterns — headings, lists, blockquotes — claim whole lines. To write a literal asterisk instead of emphasis, escape it with a backslash: \*.

Blocks, inline, and the blank line

The invisible character doing the most work is the empty line. Consecutive lines of text form one paragraph; a blank line ends the paragraph and starts a new one, and the converter emits a <p> element for each block. Inside a paragraph, single newlines become spaces or <br> depending on the implementation. This block/inline split explains most paste accidents: a list that "loses its formatting" after pasting usually just lost the blank line that separated it from the paragraph above.

Flavors: CommonMark and GitHub-Flavored Markdown

The original spec left details loose, so renderers disagreed — nested lists and underscore emphasis were notorious battlegrounds. CommonMark is the modern, rigorously specified core, and GitHub-Flavored Markdown (GFM) extends it with the table syntax, strikethrough (~~struck~~), and task lists (- [x]) that most people now treat as standard Markdown. Tables are the most-used extension, built from pipes:

| Name  | Qty |
| ----- | --- |
| Bolts | 24  |
| Nuts  | 24  |

The header separator row (| --- |) is what makes it a table rather than three paragraphs of pipes; alignment can be declared per column with :---, :--:, or ---: for left, center, and right. Because hand-spacing pipes is fiddly, the two jobs people actually need are generating a table from data they already have and realigning a table someone else wrote crooked.

How the conversion actually works

A Markdown-to-HTML converter is a pipeline of text patterns mapping to tags: headings matched line by line, consecutive list items gathered into <ul> or <ol> wrappers, emphasis replaced inside paragraphs. One step matters more than it looks: escape the HTML first. Turning <, >, and & into entities before any pattern matching means everything you paste is treated as text, never as markup that could inject tags into the output — the same discipline described in How HTML Entities Work. The reverse direction exists too: a two-way converter can walk HTML back into Markdown, which is how you rescue a page's copy into an editable note instead of retyping it.

Try it yourself

Paste a document into the Markdown to HTML Converter and check that headings, lists, and code blocks come out as the elements you expect — it supports headings, bold, italic, links, images, ordered and unordered lists, fenced code blocks, blockquotes, and horizontal rules. Use the Markdown to HTML Converter (Two-Way) to round-trip in both directions. For tables, the Markdown Table Generator builds a GitHub-flavored table from CSV, tab-, pipe-, or whitespace-separated data, and the Markdown Table Formatter takes a messy table and returns it with aligned pipes and consistent separators.