What Is Markdown?

A plain-text formatting language

Markdown is a lightweight markup language for adding formatting — headings, bold and italic text, links, lists, and code — to plain text using a small set of punctuation-based conventions. A single asterisk pair makes text italic, a double pair makes it bold, and a leading hash sign turns a line into a heading. There's no separate file format to learn and no application required to write it: a Markdown document is a .md or .txt file you can open in any text editor.

The defining idea is that unformatted Markdown should already be readable and make sense as plain text — unlike HTML, where a paragraph wrapped in <p><strong> tags is considerably harder to read in its raw form than the rendered output. Markdown is then converted, or “rendered,” into HTML (or another format) for display.

A brief history

Markdown was created by John Gruber in 2004, with input on the syntax from Aaron Swartz. Gruber's original goal, stated in the format's first release notes, was a syntax that was “as easy-to-read and easy-to-write as is feasible” — readable enough that a plain-text email or forum post using it would still make complete sense to someone who had never seen Markdown before.

That original specification, however, left several edge cases ambiguous — different tools disagreed on how to handle things like nested lists or emphasis next to punctuation. In 2014, a group including Jeff Atwood and John MacFarlane published CommonMark, a strict, unambiguous specification designed to make Markdown behave the same way across every implementation. Most modern Markdown parsers — including the one behind this site's own tools — are built on CommonMark.

A short example

Here's what that "readable even unrendered" idea looks like in practice. This plain text:

## Weekly update

Shipped the new **onboarding flow** and fixed the *login redirect* bug.

Next up:
- Finish the billing page
- Write release notes

renders as a heading, a paragraph with one bold and one italicized phrase, and a two-item bullet list — but even before it's rendered, you can already read it and understand exactly what it says. That's the whole point of the format.

Where Markdown is used today

Markdown has become the default plain-text formatting syntax across a huge range of tools:

• Developer platforms — GitHub, GitLab, and Bitbucket render README files, issues, and pull request descriptions written in Markdown.
• Chat and community tools — Reddit, Discord, and Slack all support a Markdown-like syntax for bold, italic, and code formatting in messages.
• Notes and docs apps — Notion, Obsidian, and many static site generators (Jekyll, Hugo, Next.js content layers among them) store content as Markdown files.
• Technical writing and blogging — documentation tools like GitBook and Read the Docs, and blogging platforms like Ghost and dev.to, all accept Markdown as their primary authoring format instead of a rich-text editor.
• Data science notebooks — Jupyter and similar notebook tools use Markdown cells for narrative text and explanations alongside executable code cells.
• Large language models — chat-based AI tools like ChatGPT and Claude format most of their responses in Markdown, since it lets them signal headings, lists, and code blocks with very little extra text. See Markdown for LLMs for more on why.

CommonMark vs. GitHub Flavored Markdown

Most of what people mean when they say “Markdown” today is one of two related things:

In practice, GFM is what most people write day to day — it's the syntax GitHub renders, and the one this site's own tools support. See the Markdown cheat sheet for the full reference, including exactly which rows are CommonMark and which are GFM extensions.

The distinction matters in practice when you move a document between tools: paste a table or a task list into a parser that only implements strict CommonMark, and the table markup falls back to a plain paragraph and the checkboxes stay literal [ ] text instead of rendering. If a piece of Markdown looks right on GitHub but breaks somewhere else, a GFM-only feature is usually why.

First steps

If you're new to Markdown, three pieces of syntax cover most of what you'll need to start: a hash sign for a heading (# Heading), asterisks for emphasis (**bold** or *italic*), and a dash for a list item (- item). Everything else — tables, code blocks, links — builds on the same plain-text logic.

The fastest way to get a feel for it is to write a short document and watch it render. Open the Markdown editor and type a few lines — the preview pane updates as you go, so you can see exactly what each piece of syntax produces. Keep the cheat sheet open in another tab while you get used to the syntax.

Why it stuck around

Plenty of markup languages existed before Markdown, and plenty have launched since. What kept Markdown relevant for two decades is that it never asked anyone to install anything or learn a heavyweight toolchain — it's just text, so it works in an email client, a terminal, a chat box, or a code editor without any special support. That low barrier is also why it's a natural fit for machine-generated content: a script, an API response, or a language model can emit Markdown with a plain string, and it will still be legible whether or not the receiving end knows how to render it. Two decades after Gruber's original release, that combination — human-readable, machine-writable, effectively zero-dependency — is still the reason Markdown keeps showing up in new tools rather than being replaced by them.