What Is Markdown? A Beginner's Guide to Writing in Markdown

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its goal was to allow people to write plain text that is easy to read as-is, but that can be converted to HTML automatically. The name is a play on "markup" — Markdown is meant to be the minimal, human-friendly alternative.

You have almost certainly used Markdown without realizing it. GitHub READMEs, Reddit posts, Slack messages, Notion pages, Discord formatting, and most documentation platforms all use Markdown or a variation of it.

Why Markdown?

HTML is powerful but verbose. To make a paragraph bold in HTML, you write <strong>text</strong>. In Markdown, you write **text**. Markdown lets writers focus on content rather than tags. The formatted output is handled by the renderer.

Markdown Syntax Cheat Sheet

Headings

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

Emphasis

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~

Lists

Unordered list:
- Item one
- Item two
  - Nested item

Ordered list:
1. First
2. Second
3. Third

Links and Images

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

Code

Inline: `const x = 5;`

Code block:
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Blockquotes

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

Horizontal Rule

---

Tables (GitHub Flavored Markdown)

| Name  | Age | City    |
|-------|-----|---------|
| Alice | 30  | New York|
| Bob   | 25  | London  |

Where Markdown Is Used

• GitHub — README files, pull request descriptions, issue templates, and wikis all use Markdown.
• Documentation tools — MkDocs, Docusaurus, GitBook, and most static site generators use Markdown as the primary authoring format.
• Note-taking apps — Obsidian, Notion, Bear, Typora, and Logseq all support Markdown natively.
• Communication tools — Slack, Discord, Microsoft Teams, and Mattermost support Markdown subsets for message formatting.
• Blogging — Jekyll, Hugo, Ghost, and Astro (the framework this site is built on) use Markdown for blog content.
• Academic writing — Pandoc can convert Markdown to Word, PDF, LaTeX, and more, making it popular for research papers.

Markdown Flavors

The original Markdown spec by John Gruber left many edge cases unspecified, leading to different implementations. The most important variants:

• CommonMark — A strict, well-defined specification that resolves ambiguities. This is the basis for most modern implementations.
• GitHub Flavored Markdown (GFM) — Adds tables, task lists, strikethrough, and autolinks. The de facto standard for developer documentation.
• MDX — Markdown + JSX components. Popular in React-based documentation and blog platforms.

Markdown vs. Rich Text Editors

Rich text editors (like Microsoft Word or Google Docs) store formatting as binary or complex XML. Markdown stores everything as plain text, making it:

• Version-control friendly (diffs are readable)
• Portable across any editor or OS
• Future-proof — plain text files will be readable indefinitely
• Fast to write once you know the syntax

Conclusion

Markdown is one of the most practical skills a writer, developer, or content creator can have. It is simple enough to learn in an afternoon and powerful enough to write entire books. Convert your existing Markdown or HTML using our Markdown to HTML and HTML to Markdown tools.