Markdown Guide: Complete Syntax Reference for Developers and Writers

Markdown is a lightweight markup language that converts plain text to formatted HTML. Created by John Gruber in 2004, it's now the standard for README files, documentation, blog posts, and developer notes. This reference covers everything from basic syntax to GitHub Flavored Markdown (GFM) extensions.

Headings

Use hash symbols to create headings. The number of hashes determines the heading level:

# Heading 1       → <h1>
## Heading 2      → <h2>
### Heading 3     → <h3>
#### Heading 4    → <h4>
##### Heading 5   → <h5>
###### Heading 6  → <h6>

Always add a space after the hash. Many parsers require it. Heading 1 should appear only once per document — it becomes the page title.

Text Formatting

**bold**           → bold
*italic*           → italic
***bold italic***  → bold italic
~~strikethrough~~  → strikethrough (GFM)
`inline code`     → inline code

Use _underscores_ as an alternative to asterisks for bold/italic — both work, but asterisks are more widely supported in all Markdown parsers.

Paragraphs and Line Breaks

A blank line between text creates a new paragraph. A single newline without a blank line is ignored and rendered as a space — this is intentional, making it easy to wrap long lines in source code.

Paragraph one.

Paragraph two.

Line one  ← two trailing spaces force a line break
Line two

Lists

Unordered Lists

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

* Also works with asterisks
+ Or plus signs

Ordered Lists

1. First
2. Second
3. Third

1. Markdown auto-numbers these
1. So all can be "1."
1. And it still renders correctly

Task Lists (GFM)

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

Links and Images

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

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

<!-- Reference-style links -->
[Link text][ref]
[ref]: https://example.com

Code

Inline Code

Use backticks for `inline code`

Code Blocks

```javascript
const greeting = 'Hello, world!'
console.log(greeting)
```

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

```bash
npm install && npm run build
```

Specifying the language after the opening backticks enables syntax highlighting in GitHub, VS Code, and most Markdown renderers. Common language identifiers: js, ts, python, bash, sql, json, yaml, css, html.

Blockquotes

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

> Nested blockquote:
>> Inner level
>>> Three levels deep

Tables (GFM)

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

<!-- Alignment with colons -->
| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| text     | text     | text     |

Table columns don't need to be perfectly aligned — Markdown only requires the pipe and dash structure. Alignment is optional and cosmetic in source code.

Horizontal Rules

---
***
___

Three or more dashes, asterisks, or underscores create a horizontal rule.

HTML in Markdown

Most Markdown parsers allow raw HTML inline. This is useful for features Markdown doesn't support natively:

<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

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

<mark>highlighted text</mark>

Escaping Characters

Prefix a Markdown character with a backslash to render it literally:

\*not italic\*   → *not italic*
\## not a heading → ## not a heading
\[not a link\]   → [not a link]

GitHub Flavored Markdown (GFM) Extensions

README Best Practices

A good README file typically includes:

1. Project title with a one-line description
2. Badges (build status, license, npm version)
3. Quick start — installation and a minimal working example
4. Usage — more complete examples and API reference
5. Configuration — options, environment variables
6. Contributing — how to file issues and submit PRs
7. License — always include