Markdown is a set of conventions for marking up plain text. A # at the start of a line means a heading. Text between two asterisks becomes bold. A line starting with - becomes a bullet. Nothing is hidden: the file contains exactly the characters you typed, and a program called a renderer turns those characters into headings, lists and links when it displays them.

That single property explains most of Markdown's appeal. A Word file is a compressed archive you cannot read without Word. A Markdown file is legible in Notepad, in a terminal, in an email, in a diff. The formatting is a suggestion carried in the text itself.

John Gruber published Markdown in 2004, with input from Aaron Swartz on the syntax. Gruber's goal was narrow and worth repeating: a Markdown document should be publishable as-is, readable as plain text, without looking like it was covered in tags. The conventions he chose were mostly borrowed from how people already formatted plain-text email — asterisks around a word for emphasis, a row of dashes under a title.

The original release was a Perl script that converted Markdown to HTML. That is still the core job. Markdown is not a replacement for HTML; it is a shorthand that expands into it, covering the handful of elements writers actually use.

A file ending in .md (or the longer .markdown) is a plain text file. There is no special encoding, no hidden structure, nothing that can carry a macro or a virus. Rename a .md file to .txt and it opens the same; the extension only tells your computer which app to suggest.

You can open one in any text editor, but a text editor shows you the raw symbols. To read it formatted, drop it into a viewer, open it in an editor with a preview pane such as VS Code or Obsidian, or push it to GitHub, which renders .md files automatically. Our Markdown file viewer does it in the browser without uploading the file anywhere.

This is close to the smallest example that shows why the format is useful. Read the left column on its own and it still makes sense as a note to a colleague — that is the test Gruber set. Read the rendered version and you get a heading, a bold phrase, a bulleted list and a working link, without a single tag.

More places than most people notice. GitHub and GitLab render every README, issue and pull request description as Markdown. Notion, Obsidian, Bear, Joplin and Logseq either store notes as Markdown or accept it as you type. Static site generators such as Jekyll, Hugo, Astro and Next.js treat Markdown files as pages. Reddit and Stack Overflow use it for comments.

Slack and Discord support a partial dialect: bold, italic, strikethrough, inline code and code blocks work; headings, tables and inline links generally do not. And when ChatGPT or Claude replies with neat headings and bullets, it is emitting Markdown — which is why copying that answer into an email sometimes pastes a wall of asterisks.

Against Word: Word stores appearance — point sizes, fonts, colours — inside a binary file. Markdown stores intent. You write "this is a heading" and whatever renders it decides what a heading looks like. That makes Markdown poor for a designed brochure and excellent for documentation, notes and anything kept in version control, where a one-word change should show as a one-word diff.

Against HTML: HTML can express anything; Markdown covers maybe the twenty elements writers use daily, in a fraction of the characters. **bold** beats <strong>bold</strong>. Where Markdown falls short, many renderers let you drop raw HTML in — though not all do, and ours deliberately does not, for safety.

Gruber's 1.0 description left real ambiguities, so implementations diverged. CommonMark, published in 2014, is the strict specification that most modern parsers follow for the core syntax. On top of it sit flavors: GitHub Flavored Markdown adds tables, task lists, strikethrough and automatic links, and is the de facto standard today. Others add footnotes, maths, callouts or wiki-style [[links]].

The practical rule: headings, emphasis, lists, links, images, quotes and code blocks work everywhere. Anything beyond that, check before you rely on it. The cheat sheet marks what is core and what is an extension.

Almost always because whatever you pasted into does not render Markdown — an email client, a Google Doc, a form field. The text is fine; the destination is plain. Convert it first, or use a renderer.

The other common causes are real syntax slips. A heading needs a space after the #. A list or a table needs a blank line above it if a paragraph comes first. Emphasis inside a word (snake_case_name) can be ignored or can mangle the word, depending on the parser. And underscores or asterisks with a space after the opening marker never produce emphasis at all: * not italic * stays literal.