How to Write Markdown: A Practical Guide (With Cheat Sheet)

What Markdown is

Markdown is a lightweight markup language — plain text with formatting symbols that converts to HTML. A # becomes an h1, ** around text makes it bold, - starts a list item. The philosophy: the text should look good even when not rendered, and the formatting syntax should be intuitive.

The complete cheat sheet

Headings

# H1 — page title
## H2 — main section
### H3 — subsection
#### H4 — rarely needed

Text formatting

**bold text**
*italic text*
~~strikethrough~~
`inline code`
> blockquote

Links and images

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

Lists

- Unordered item
- Another item
  - Nested item (2 spaces indent)

1. Ordered item
2. Another item
   1. Nested ordered item

Code blocks

```javascript
const name = "World";
console.log(`Hello, ${name}`);
```

The language name after the opening backticks enables syntax highlighting on most platforms (GitHub, GitLab, many blog engines).

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |
| Cell     | Cell     | Cell     |

Horizontal rule

---
(three or more dashes on their own line)

Task list (GitHub Flavored Markdown)

- [x] Completed task
- [ ] Incomplete task

The formatting choices that break rendering

Blank lines between elements

Markdown requires a blank line between most elements. A heading immediately followed by a paragraph may not render correctly on some parsers. Always add a blank line between headings, paragraphs, lists, and code blocks.

Indentation for nested lists

Nested list items must be indented by exactly 2 or 4 spaces (parsers vary). A single space does not create nesting on most platforms.

Line breaks inside paragraphs

A single newline within a paragraph is ignored — the text continues on the same line. To force a line break within a paragraph, end the line with two spaces before pressing Enter. This is one of Markdown's least intuitive behaviors.

Special characters

To display literal Markdown syntax characters (*, #, [], etc.), escape them with a backslash: \* renders as *, \# renders as #.

GitHub Flavored Markdown (GFM) vs CommonMark

There is no single Markdown standard. CommonMark is the most widely adopted specification. GitHub uses GitHub Flavored Markdown (GFM) which adds tables, task lists, strikethrough, and autolinks. Most platforms (GitLab, Notion, Obsidian) support similar supersets of CommonMark.

Features that vary by platform:

• Tables — GFM only, not in basic CommonMark
• Task lists (checkboxes) — GitHub and some others
• Footnotes — Pandoc and some platforms
• Math expressions — platforms with KaTeX/MathJax support

Summary — the 10 things you use 90% of the time

# Heading 1
## Heading 2
**bold** *italic*
[link](url) ![image](url)
- list item
1. ordered item
`code`
```language
code block
```
> blockquote
---

That covers nearly all Markdown you will need for README files, documentation, and blog posts.