Markdown Cheat Sheet with Examples

Markdown is the lingua franca of technical writing. From GitHub README files and documentation sites to Notion pages and Stack Overflow answers, Markdown lets you add structure and meaning to plain text without reaching for a word processor. This cheat sheet covers every major element — with copy-paste examples — so you can write clean, portable Markdown every time.

If you want to experiment as you read, open the Markdown Editor and try each snippet live.

---

What Is Markdown?

Markdown was created by John Gruber in 2004 as a lightweight text-to-HTML conversion tool. The design goal was that raw Markdown source should be readable as-is — it should look like naturally formatted plain text, not like markup code. Over the years, multiple dialects emerged. The two most important today are:

• CommonMark — a strict, unambiguous specification (commonmark.org) that most modern parsers implement. It resolves many of the edge cases that Gruber's original spec left undefined.
• GitHub Flavored Markdown (GFM) — a superset of CommonMark used by GitHub. It adds task lists, tables, strikethrough, and auto-linking of URLs and issue references.

Unless noted, everything in this guide works in both dialects.

---

Headings

Use the # character followed by a space. The number of # symbols maps to the HTML heading level.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

ATX style (shown above) is the modern standard. An older Setext style also exists for H1 and H2:

Heading 1
=========

Heading 2
---------

Prefer ATX — it works for all six levels and is unambiguous.

CommonMark rule: you must have a space after the #. #heading without a space is rendered as a paragraph, not a heading.

---

Emphasis

Bold

**bold text**
__also bold__

Use **double asterisks** — it is unambiguous. Underscores work but can clash with variable names like my_variable_name.

Italic

*italic text*
_also italic_

Bold and Italic Together

***bold and italic***
**_bold and italic_**

Strikethrough (GFM only)

~~strikethrough text~~

This is a GitHub Flavored Markdown extension and is not part of CommonMark. It renders in GitHub, GitLab, and most modern editors.

Inline Code

Use the `console.log()` function for debugging.

Backticks preserve whitespace and disable all other Markdown formatting inside them. To include a literal backtick inside inline code, use double backticks as the delimiter:

`` Use `backticks` like this ``

---

Lists

Unordered Lists

Use -, *, or + followed by a space. Pick one character and stick with it for consistency.

- Item one
- Item two
  - Nested item (two spaces)
  - Another nested item
- Item three

Result:

• Item one
• Item two
  • Nested item (two spaces)
  • Another nested item
• Item three

Nesting rule: indent nested items by exactly two spaces (or four spaces in some parsers). Using a tab character can work but is not portable across all Markdown renderers.

Ordered Lists

1. First item
2. Second item
3. Third item
   1. Nested ordered item
   2. Another nested item

A useful trick: you can use 1. for every item and most parsers will auto-number them. This makes reordering easier without renumbering.

1. First
1. Second
1. Third

Task Lists (GFM only)

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Share on social media

Renders as interactive checkboxes on GitHub. The [x] marks a completed task; [ ] marks an incomplete one. This is one of the most useful GFM extensions for project planning in README files.

---

Links and Images

Inline Links

