Plain text that formats itself
Markdown is a lightweight markup language created by John Gruber in 2004. The idea is simple: write plain text with a few special characters, and it converts automatically to formatted HTML. Instead of clicking a “Bold” button, you wrap text in **asterisks**. Instead of a heading button, you put a # at the start of a line.
Markdown is now everywhere in software development: GitHub READMEs, documentation sites, static site generators, note-taking apps, messaging platforms like Slack and Discord, and increasingly in content management systems. If you write anything in a technical context, you’ll encounter Markdown.
Preview your Markdown formatting in real time with Markdown Preview.
The essential syntax
Headings — Use # for H1, ## for H2, ### for H3, and so on up to H6. The number of # characters determines the heading level.
Bold and italic — Wrap text in **double asterisks** for bold, *single asterisks* for italic. You can combine them: ***bold and italic***.
Links — [link text](https://example.com) creates a hyperlink. The text in square brackets is what users see; the URL in parentheses is where they go.
Images — Same syntax as links but with a ! prefix: .
Lists — Unordered lists use - or * at the start of each line. Ordered lists use 1., 2., 3.. Indent with two spaces to create nested lists.
Code — Wrap inline code in backticks: `code here`. For code blocks, use triple backticks with an optional language name:
```javascript
const greeting = "hello world";
console.log(greeting);
```Blockquotes — Start a line with > to create a blockquote. Useful for quoting text or callout boxes.
Horizontal rule — Three dashes --- on their own line creates a horizontal divider.
Why developers prefer it over rich text editors
It’s version-controllable — Markdown is plain text. You can commit it to Git, diff it, review changes, and merge branches. A Word document or Google Doc can’t do this.
It’s portable — A .md file opened in any text editor twenty years from now will still be readable. Proprietary formats lock you into specific tools.
It’s fast — Formatting with a keyboard shortcut or special character is faster than reaching for a mouse to click a toolbar button once you’ve learned the syntax.
It stays out of the way — Markdown files don’t have styling, fonts, or margins to worry about. The focus stays on the content.
It converts cleanly — Markdown-to-HTML conversion is predictable and produces clean markup. Many static site generators (Jekyll, Hugo, Astro) build entire websites from Markdown files.
Where Markdown is used
GitHub and GitLab — Every repository README is a Markdown file. Pull request descriptions, issue comments, and wiki pages all support Markdown.
Documentation sites — Most technical documentation is written in Markdown or an extended variant. Tools like Docusaurus, MkDocs, and GitBook build documentation sites directly from Markdown files.
Static site generators — Astro, Next.js, Jekyll, Hugo, and Eleventy all support Markdown as a content format. Blog posts, pages, and documentation are often Markdown files that get compiled to HTML at build time.
Note-taking apps — Obsidian, Notion, Bear, and Typora all use Markdown as their core format or offer Markdown mode.
Messaging platforms — Slack, Discord, and many other platforms support a subset of Markdown for formatting messages.
Markdown flavors and extensions
The original Markdown spec left some things ambiguous, leading to variations. The most important ones:
CommonMark — A standardized specification that resolves ambiguities in the original spec. Most modern tools follow CommonMark.
GitHub Flavored Markdown (GFM) — Extends CommonMark with tables, task lists (- [x] item), strikethrough (~~text~~), and automatic URL linking.
MDX — Markdown with JSX, used in React-based documentation sites. Allows embedding React components inside Markdown files.
When you’re writing for a specific platform, check which Markdown variant it uses — most of the syntax is the same, but extensions differ.
Preview any Markdown document with Markdown Preview to verify formatting before publishing.