What Is Markdown? A Beginner's Guide With Live Preview

Markdown is a lightweight plain text format that lets you write formatted content — headings, bold text, lists, links, code — using simple symbols instead of HTML tags. Type **bold** and it renders as bold. Type # Heading and it becomes a large heading. Try it live in Markdown Preview and you'll see the results instantly as you type.

This guide explains what Markdown is, why it became the standard for writing on the web and in developer tools, and covers the 10 most useful Markdown elements with examples you can test immediately.

What Is Markdown — and Why Does It Exist?

Markdown was created by John Gruber in 2004 with one goal: make it easy to write formatted text that looks readable as plain text AND converts cleanly to HTML. Before Markdown, the two main options were writing raw HTML (verbose, hard to read) or using a rich-text editor (not portable, not plain text).

Markdown hit a middle ground: use simple punctuation conventions that already look natural in plain text. Asterisks around a word (*like this*) suggest emphasis — and they create emphasis when rendered. A pound sign at the start of a line (# Heading) looks like a heading — and it becomes a heading.

Today Markdown is the default writing format for:

• GitHub README files and comments
• Notion, Obsidian, Roam Research, and most note-taking apps
• Reddit posts and Discord messages
• Developer documentation platforms (Read the Docs, GitBook, Docusaurus)
• Static site generators (Jekyll, Hugo, Gatsby, Astro)

The 10 Most Useful Markdown Elements (With Examples)

Paste these into Markdown Preview to see them render live:

# Heading 1
## Heading 2
### Heading 3

**Bold text**
*Italic text*
~~Strikethrough~~

- Unordered list item
- Another item
  - Nested item

1. Ordered list
2. Second item

[Link text](https://example.com)

![Alt text](image-url.jpg)

`inline code`

```javascript
// Code block with syntax highlight
const x = 42;
```

> Blockquote text

---  (horizontal rule)

| Column 1 | Column 2 |
|----------|----------|
| Cell A   | Cell B   |

These 10 elements cover roughly 95% of everyday Markdown use. Master these and you can write for any Markdown-based platform.

Sell Custom Apparel — We Handle Printing & Free Shipping

Where You'll Encounter Markdown

Once you learn Markdown, you'll start seeing it everywhere:

• GitHub: Every README.md, issue, pull request comment, and wiki page uses Markdown
• Notion: Slash commands and paste-as-Markdown are built on Markdown syntax
• Obsidian: All notes are stored as .md files — your notes are portable plain text forever
• Reddit: Old Reddit uses Markdown for posts and comments
• Discord: Uses Markdown for bold, italic, code, and strikethrough in messages
• Slack: Supports a subset of Markdown in messages
• Static sites: Most modern site builders (Hugo, Jekyll, Astro) accept .md content files

Common Markdown Mistakes Beginners Make

These are the formatting issues that trip up new Markdown writers most often:

• No blank line before a list: Lists need a blank line above them, or they render as plain text on some platforms.
• Forgetting spaces after #: #Heading won't render as a heading — you need # Heading with a space after the pound sign.
• Single asterisk for bold: One asterisk (*text*) makes italic. Two (**text**) makes bold. Easy to mix up.
• Broken table separator: The second row of a table must have dashes (|---|) between the header and body rows.
• Image URL with spaces: Image and link URLs can't have spaces. Use %20 or quote the URL if it contains spaces.

The fastest way to catch these is to paste your Markdown into a preview tool immediately rather than writing a long document before checking.

Frequently Asked Questions

Do I need to know HTML to use Markdown?

No. Markdown converts to HTML automatically when rendered, but you write it entirely in plain text using simple symbols. You don't need to write a single HTML tag.

Is Markdown the same on every platform?

There's a common core that works everywhere, but platforms add their own extensions. GitHub Flavored Markdown (GFM) adds task lists and strikethrough. Obsidian adds wiki-style internal links. The 10 elements in this guide work on virtually every platform.

How do I preview my Markdown before publishing?

Paste your text into a browser-based Markdown preview tool like this one. You'll see the rendered output in real time on the right side as you type on the left.

What's the file extension for Markdown files?

Markdown files use the .md extension (and sometimes .markdown). Most text editors and IDEs support syntax highlighting for .md files.

Can I mix Markdown and HTML?

On most platforms, yes — HTML tags inside a Markdown document are passed through directly. However, it's usually cleaner to stick to Markdown and only use HTML for elements Markdown can't handle (like colored text or complex layouts).