The Markdown Handbook for Writers and Developers

Markdown is the simplest formatting language ever invented. You can learn the full syntax in 10 minutes and you'll use it for the rest of your career. Notes, blog posts, GitHub READMEs, documentation, Discord messages — Markdown is everywhere.

The 10-minute syntax

Headings

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

Use one # for the main title and increment per level. Don't skip levels.

Emphasis

**bold text**
_italic text_
**_bold italic_**
~~strikethrough~~

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item

- [ ] Task list (GFM)
- [x] Completed task

Links and images

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

Code

Inline `code` with backticks.

```js
// Code block with syntax language
const greet = (name) => `Hello ${name}`
```

Quotes and rules

> Blockquote — useful for callouts and references.

---

Horizontal rule above.

Tables (GFM)

| Header | Header |
|--------|--------|
| Cell   | Cell   |
| Cell   | Cell   |

Alignment with colons in the separator row: :-- left, :-: center, --: right.

GitHub Flavored Markdown (GFM)

GFM is the dominant Markdown variant in 2026. Most platforms (GitHub, GitLab, Notion, Discord, Reddit, Medium, most blog engines) support some flavour of it. Extensions beyond basic Markdown:

• Tables (shown above).
• Strikethrough with ~~text~~.
• Task lists with - [ ] and - [x].
• Fenced code blocks with language hints for syntax highlighting.
• Auto-linking raw URLs.
• Footnotes with [^1] references.

When to use Markdown vs rich text

Use Markdown for:

• Anything destined for the web — blog posts, docs, READMEs.
• Notes you might want to migrate later (Markdown survives every tool change).
• Plain-text-friendly contexts (Slack, Discord, GitHub).
• Anything version-controlled.

Use rich text editors for:

• Documents shared with non-technical people (Google Docs, Word).
• Highly formatted documents (legal contracts, design briefs).
• Real-time collaboration with comments.

The Markdown editors worth using

• Obsidian — best for personal knowledge management, free for individuals.
• Typora — distraction-free Markdown editor with live preview. Paid one-time.
• VS Code with the Markdown All in One extension — best for devs who already use VS Code.
• iA Writer — minimalist, great typography, focus mode.
• Notion — Markdown-flavoured rich editor. Half-Markdown, half-rich-text.
• The Markdown Converter — paste anywhere, convert to HTML when needed.

Markdown for blog posts

Almost every modern blogging platform (Ghost, Medium, Hashnode, Dev.to, Bear, Mataroa) accepts Markdown. Workflow that works:

1. Draft in Markdown in your favorite editor (Obsidian, Typora, iA Writer).
2. Preview live to catch formatting issues.
3. Copy-paste to publishing platform OR import the .md file directly.
4. Adjust platform-specific details (images, links, SEO meta).

For converting Markdown to HTML for embedding in a custom site, the Markdown Converter handles GFM and shows live preview.

Markdown gotchas

• Bare URLs aren't always autolinked. Some parsers don't autolink. Wrap in <url> or use [text](url).
• Underscores inside words. this_is_a_variable can trigger italic. Escape with backslash: this\_is\_a\_variable, or use a code span.
• Nested lists need correct indent. 2 or 4 spaces — inconsistent indenting breaks the list.
• HTML inside Markdown works. Markdown supports inline HTML for things Markdown doesn't (table cell alignment, video embeds).
• Smart quotes change behavior. Some editors auto-convert "text" to curly quotes which then break code.

Common patterns

Front matter for static site generators

---
title: My Post
date: 2026-05-26
tags: [markdown, writing]
---

# Body content starts here

YAML frontmatter at the top of a Markdown file is how Jekyll, Hugo, Astro, and most static site generators handle metadata. The triple-dash separator is universal.

Embedded HTML for video

<video src="demo.mp4" controls></video>

Markdown has no native video syntax. Drop in HTML for it.

Comments

<!-- This is a comment, not rendered -->

Why Markdown survives

Markdown's longevity isn't an accident. The design has two genius decisions:

• Plain text is readable. Even without rendering, **bold** reads as emphasis. Other markup languages fail this test.
• Subset of writer conventions. People were typing *emphasis* in emails decades before Markdown formalised it.

Your Markdown notes from 2010 still render correctly today. Your Word .doc files from 2010 may have font issues. Your Notion notes from 2020 are locked in proprietary format until Notion's takeout feature continues to exist.

The handbook in one screen

# H1 Heading
## H2 ### H3 #### H4

**bold**  _italic_  ~~strike~~  `code`

- List
- Item
  - Nested
- [ ] Task
- [x] Done

1. Numbered
2. Item

[Link](url)  ![Image](url)

> Quote

```js
const x = 1
```

| Col | Col |
|-----|-----|
| Row | Row |

---