Markdown is a lightweight markup language that lets you format text using simple characters — asterisks for bold, hashes for headings, dashes for lists. It was created by John Gruber in 2004 with a single goal: make writing for the web as easy as writing plain text, while producing clean, readable HTML. Two decades later, Markdown is everywhere — GitHub READMEs, Reddit posts, Discord messages, Notion pages, documentation sites, and most modern blogging platforms all use it.
Why Markdown?
Before Markdown, formatting web content meant either writing raw HTML (<strong>bold</strong>) or using a rich text editor that produced messy, inconsistent HTML. Markdown gives you a third option: write in a natural, readable way and let the tool convert it to clean HTML automatically.
A Markdown file is just a plain text file. It opens in any text editor, it works in version control, and it renders beautifully when displayed. That combination of simplicity and portability is why it's become the default format for technical documentation.
Core Markdown Syntax
Headings
Use # symbols. More hashes = smaller heading.
# Heading 1
## Heading 2
### Heading 3
Bold and Italic
**bold text**
*italic text*
***bold and italic***
Lists
- Unordered item
- Another item
- Nested item
1. First ordered item
2. Second item
3. Third item
Links and Images
[Link text](https://example.com)
Code
Inline code uses backticks: `variable`
Fenced code blocks use triple backticks with an optional language name:
```javascript
const greeting = "Hello, World!";
console.log(greeting);
```
Blockquotes
> This is a quoted passage.
> It can span multiple lines.
Horizontal Rule
---
Tables
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Data |
| Row 2 | Data | Data |
How to Use the Markdown Preview Tool
- Write or paste Markdown in the left panel. You'll see raw Markdown syntax — asterisks, hashes, backticks.
- See the rendered output in the right panel, updated live as you type. What you see on the right is what the HTML will look like.
- Copy the Markdown to use in GitHub, Notion, a blog platform, or any Markdown-supporting tool.
- Copy the HTML if you need the raw HTML output for embedding in a website.
Where Markdown Is Used
GitHub — Every repository README is a Markdown file (README.md). Issues, pull request descriptions, and comments also support Markdown. It's the primary way developers communicate technical information on GitHub.
Reddit — Reddit's old.reddit.com interface uses Markdown for post and comment formatting. The new interface offers a rich text editor that generates Markdown under the hood.
Discord — Discord supports a subset of Markdown: **bold**, *italic*, `code`, code blocks, and ~~strikethrough~~.
Notion — Notion's editor accepts Markdown shortcuts. Type ## and press space to create a Heading 2, or - for a bullet list.
Jekyll and Hugo — Popular static site generators use Markdown files as their content format. Blog posts are .md files that get compiled into HTML during the build.
Documentation — Tools like MkDocs, Docusaurus, and GitBook use Markdown for technical documentation. The entire docs for many major open-source projects are written in Markdown.
Tips
- Blank lines matter — In Markdown, a blank line separates paragraphs. Without it, consecutive lines merge into one paragraph.
- Escape special characters — If you need a literal asterisk or hash that isn't formatting, prefix it with a backslash:
\*renders as*. - Consistent heading hierarchy — Use
#only once per page (for the main title), then##for sections,###for subsections. Don't skip levels. - Preview before publishing — Always render your Markdown before pasting it somewhere. Missing a closing
**makes everything from that point bold.
Frequently Asked Questions
What's the difference between Markdown and HTML?
HTML is a markup language where you wrap content in tags: <p>text</p>. Markdown is a shorthand that converts to HTML. Markdown is faster to write; HTML gives you more control. In most Markdown editors, you can mix both — raw HTML embedded in a Markdown file is usually rendered correctly.
Why does my Markdown look different on different platforms? Different platforms implement slightly different versions of Markdown. GitHub Flavored Markdown (GFM) adds features like tables and task lists that aren't in the original spec. When writing for a specific platform, check its Markdown documentation.
Can I include images in Markdown?
Yes, with . The image must be hosted somewhere accessible. Most platforms also support drag-and-drop image upload that inserts the Markdown syntax automatically.
Is Markdown case-sensitive?
No — **bold** and **BOLD** both render as bold. The formatting syntax uses specific characters, not case.