Markdown Syntax: The Complete Guide with Examples

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you write formatted text using plain text syntax that's easy to read and write. Markdown is used everywhere: GitHub READMEs, documentation, blogs, note-taking apps, and even chat platforms like Slack and Discord.

The beauty of Markdown is that the source text is readable even without rendering. Compare:

HTML:    <h1>Hello</h1><p>This is <strong>bold</strong> and <em>italic</em></p>
Markdown: # Hello\n\nThis is **bold** and *italic*

Headings

Use # symbols for headings. More # = smaller heading:

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

Best practice: Always put a space after the #. Always leave a blank line before and after headings.

Text Formatting

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`

Renders as:

• Bold text
• Italic text
• Bold and italic
• Strikethrough
• Inline code

Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")
<https://example.com>  (auto-linked URL)
[Reference link][1]

[1]: https://example.com

Images

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

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

Accessibility tip: Always include meaningful alt text for images.

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item
  - Another nested item
- Item 3

* Also works with asterisks
+ And plus signs

Ordered Lists

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

<!-- Numbers don't have to be sequential -->
1. First
1. Second (still renders as 2)
1. Third (still renders as 3)

Task Lists (GitHub Flavored)

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

Blockquotes

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

> Nested blockquotes
>> Are also possible
>>> And can go deeper

Code

Inline Code

Use `console.log()` to debug.

Code Blocks

Use triple backticks with an optional language identifier:

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

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

```sql
SELECT * FROM users WHERE active = true;
```

Supported languages include: javascript, typescript, python, java, c, cpp, csharp, go, rust, ruby, php, sql, html, css, bash, json, yaml, markdown, and many more.

Indented Code Blocks

Indent with 4 spaces or 1 tab (less common, prefer fenced blocks):

    function hello() {
      console.log("Hello!");
    }

Tables

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

Alignment

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

The colons in the separator row control alignment:

• :--- = left (default)
• :---: = center
• ---: = right

Horizontal Rules

Any of these create a horizontal line:

---
***
___

Line Breaks

Markdown joins consecutive lines into a single paragraph. To create a line break:

Line 1  
Line 2

<!-- Two spaces at the end of Line 1 creates a <br> -->
<!-- Or use a blank line for a new paragraph -->

Escaping Characters

Use backslash to escape Markdown characters:

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

Characters that can be escaped: \ ` * _ { } [ ] ( ) # + - . ! |

GitHub Flavored Markdown (GFM)

GitHub extends standard Markdown with additional features:

Autolinked URLs

https://example.com  (automatically becomes a link)

Username Mentions

@username will notify that user

Issue/PR References

#123 links to issue/PR 123
user/repo#123 links to another repo's issue

Emoji

:smile: :rocket: :thumbsup: :heart:

Footnotes

Here is a statement[^1].

[^1]: This is the footnote content.

Alerts (GitHub-specific)

> [!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.

Collapsed Sections

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

Hidden content goes here.

- Can include any Markdown
- Lists, code blocks, etc.

</details>

Markdown Best Practices

1. Use ATX-style headings (#) instead of Setext-style (underlines)
2. Leave blank lines before and after headings, lists, and code blocks
3. Use fenced code blocks with language identifiers for syntax highlighting
4. Keep lines under 80-120 characters for readability in source
5. Use reference-style links for long URLs to keep text readable
6. Be consistent with list markers (pick - or * and stick with it)
7. Use meaningful alt text for images

Markdown Editors

Popular editors with Markdown support:

• VS Code — Built-in preview, extensions for enhanced editing
• Obsidian — Knowledge management with Markdown
• Typora — WYSIWYG Markdown editor
• StackEdit — Browser-based editor
• HackMD/CodiMD — Collaborative Markdown

Preview your Markdown with our Markdown to HTML converter tool.