📄
← Back to Guides

Markdown Syntax Guide: Complete Reference with Examples

· Tags: markdown-syntax, markdown-guide, markdown-formatting, github-flavored-markdown, markdown-reference

Markdown Syntax Guide

Markdown is a lightweight markup language that converts plain text to formatted HTML. Created by John Gruber in 2004, it has become the standard writing format for documentation, README files, and technical content across the web.

Headings

Use # symbols. One # for the top level, up to six for the deepest:

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

Levels should increase by one — skipping from ## to #### can confuse screen readers.

Text Formatting

**Bold text** or __Bold text__
*Italic text* or _Italic text_
**_Bold and italic_**
~~Strikethrough text~~

Links

[Link text](https://example.com)
[Link with title](https://example.com "Title")
[Reference-style][ref-id]
[ref-id]: https://example.com
<contact@example.com>

Images

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

Alt text is critical for accessibility and SEO — it displays when images fail to load.

Lists

Unordered lists use -, *, or +. Ordered lists use numbers:

- Item one         1. First item
- Item two         2. Second item
  - Nested item       1. Nested item

Code

Inline code uses single backticks: `printf()`.

Code blocks use triple backticks with optional language identifier:

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


Supported languages: `javascript`, `python`, `html`, `css`, `json`, `bash`, `sql`, `yaml`.

## Blockquotes

```markdown
> This is a blockquote.
> > Nested blockquotes are supported.

Common for callouts, notes, and citing external sources.

Horizontal Rules

Three or more dashes, asterisks, or underscores on a line:

---
***
___

Tables

Pipes and dashes define columns. Colons control alignment:

| Left | Center | Right |
| :--- | :----: | ----: |
| A1   | B1     | C1    |

GitHub Flavored Markdown Extensions

GitHub Flavored Markdown (GFM) adds useful features:

- [x] Completed task     # Task lists
- [ ] Incomplete task

:smile: :rocket: :warning:    # Emoji shortcodes

~~Strikethrough text~~        # Strikethrough

GFM also auto-links URLs — www.example.com becomes clickable without wrapping in < >.

Escaping Special Characters

Prefix with \ to display literal Markdown characters:

\*This is not italic\*
\# This is not a heading

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

Markdown Preview Online

Use the Markdown preview tool to write and preview Markdown in real time. The live preview updates as you type, showing exactly how headings, links, images, code blocks, and tables will render.