Markdown Guide 2025: Complete Syntax Reference & Cheat Sheet

Markdown is a lightweight markup language that makes writing formatted text simple and intuitive. Whether you're creating README files, writing documentation, composing blog posts, or taking notes, Markdown is the go-to format for developers and writers. This complete guide covers all Markdown syntax with practical examples.

What is Markdown?

Markdown is a plain text formatting syntax created by John Gruber in 2004. It's designed to be easy to read and write, converting plain text into HTML with simple, memorable symbols.

Why Use Markdown?

Simple and readable: Plain text format that's easy to understand
Platform-independent: Works everywhere, from GitHub to note-taking apps
Fast to write: No need for complex formatting tools
Version control friendly: Perfect for Git and collaboration
Widely supported: GitHub, Reddit, Stack Overflow, Discord, and more
Converts to HTML: Easily transformed into web content

Basic Markdown Syntax

Headings

Use # symbols for headings (1-6 levels):

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

Alternative syntax for H1 and H2:

Heading 1
=========

Heading 2
---------

Emphasis (Bold and Italic)

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

Result:

italic text
bold text
bold and italic
~~strikethrough text~~

Paragraphs and Line Breaks

This is a paragraph.

This is another paragraph (separated by a blank line).

This is a line with two spaces at the end  
This creates a line break without a new paragraph.

Lists

Unordered lists:

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

* You can also use asterisks
+ Or plus signs

Ordered lists:

1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

1. Numbers auto-increment
1. So you can use 1. for all items
1. And they'll number correctly

Task lists (GitHub-flavored):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Links

