What is Markdown? A Beginner's Guide

Markdown was created in 2004 by John Gruber with help from Aaron Swartz. Gruber was frustrated by the verbosity of HTML. He wanted a way to write for the web that was as readable as plain text but could be converted to valid HTML with a simple script.

The design philosophy was straightforward: a Markdown document should be "publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions." In other words, even without rendering, a Markdown file should be perfectly readable.

The original Markdown was a Perl script that converted .md files to HTML. Since then, multiple implementations have appeared — CommonMark (a standardized spec), GitHub Flavored Markdown (GFM), and many more. The core syntax, however, has remained remarkably stable for over two decades.

Markdown has become the de facto standard for writing technical content, documentation, and notes. Here's why millions of people prefer it:

• It's fast. No reaching for toolbar buttons or menu items. Type **bold** and keep writing. Your hands never leave the keyboard.
• It's portable. Markdown is plain text. It works in any text editor, on any operating system, and will be readable decades from now. Your notes won't be locked in a proprietary format that might stop being supported.
• It's everywhere. GitHub, GitLab, Reddit, Discord, Slack, Notion, Obsidian, Stack Overflow, Jupyter notebooks, static site generators — they all support Markdown.
• It's easy to learn. You can learn the essentials in about 10 minutes. The syntax is designed to be intuitive — *italic* for italic, # Header for a header.
• It converts to anything. Markdown can be converted to HTML, PDF, Word documents, slides, and more. Tools like MarkdownFTW make conversion effortless — write once, export to any format you need.

Here are the fundamental building blocks of Markdown. For a comprehensive reference, check out our full Markdown syntax guide.

Headers

Use # symbols to create headings. More symbols = smaller heading:

# Heading 1 (largest)
## Heading 2
### Heading 3
#### Heading 4

Emphasis

Wrap text in asterisks or underscores:

*italic text*
**bold text**
***bold and italic***
~~strikethrough~~

Links and Images

Links use square brackets for the text and parentheses for the URL:

[Link text](https://example.com)
![Alt text](image.jpg)

Lists

Use dashes, asterisks, or numbers:

- Unordered item
- Another item
  - Nested item

1. First item
2. Second item
3. Third item

Code

Inline code uses single backticks. Code blocks use triple backticks with an optional language:

Use `inline code` in a sentence.

```javascript
function hello() {
  console.log("Hello, Markdown!");
}
```

Blockquotes

Prefix lines with >:

> This is a blockquote.
> It can span multiple lines.

Markdown is used by an incredibly diverse range of people and platforms:

• Software developers — README files, pull request descriptions, documentation, code comments, and issue trackers all use Markdown.GitHub Flavored Markdown is one of the most popular dialects.
• Technical writers — Documentation sites built with tools like Docusaurus, MkDocs, VitePress, and Hugo are all written in Markdown.
• Bloggers and content creators — Static site generators (Jekyll, Gatsby, Next.js) commonly use Markdown for content.
• Students and researchers — Note-taking apps like Obsidian, Notion, and Bear use Markdown. Jupyter notebooks support it for inline documentation.
• Everyday communicators — Millions of people use Markdown daily on Discord, Slack, Reddit, and other chat platforms.

Because the original Markdown spec left some ambiguities, various "flavors" have emerged that extend the base syntax:

• CommonMark — A strict, well-defined specification that resolves ambiguities in Gruber's original spec. Most modern parsers follow CommonMark.
• GitHub Flavored Markdown (GFM) — Extends CommonMark with tables, task lists, strikethrough, and autolinks. It's probably the most widely used flavor today. Learn more about GFM →
• MultiMarkdown — Adds footnotes, metadata, math, definition lists, and more.
• R Markdown — Integrates R code execution with Markdown for data science and statistical reporting.

The differences between flavors are usually minor. If you learn standard Markdown syntax, you'll be productive in any flavor.

The best way to learn Markdown is to start writing it. You don't need to install anything — just open a Markdown editor and experiment.

Here's a simple exercise to try right now:

# My First Markdown Document

Hello, world! This is **Markdown** in action.

## Things I want to learn

- [x] Basic syntax
- [ ] Tables
- [ ] Code blocks
- [ ] Advanced features

> "The best time to learn Markdown was yesterday.
> The second best time is now."

Check out [MarkdownFTW](https://markdownftw.com) for a
free editor with live preview.

Paste that into any Markdown editor and you'll see it transform into beautifully formatted content. For a deeper dive into syntax, head to our complete Markdown syntax guide.