Plain Text with Superpowers
The first time I encountered Markdown was on GitHub. A project's README had headings, bold text, bullet lists, code blocks, even tables — all looking polished and professional. Then I viewed the source: just a plain .md text file with some # signs and * characters.
No Word document. No design software. Just a few symbols turning plain text into structured, readable content.
That's the appeal of Markdown in a nutshell.
What Is Markdown?
Markdown is a lightweight markup language that uses simple symbols to represent formatting. You write in plain text, and it converts to HTML for display.
Created in 2004 by John Gruber, the design philosophy was that the raw source should be readable even without rendering. And it is — a Markdown file makes sense whether you're reading it formatted or viewing the raw text.
Today Markdown is everywhere: GitHub, Notion, HackMD, Reddit, Discord, Slack, and countless other platforms.
Syntax Quick Reference
The fastest way to learn is to write some Markdown while seeing the result in real time.
Headings
Use # symbols. More hashes = smaller heading:
# Heading 1 (largest)
## Heading 2
### Heading 3
#### Heading 4
Typically one # per document (the title), then ## and ### for sections. You'll rarely need four levels.
Bold and Italic
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
Two asterisks for bold, one for italic. I use bold for emphasis on key terms. Italic is less common in practice — it doesn't render as distinctly in many fonts.
Lists
- Unordered item one
- Item two
- Sub-item
- Another sub-item
1. Ordered item one
2. Item two
3. Item three
Use -, *, or + for unordered lists. Indent sub-items with two spaces.
Links and Images
[link text](https://example.com)
Images are just links with a ! prefix.
Blockquotes
> This is a quoted passage
> that can span multiple lines
Useful for citing sources or highlighting key statements.
Code
Inline code uses backticks: `console.log("hello")`
Code blocks use triple backticks:
```javascript
function greet(name) {
console.log(`Hello, ${name}!`);
}
```
Adding the language name after the opening backticks enables syntax highlighting.
Tables
| Column A | Column B | Column C |
|----------|----------|----------|
| Data 1 | Data 2 | Data 3 |
| Data 4 | Data 5 | Data 6 |
Table syntax looks fiddly but becomes second nature after a few uses. The alignment of pipes and dashes is purely cosmetic — the parser doesn't care.
You don't need to perfectly align the table separators. The Markdown parser ignores extra spaces. But if you frequently read raw Markdown, aligned tables are much easier to scan.
Horizontal Rules
---
Three or more hyphens create a divider line. Useful for separating major sections.
Where Markdown Gets Used
GitHub / GitLab
READMEs, issues, pull requests, wikis — all Markdown. If you're a developer, Markdown fluency is non-negotiable.
Technical Documentation
Many open-source projects write their docs in Markdown and render them with tools like GitBook, Docusaurus, or VitePress. Learn the syntax once, contribute anywhere.
Note-Taking Apps
Notion, Obsidian, HackMD, Bear, Typora — the trend toward Markdown-compatible note apps keeps growing. One syntax works across all of them.
Blogs
Static site generators (Hugo, Gatsby, Next.js) use Markdown for content. The article you're reading right now was written in Markdown.
Messaging
Discord and Slack support Markdown subsets. Using **bold** or `code` in messages makes them clearer and more scannable.
Markdown vs Word
They serve different purposes rather than competing.
Markdown strengths:
- Plain text files — tiny, portable, opens in any editor
- Integrates perfectly with Git version control (try diffing a .docx)
- Forces focus on content over formatting
- Converts to HTML, PDF, slides with the right tools
Word strengths:
- Complex layouts (headers, footers, columns, floating images)
- Track changes and commenting
- More accessible to non-technical users
- Standard format in business environments
Rule of thumb: technical docs, notes, and blog posts → Markdown. Business reports and formal documents → Word.
Need to convert between formats? Pandoc is an open-source tool that converts Markdown to virtually any document format — Word, PDF, HTML, LaTeX, and more.
Advanced Syntax
Once you're comfortable with the basics:
Task Lists
- [x] Completed task
- [ ] Pending task
Especially common in GitHub issues for tracking progress.
Footnotes
Here's a statement with a footnote[^1].
[^1]: The footnote content.
Math Notation Some platforms support LaTeX-style math:
Inline: $E = mc^2$
These advanced features aren't universally supported. Check your target platform before relying on them.
Wrapping Up
Markdown has one of the gentlest learning curves of any technical skill. Five minutes reading the syntax, a few minutes practicing in the preview tool, and you're productive. It won't replace every document format, but for a surprising number of writing situations, Markdown is the simplest and cleanest approach available.