[Link text](https://www.example.com)
[Link with title](https://www.example.com "Hover title")


[Link text][reference]
[reference]: https://www.example.com "Optional title"

Images

![Alt text](image.jpg)
![Alt text](image.jpg "Image title")


![Alt text][image-ref]
[image-ref]: image.jpg "Optional title"


[![Alt text](image.jpg)](https://www.example.com)

Code

Inline code:

Use `backticks` for inline code.

Code blocks:

```
Code block without syntax highlighting
Multiple lines of code
```

```javascript
// Code block with syntax highlighting
function hello() {
    console.log("Hello, World!");
}
```

```python
# Python code
def hello():
    print("Hello, World!")
```

Indented code blocks (alternative):

    Indent with 4 spaces or 1 tab
    for a code block
    No syntax highlighting

Blockquotes

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

> Blockquotes can be nested
>> By using multiple > symbols
>>> Like this

> Blockquotes can contain **formatting**
> - And lists
> - And other elements

Horizontal Rules

---
Three or more hyphens

***
Three or more asterisks

___
Three or more underscores

Advanced Markdown Syntax

Tables

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


| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| Text         | Text           | Text          |

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

You can also use named footnotes.[^note]

[^note]: Named footnotes are easier to manage.

Definition Lists

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Abbreviations

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Escaping Characters

Use backslash \ to escape Markdown characters:

\* Not italic \*
\# Not a heading
\[Not a link\](url)
\`Not code\`

Characters you can escape:
\ ` * _ { } [ ] ( ) # + - . ! |

HTML in Markdown

You can use raw HTML in Markdown:


    This is red text using HTML.



Click to expand
Hidden content here.


Ctrl + C to copy

GitHub-Flavored Markdown (GFM)

GitHub extends standard Markdown with additional features:

Syntax Highlighting

```diff
- Removed line
+ Added line
! Changed line
# Comment line
```

Emoji

:smile: :heart: :thumbsup: :rocket:
:+1: :-1: :tada: :fire:

Mentions and References

@username mentions a user
#123 references issue/PR number
SHA: a5c3785ed8d6a35868bc169f07e40e889087fd2e
username/repository#123 cross-repo reference

Alerts (GitHub)

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Markdown Best Practices

1. Consistent Formatting

Choose one style for emphasis (* or _) and stick with it
Use consistent heading hierarchy (don't skip levels)
Maintain consistent list markers (-, *, or +)

2. Readability

Add blank lines between different elements
Keep lines under 80-100 characters when possible
Use descriptive link text (not "click here")
Add alt text to all images

3. Code Blocks

Always specify language for syntax highlighting
Keep code examples concise and focused
Include comments in code when helpful

4. Links

Use reference-style links for repeated URLs
Add titles to links for better accessibility
Check that all links work before publishing

5. Lists

Use ordered lists for sequential steps
Use unordered lists for non-sequential items
Indent nested lists with 2-4 spaces

Common Markdown Use Cases

1. README Files

# Project Name

Brief description of your project.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install project-name
```

## Usage

```javascript
const project = require('project-name');
project.doSomething();
```

## Contributing

Pull requests are welcome!

## License

MIT

2. Documentation

# API Documentation

## Authentication

All API requests require authentication.

### Headers

| Header | Value | Required |
|--------|-------|----------|
| Authorization | Bearer {token} | Yes |
| Content-Type | application/json | Yes |

### Example Request

```bash
curl -X GET https://api.example.com/users \
  -H "Authorization: Bearer YOUR_TOKEN"
```

3. Blog Posts

# How to Write Better Markdown

Published: 2024-01-15

## Introduction

Markdown is a powerful tool...

## Key Points

1. Keep it simple
2. Use headings effectively
3. Format code properly

## Conclusion

By following these tips...

---

*Tags: markdown, writing, documentation*

4. Meeting Notes

# Team Meeting - 2024-01-15

**Attendees:** @john, @sarah, @mike

## Agenda

1. Project updates
2. Q1 planning
3. Action items

## Discussion

### Project Updates

- Feature X is 80% complete
- Bug fixes deployed last week

## Action Items

- [ ] @john: Review PR #123
- [ ] @sarah: Update documentation
- [x] @mike: Deploy to staging

## Next Meeting

**Date:** 2024-01-22  
**Time:** 2:00 PM

Markdown Tools and Editors

Desktop Editors

VS Code: With Markdown extensions
Typora: WYSIWYG Markdown editor
Obsidian: Note-taking with Markdown
Mark Text: Simple and elegant
iA Writer: Distraction-free writing

Online Editors

StackEdit: In-browser Markdown editor
Dillinger: Online Markdown editor
HackMD: Collaborative Markdown
GitHub: Built-in editor and preview

Converters

Pandoc: Universal document converter
Marked: Markdown to HTML converter
Markdown-it: JavaScript parser
Showdown: Markdown to HTML in JS

Markdown Flavors

Common Markdown Flavors

CommonMark: Standardized specification
GitHub Flavored Markdown (GFM): GitHub's version with tables, task lists, strikethrough
MultiMarkdown: Adds footnotes, tables, metadata
Markdown Extra: PHP Markdown with extra features
R Markdown: For data science and reports
Pandoc Markdown: Extended syntax for academic writing

Common Mistakes to Avoid

Missing blank lines: Always add blank lines between different elements
Incorrect list indentation: Use consistent spacing (2 or 4 spaces)
Forgetting alt text: Always add descriptions to images
Inconsistent heading levels: Don't skip from H1 to H3
Not escaping special characters: Use \ to escape when needed
Mixing HTML and Markdown: Can cause rendering issues
Long lines: Break lines for better readability
No syntax highlighting: Always specify language in code blocks

Markdown Cheat Sheet

# Heading 1                    *italic*
## Heading 2                   **bold**
### Heading 3                  ***bold italic***
#### Heading 4                 ~~strikethrough~~
##### Heading 5                `code`
###### Heading 6               

[link](url)                    - List item
![image](url)                  1. Ordered item
                               - [ ] Task list

> Blockquote                   | Table | Header |
                               |-------|--------|
---                            | Cell  | Cell   |

```language                    :emoji:
code block                     @mention
```                            #issue

📝 Try Our Markdown Converter: Use our free Markdown to HTML Converter to preview and convert your Markdown instantly!

Conclusion

Markdown is an essential skill for developers, writers, and anyone who works with text. Its simple syntax makes formatting fast and intuitive, while its plain text format ensures compatibility and longevity. Whether you're writing README files, documentation, blog posts, or notes, Markdown helps you focus on content rather than formatting.

Start with the basics—headings, lists, links, and code blocks—and gradually incorporate advanced features as needed. With practice, Markdown becomes second nature, making you a more efficient and effective writer.

Related Tools & Resources

Enhance your Markdown workflow:

Markdown to HTML Converter - Convert and preview Markdown
Word Counter - Track your writing progress
Case Converter - Format text properly
Text Formatter - Clean up your text

← Back to Blog