Markdown: Write Once, Publish Anywhere
The simplest way to format text that works on GitHub, Notion, blogs, and almost everywhere else.
You need to write documentation. Or a README. Or a blog post. Or a Slack message with formatting.
HTML is overkill. Word documents don't work everywhere. Plain text has no formatting.
Markdown sits in the sweet spot. Simple syntax, readable as plain text, converts to HTML when needed.
The Basics
# Heading 1
## Heading 2
### Heading 3
**bold** and *italic*
- Bullet point
- Another point
- Nested point
1. Numbered list
2. Second item
[Link text](https://example.com)
That's most of what you need.
Code Formatting
Inline code with backticks: console.log('hello')
Code blocks with triple backticks:
function hello() {
return 'world';
}
Specify the language after the opening backticks for syntax highlighting.
Tables
| Name | Role |
|-------|------------|
| Alice | Developer |
| Bob | Designer |
Tables are fiddly to type. Most editors have shortcuts.
Blockquotes
> This is a quote.
> It can span multiple lines.
Use for callouts, quotes, or emphasizing important text.
Why Markdown Works
Readable source. Even without rendering, Markdown is easy to read. **bold** is obviously bold.
Portable. GitHub, Notion, Slack, Reddit, countless static site generators. Write once, paste anywhere.
Version control friendly. It's plain text. Git diffs make sense. Merges work.
Future-proof. No proprietary format. Your content is accessible forever.
Flavor Differences
GitHub Flavored Markdown (GFM) adds checkboxes, tables, and syntax highlighting.
CommonMark is the standardization effort. Most platforms support it.
Some platforms add extras: Obsidian has wikilinks, Notion has databases.
For maximum portability, stick to basic syntax.
Common Mistakes
Forgetting blank lines. Paragraphs need blank lines between them. Without them, everything runs together.
Spaces after headings. #Heading doesn't work. # Heading does. Note the space.
Broken links. Missing the https:// makes links fail on some platforms.
Images without alt text.  works but isn't accessible. Add descriptions.
Writing Tips
Use headings for structure. Readers scan before reading.
Keep paragraphs short. White space helps readability.
Preview before publishing. Different renderers handle edge cases differently.
Markdown removes friction from writing. Learn the basics once, use them everywhere. The simplicity is the feature.