MarkdownForge

What is Markdown?

Markdown is a way to format text using ordinary characters, so a document reads cleanly as plain text and converts to HTML without any clicking.

Instead of pressing a Bold button, you type **two asterisks** around a word. Instead of choosing “Heading 1” from a menu, you start the line with #. A program called a Markdown parser reads those symbols and produces formatted output, usually HTML.

John Gruber designed it in 2004, with Aaron Swartz, around one goal: a Markdown document should be publishable as-is, as plain text, without looking like it’s been marked up with tags. Twenty years later it’s the default writing format for developers and a growing number of writers.

How a Markdown parser works

Step through what happens between typing and seeing. This uses the real parser behind this site (markdown-it, which follows the CommonMark spec). Edit the text and every step updates.

Step 1 of 5: Source text

What you type. Just characters and line breaks. Nothing is formatted yet.

# Grocery list

Buy **fresh** basil and
a [lemon](https://example.com).

- tomatoes
- olive oil

Seeing each stage laid out is the quickest way to understand what a parser is doing. If you like learning this way, ahaboo has narrated, interactive explainers on how everyday things work, from why the seasons happen to how compound interest grows.

Why people use Markdown

  • It’s portable. A .md file is plain text. It opens on any computer, diffs cleanly in git and will still be readable in 30 years.
  • It’s fast. Your hands stay on the keyboard. No menus, no toolbar hunting.
  • It separates content from design. The same file can become a web page, a PDF, a Word document or slides, each with its own styling.
  • It’s everywhere. GitHub, GitLab, Reddit, Discord, Slack, Stack Overflow, Obsidian, Notion, Jupyter notebooks and most static site generators understand it. AI chatbots answer in Markdown by default.

The standards: CommonMark and GFM

Gruber’s original description left edge cases open, so different tools rendered the same text differently. In 2014 a group including John MacFarlane (author of Pandoc) published CommonMark, a precise specification with hundreds of test cases. GitHub built GitHub Flavored Markdown on top of it in 2017, adding tables, task lists, strikethrough and autolinks. Those two specs are what “Markdown” means in practice today.

A 30-second example

This source:

## Trip checklist

- [x] Passport
- [ ] **Charger**
- [ ] Book: *The Overstory*

renders as a level-2 heading and a checklist with “Charger” in bold and the book title in italics. Try it in the online Markdown editor, or keep the cheat sheet open while you write.

Markdown vs. a word processor

A word processor stores formatting invisibly and shows you the result (what you see is what you get). Markdown shows you the formatting as symbols and lets a program produce the result. The trade-off: Markdown can’t do complex page layout, but it’s far better for anything that lives in version control, gets published to the web, or needs to be converted to several formats. When you need a Word file, convert it.

Questions people ask

What is Markdown used for?
READMEs and documentation, notes (Obsidian, Notion, Bear), blog posts in static site generators, chat formatting (Slack, Discord), forum posts (Reddit, Stack Overflow), and prompts and responses in AI chat tools.
Who created Markdown?
John Gruber created Markdown in 2004, with significant input from Aaron Swartz, and published it with a Perl script that converted it to HTML.
What is a .md file?
A plain-text file containing Markdown. Any text editor can open it; a Markdown viewer or editor shows it formatted.
Is Markdown a programming language?
No. It is a lightweight markup language: it describes structure (this is a heading, this is a list) but has no logic, variables or loops.
Markdown vs HTML: which should I use?
Markdown for writing, because it’s faster and readable as plain text. HTML when you need layout or elements Markdown lacks. Most Markdown renderers let you mix raw HTML in where needed.