Markdown Syntax Cheat Sheet: The Complete Guide for Developers and Bloggers

Markdown has become the universal language of technical writing. Created by John Gruber in 2004, it lets you write formatted text using plain text syntax — no complex editors or HTML knowledge needed. Whether you're writing GitHub READMEs, documentation, blog posts, or notes, Markdown skills are essential for any developer or content creator. This comprehensive guide covers everything from basic syntax to advanced formatting techniques.

Why Learn Markdown?

Markdown is everywhere in the modern developer ecosystem. GitHub, GitLab, Bitbucket, Stack Overflow, Reddit, Discord, Notion, Obsidian, Jira, Confluence — they all support Markdown to some degree. Learning Markdown once gives you formatting power across dozens of platforms. It's faster than using a WYSIWYG editor, version-control friendly, and produces clean, portable text that can be converted to HTML, PDF, or any other format.

Beyond developer tools, Markdown is increasingly used in academic writing (with tools like Pandoc), email composition (many email clients support Markdown), and even book publishing. The investment in learning Markdown pays dividends across your entire digital life.

Basic Syntax: Headings, Bold, and Italic

Headings are created with hash (#) symbols. One hash for H1, two for H2, and so on up to H6. Always put a space after the hash symbols. For emphasis, wrap text in single asterisks (*italic*) or underscores (_italic_) for italics, and double asterisks (**bold**) or double underscores (__bold__) for bold. You can combine them: ***bold italic*** or use ___bold italic___.

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

*italic text* or _italic text_
**bold text** or __bold text__
***bold italic*** or ___bold italic___
~~strikethrough~~

Paragraphs are separated by blank lines. A single line break within text won't create a new paragraph — you need a full empty line between blocks. For a line break within a paragraph (without starting a new paragraph), add two spaces at the end of the line or use a backslash (\). Horizontal rules are created with three or more hyphens (---), asterisks (***), or underscores (___).

Lists: Ordered and Unordered

Unordered lists use hyphens (-), asterisks (*), or plus signs (+) followed by a space. Ordered lists use numbers followed by periods. You can nest lists by indenting with 2 or 4 spaces. Markdown is flexible with ordered list numbering — you can use 1 for every item and it will still render correctly as a sequential list.

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

1. First step
2. Second step
   1. Sub-step A
   2. Sub-step B
3. Third step

- [x] Completed task
- [ ] Incomplete task

Task lists (checkboxes) are a GitHub-flavored Markdown extension. Use - [ ] for unchecked and - [x] for checked items. These are particularly useful in issue descriptions and pull request templates for tracking action items.

Links and Images

Links use the format [display text](URL). You can add a hover title with [display text](URL "title"). Reference-style links let you define URLs elsewhere in the document for cleaner text: [display text][ref] with [ref]: URL defined at the bottom. Images use the same syntax but with an exclamation mark prefix: .

[Visit Google](https://google.com)
[Visit Google](https://google.com "Google Homepage")

[Reference link][1]
[1]: https://example.com

![Alt text for image](https://example.com/image.png)
![Alt text](image.png "Image title")

<!-- Linked image -->
[![Alt text](image.png)](https://example.com)

Code: Inline and Blocks

Inline code is wrapped in single backticks: `code here`. For code blocks, use triple backticks (```) on separate lines before and after the code. Add a language identifier after the opening backticks for syntax highlighting. Most Markdown processors support highlighting for JavaScript, Python, TypeScript, HTML, CSS, JSON, Bash, SQL, and dozens more languages.

Inline: Use `console.log()` to debug.

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

```python
def greet(name):
    return f"Hello, {name}!"
```

    // Indented code block (4 spaces)
    const x = 42;

Tables

Tables use pipes (|) and hyphens (-) to create columns and rows. The second row defines alignment: left-aligned (default), center-aligned (:---:), or right-aligned (---:). Tables don't need to be perfectly aligned in the source — Markdown processors handle the formatting.

| Feature   | Markdown | HTML    |
|-----------|:--------:|--------:|
| Headings  | Easy     | Verbose |
| Lists     | Simple   | Complex |
| Tables    | OK       | Tedious |
| Learning  | Quick    | Slow    |

Advanced Features

Beyond basic syntax, many Markdown flavors support extended features that add even more power to your documents:

• Footnotes: Add [^1] in text and [^1]: footnote content at the bottom. Supported in GitHub, Obsidian, and many static site generators.
• Definition lists: Term on one line, followed by : definition on the next (indented). Supported in PHP Markdown Extra and some processors.
• Abbreviations: Define *[HTML]: Hyper Text Markup Language and all instances of HTML in the document show a tooltip.
• Emoji: Use :emoji_name: syntax (e.g., :rocket:, :tada:). Widely supported on GitHub, Slack, Discord.
• Math equations: Use $inline math$ and $$display math$$ with LaTeX syntax. Supported on GitHub, Obsidian, Jupyter notebooks.
• Mermaid diagrams: Create flowcharts, sequence diagrams, and more with ```mermaid code blocks. Supported on GitHub and many documentation tools.
• Admonitions/callouts: Use > [!NOTE], > [!WARNING], > [!TIP] in blockquotes. Supported on GitHub and Obsidian.

Blockquotes use the greater-than symbol (>) at the start of each line. They can be nested (>>), contain other Markdown elements, and are commonly used for quotes, notes, and callouts. Many platforms extend blockquotes with special syntax for colored callout boxes.