You open a GitHub repository and the first thing you see is a nicely formatted page with headings, bullet points, and code blocks — but the source file is just plain text with some asterisks and pound signs scattered around. That's Markdown, and once you understand it, you'll realize it's everywhere.
Markdown is a lightweight markup language created by John Gruber in 2004. The core idea is simple: write plain text that looks good as-is, but can also be converted to HTML automatically. A line starting with # becomes an <h1>. Text wrapped in ** becomes <strong>. The raw file is readable without any rendering, which is the whole point.
Why Markdown won
Before Markdown, people writing for the web had two options: write raw HTML (tedious and noisy) or use a rich-text editor (which produces bloated, unpredictable output). Markdown threads the needle. It's fast to type, easy to read in source form, and converts cleanly to HTML.
That combination explains why it spread so fast. GitHub adopted it for READMEs in 2009. Stack Overflow used it for answers. Blogging platforms, documentation tools, note-taking apps, and chat clients all followed. Today if you write anything technical — code comments, pull request descriptions, API docs, personal notes — you're almost certainly writing Markdown.
The syntax in five minutes
You don't need to memorize everything at once. These eight patterns cover 95% of what you'll actually use.
Headings use # symbols. One # for the top-level heading, ## for the second level, down to ###### for the sixth. Most documents only use two or three levels in practice.
Emphasis uses asterisks or underscores. **bold** renders as bold. _italic_ renders as italic. Combine them: **_bold and italic_**.
Lists are exactly what they look like. Unordered lists start each line with - or * . Ordered lists use numbers: 1., 2., 3.. Indent two spaces to nest a sub-list inside another.
Links follow the pattern [link text](URL). Images use the same pattern with a leading exclamation mark: .
Code uses backticks. A single backtick wraps inline code: `console.log()`. Triple backticks create a fenced code block, and you can add a language name for syntax highlighting:
```javascript
function add(a, b) {
return a + b;
}
```
Blockquotes start with > . Nest them with >> .
Tables use pipes and dashes. The second row defines column alignment with colons:
| Name | Role |
|---------|-----------|
| Alice | Engineer |
| Bob | Designer |
Horizontal rules are three or more dashes on their own line: ---.
GitHub Flavored Markdown
The original Markdown spec left some things undefined, so GitHub published their own extension called GitHub Flavored Markdown (GFM). It's now the de-facto standard for anything code-related.
GFM adds a few things the original spec doesn't have. Task lists let you create checkboxes: - [x] done and - [ ] pending. Strikethrough wraps text in tildes: ~~removed~~. Tables are part of GFM (they're not in the original spec). Autolinks turn bare URLs into clickable links automatically.
GFM also defines alerts — a way to call out important information with a specific tone:
> [!NOTE]
> This feature requires Node.js 18 or later.
> [!WARNING]
> This action cannot be undone.
Most platforms that render Markdown — GitHub, GitLab, VS Code, many documentation sites — support GFM or a close superset of it.
CommonMark: the standardization effort
The original Markdown spec was deliberately vague in places, which led to different renderers making different choices for edge cases. CommonMark is a standardization project that nails down the ambiguities with a detailed spec and a conformance test suite.
For practical purposes, CommonMark and GFM are compatible. If you write standard Markdown without relying on renderer-specific quirks, your documents will look correct everywhere.
Where Markdown is used
GitHub and GitLab — Every README, issue, pull request description, wiki page, and release note is Markdown. Learning Markdown is essentially a requirement for contributing to open-source projects.
Documentation sites — Tools like MkDocs, Docusaurus, and VitePress take a folder of Markdown files and turn them into a full documentation website. You write plain text; the tool handles navigation, search, and styling.
Static site generators — Hugo, Jekyll, Eleventy, and Astro all use Markdown for page content. This site's blog posts are Markdown files.
Note-taking apps — Obsidian stores everything as plain Markdown files on disk. Notion uses a Markdown-inspired syntax. Typora, Bear, and iA Writer are dedicated Markdown editors. Because the format is plain text, your notes aren't locked into any proprietary format.
Chat and messaging — Slack, Discord, and Microsoft Teams all support a subset of Markdown for message formatting. Asterisks make text bold, backticks format code, and triple backticks create code blocks.
Common mistakes to avoid
Forgetting blank lines around block elements. A heading or code block needs an empty line before and after it in many renderers. When in doubt, add the blank line.
Mixing list marker styles. - and * both work for unordered lists, but mixing them in the same list makes the source harder to read. Pick one and stick with it.
Using indented code blocks unintentionally. Any line indented by four spaces becomes a code block in standard Markdown. This trips people up inside lists, where indentation means something different.
Forgetting the language on code blocks. A fenced code block without a language label won't get syntax highlighting. Always add the language name: ```python, ```bash, ```json.
Markdown vs other formats
HTML — Markdown compiles to HTML, so anything Markdown can do, HTML can do. The difference is ergonomics: Markdown is much faster to write for prose and simple formatting. Most Markdown renderers also accept inline HTML for the cases where Markdown falls short.
reStructuredText — Python's documentation ecosystem uses reStructuredText (reST). It's more powerful than Markdown but significantly more verbose. Unless you're working on Python documentation, you'll rarely need it.
AsciiDoc — A more powerful alternative with better support for technical documentation features like cross-references and conditional content. Used by some large open-source projects. More complex than Markdown.
For everyday technical writing — READMEs, blog posts, notes, API documentation — Markdown hits the sweet spot. It's simple enough to learn in an afternoon, but expressive enough to handle almost anything you'd actually want to write.