[link text](https://example.com)
[link with title](https://example.com "Hover tooltip")

Reference Links

Useful when the same URL appears multiple times, or when you want to keep URLs out of the prose:

Visit [Google][search-engine] or [Bing][search-engine-2].

[search-engine]: https://google.com
[search-engine-2]: https://bing.com

The reference definitions can be placed anywhere in the document — conventionally at the bottom, like footnotes.

Autolinks

In GFM, bare URLs are automatically linked:

https://example.com

In CommonMark, you must use angle brackets: <https://example.com>

Images

Images follow the same syntax as links but with a leading !:

![alt text](image.png)
![alt text](image.png "Optional title")

The alt text is important for accessibility — screen readers read it aloud. Never leave it empty unless the image is purely decorative.

Reference-style image:

![Logo][logo-ref]

[logo-ref]: /assets/logo.png "Company Logo"

Linking an Image

[![alt text](thumbnail.png)](https://example.com)

This wraps an image in a link — useful for badges in README files.

---

Code Blocks

Fenced Code Blocks

Fenced code blocks use triple backticks (or triple tildes). Always add a language identifier — it enables syntax highlighting in GitHub, VS Code, and most documentation platforms.

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

console.log(greet('World'));
```

Common language identifiers:

Language	Identifier
JavaScript	javascript or js
TypeScript	typescript or ts
Python	python or py
Shell / Bash	bash or sh
SQL	sql
HTML	html
CSS	css
JSON	json
YAML	yaml or yml
Markdown	markdown or md
Diff	diff
Plain text	text or plaintext

Diff Highlighting

- const oldFunction = () => false;
+ const newFunction = () => true;

Lines prefixed with - render in red; lines prefixed with + render in green. Invaluable for showing what changed.

Indented Code Blocks

The older syntax uses four spaces of indentation. Avoid it — fenced blocks are clearer and support language hints.

    // This is an indented code block (4 spaces)
    console.log('old style');

---

Blockquotes

Use > to create blockquotes. Chain multiple > for nested quotes.

> "Programs must be written for people to read, and only incidentally
> for machines to execute."
>
> — Harold Abelson

"Programs must be written for people to read, and only incidentally for machines to execute."

— Harold Abelson

Nested blockquotes:

> Outer quote
>
> > Inner quote (nested)
> >
> > > Deeply nested

Blockquotes can contain other Markdown elements — lists, code, headings — making them useful for callout boxes in documentation.

---

Tables

Tables are a GFM extension (not standard CommonMark). They use pipes | and hyphens - for the header separator row.

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Column Alignment

Colons in the separator row control alignment:

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| text         |     text       |          text |
| 1234         |      5678      |          9012 |

Left Aligned	Center Aligned	Right Aligned
text	text	text
1234	5678	9012

Table tips:

• Leading and trailing pipes are optional but recommended for readability.
• You do not need to align the pipes — Markdown parsers ignore extra whitespace inside cells.
• You cannot create tables with merged cells in standard Markdown. Use HTML <table> tags if you need rowspan or colspan.
• Inline formatting (bold, italic, code) works inside table cells.

---

Horizontal Rules

Three or more hyphens, asterisks, or underscores on a line by themselves create a <hr> element:

---
***
___

Caution: a line of hyphens directly below a paragraph (with no blank line separating them) creates a Setext H2 heading, not a horizontal rule. Always put a blank line before ---.

---

CommonMark vs GitHub Flavored Markdown: Key Differences

Feature	CommonMark	GitHub Flavored Markdown
Tables	Not supported	Supported
Task lists	Not supported	Supported
Strikethrough (~~)	Not supported	Supported
Bare URL autolinks	Not supported	Supported
Emoji shortcodes (:smile:)	Not supported	Supported
Footnotes	Not supported	Supported (beta)
HTML blocks	Allowed (restricted)	Allowed (restricted)
Tight list paragraph handling	Strict spec	Same

If your Markdown will be read on GitHub, GitLab, or a platform that explicitly states GFM support, you can safely use all GFM extensions. For maximum portability (e.g., a static site generator, a wiki engine, or a tool you do not control), stick to CommonMark.

---

How to Structure a Great README

A README is the front door of your project. Good README structure follows a predictable order so readers can quickly find what they need. Here is the recommended section order:

1. Project Title and Badges

Start with the project name as an H1, then a row of status badges (build, coverage, license, version). Badges give immediate health signals.

# MyProject

[![Build](https://img.shields.io/github/workflow/status/user/repo/CI)](link)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

2. One-Line Description

One sentence explaining what the project does. Imagine someone has five seconds. What do they need to know?

3. Table of Contents (optional for short READMEs)

For long READMEs, a TOC with anchor links helps readers jump to sections:

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)

4. Installation

Exact, copy-paste steps. Do not assume the reader's environment. Name every prerequisite.

## Installation

**Prerequisites:** Node.js 18+ and pnpm 8+

```sh
git clone https://github.com/user/myproject.git
cd myproject
pnpm install

### 5. Quick Start / Usage

Show the most common use case first, with a working code example. This is often the most-read section.

### 6. Configuration

Document all environment variables, config files, and flags. A table works well here.

### 7. API Reference (if applicable)

For libraries, document the public API. Link to generated docs if they exist.

### 8. Contributing

How to open issues, submit PRs, and run tests. Link to a `CONTRIBUTING.md` for detailed guidelines.

### 9. License

State the license and link to the `LICENSE` file.

```markdown
## License

MIT — see [LICENSE](LICENSE) for details.

---

Common Markdown Mistakes

These are the errors that trip up even experienced writers.

1. Missing Blank Lines

Many Markdown elements require a blank line before them to be recognized.

This is a paragraph.
## This heading will NOT render correctly

This is a paragraph.

## This heading WILL render correctly

Blank lines are also required before and after:

• Block-level code fences
• Blockquotes (in some parsers)
• Ordered and unordered lists (when they follow a paragraph)

2. Unclosed Fences

An unclosed triple-backtick fence will swallow the rest of the document into a code block. Always close your fences.

```python
def broken():
    pass
# Missing closing fence — everything below becomes code!

3. Tab vs Space Indentation for Nested Lists

Different parsers handle tabs differently inside lists. Use spaces — specifically two or four — for nested list items. Do not mix tabs and spaces.

- Parent
  - Child (2 spaces — works everywhere)
	- Child (tab — unreliable)

4. Emphasis Across Words with Underscores

In CommonMark, underscores cannot be used for emphasis inside a word:

my_variable_name  ← the underscores do NOT become italic
*my_variable_name*  ← use asterisks if you need emphasis here

5. Special Characters in Link Destinations

Parentheses in URLs must be escaped or encoded:

<!-- Broken -->
[Link](https://example.com/page(1))

<!-- Fixed: escape with backslash -->
[Link](https://example.com/page\(1\))

<!-- Fixed: percent-encode -->
[Link](https://example.com/page%281%29)

6. HTML Entities vs Literal Characters

Markdown does not escape HTML entities automatically in all contexts. Inside HTML blocks, use & for &, < for <, etc. Inside regular Markdown paragraphs, you can write & and < directly and most parsers will handle them.

7. Forgetting the Space After `#` in Headings

#Title is a paragraph starting with #Title. # Title is a heading. This is one of the most common typos.

8. Trailing Spaces for Line Breaks

A single line break in Markdown source renders as a space, not a new line. To force a line break, end the line with two trailing spaces or use <br>:

Line one  
Line two (two trailing spaces above force a line break)

This is subtle and easy to miss because trailing spaces are invisible in most editors. Consider using <br> instead for clarity.

---

Where Markdown Is Used

Markdown has become the default format in many contexts:

Platform	Where Markdown Appears
GitHub / GitLab	README files, issues, pull requests, wikis, comments
Stack Overflow	Questions, answers, comments
Reddit	Posts and comments (partial Markdown)
Notion	Pages and databases
Obsidian	All notes (with extensions)
Confluence	Pages (via the Markdown macro or import)
Discord	Messages (partial: bold, italic, code)
Slack	Messages (simplified Markdown)
Jekyll / Hugo / Eleventy	Blog posts and page content
Docusaurus / MkDocs	Documentation sites
Jupyter Notebooks	Prose cells
VS Code	Markdown preview, README editing

Markdown files conventionally use the .md extension (sometimes .markdown). YAML front matter — a block of key-value pairs at the very top, delimited by --- — is widely used by static site generators to attach metadata:

---
title: My Blog Post
date: 2026-06-04
tags: [markdown, writing]
---

# My Blog Post

Content starts here.

---

Escaping Markdown Characters

To display a literal Markdown character that would otherwise be interpreted as formatting, prefix it with a backslash:

\*not italic\*
\# not a heading
\[not a link\](not-a-url)

Characters you may need to escape: \, `, *, _, {, }, [, ], (, ), #, +, -, ., !

---

HTML in Markdown

Most Markdown parsers allow raw HTML. Use it sparingly — only when Markdown cannot express what you need:

<details>
<summary>Click to expand</summary>

Hidden content here. Note the blank lines around the Markdown inside HTML blocks.

</details>

This renders as a collapsible section on GitHub — handy for long installation instructions or changelogs.

<kbd>Ctrl</kbd> + <kbd>C</kbd>

The <kbd> tag renders as keyboard key styling, which Markdown has no native equivalent for.

---

Quick Reference Summary

Element	Syntax
H1 Heading	# Heading
H2 Heading	## Heading
Bold	**text**
Italic	*text*
Bold + Italic	***text***
Strikethrough	~~text~~
Inline code	`code`
Fenced code block	```lang ... ```
Unordered list	- item
Ordered list	1. item
Task list	- [x] done / - [ ] todo
Link	[text](url)
Image	
Blockquote	> text
Table	| col | col |
Horizontal rule	---
Line break	two trailing spaces
Escape character	\*

---

Tooling and Extensions

Editor Support

• VS Code — built-in Markdown preview, plus extensions like Markdown All in One for TOC generation and shortcuts.
• Typora — WYSIWYG Markdown editor that shows formatted output in place.
• Obsidian — note-taking app built entirely around Markdown files.
• Zed / Neovim / Emacs — all have solid Markdown support via plugins.

Linting

markdownlint (available as a VS Code extension, CLI, and GitHub Action) enforces consistent style — heading levels, blank lines, line length, and more. Adding it to a CI pipeline catches formatting issues before they merge.

Converters

• Pandoc — converts Markdown to PDF, DOCX, HTML, LaTeX, EPUB, and dozens of other formats. The Swiss Army knife of document conversion.
• markdown-it — a fast, spec-compliant JavaScript parser used by many web platforms.
• marked — another popular JavaScript Markdown parser.

---

Practical Example: A Complete README Skeleton

# ProjectName

[![CI](https://img.shields.io/badge/build-passing-brightgreen)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A one-sentence description of what the project does.

## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)

## Installation

**Prerequisites:** Node.js 20+

```sh
npm install projectname

Usage

import { doThing } from 'projectname';

const result = doThing('input');
console.log(result);

Configuration

Variable	Default	Description
PORT	3000	HTTP port to listen on
LOG_LEVEL	info	Logging verbosity

Contributing

PRs welcome. Please open an issue first to discuss the change. Run npm test before submitting.

License

MIT — see LICENSE for details.

---

## Conclusion

Markdown strikes a rare balance: it is simple enough to write in a plain text editor with no tooling, yet powerful enough to produce beautifully formatted documentation, READMEs, and blog posts. The learning curve is shallow — most people are productive within an hour.

The keys to writing great Markdown are consistency (pick one style for bullets, headings, emphasis and stick with it), adding language hints to every code fence, and respecting the blank-line rules that many parsers require.

For a hands-on environment to practice everything from this guide, try the [Markdown Editor](/tools/markdown-editor) — you can paste any snippet from this post and see the rendered result immediately.