Markdown Guide: Complete Syntax Reference & Online Editor (2026)

Headings

Use # symbols to create headings. More hashes = smaller heading.

Text Formatting

Lists

Unordered lists use -, *, or + as bullet markers:

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

Ordered lists use numbers followed by a period:

1. First step
2. Second step
3. Third step

Links

Images

Images use the same syntax as links, prefixed with !:

![Alt text](image-url.jpg "Optional title")
![Logo](https://example.com/logo.png)

To resize images in GitHub-Flavored Markdown, you can use HTML:

<img src="image.png" width="300" alt="Description">

Code Blocks

Inline code uses single backticks: `const x = 42;`

Fenced code blocks use triple backticks with an optional language identifier for syntax highlighting:

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

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

Tables

Markdown tables use pipes | and hyphens -:

| Name    | Role      | City      |
|---------|-----------|-----------|
| Alice   | Developer | Mumbai    |
| Bob     | Designer  | Bangalore |
| Charlie | PM        | Delhi     |

Column alignment is controlled by colons in the separator row:

| Left   | Center  | Right  |
|:-------|:-------:|-------:|
| text   |  text   |   text |

• :--- = left-aligned (default)
• :---: = centre-aligned
• ---: = right-aligned

Task Lists (GitHub-Flavored Markdown)

- [x] Create project repository
- [x] Set up CI/CD pipeline
- [ ] Write unit tests
- [ ] Deploy to production

Renders as interactive checkboxes in GitHub issues and pull requests.

Horizontal Rules

Three or more hyphens, asterisks, or underscores create a horizontal line:

---
***
___

Footnotes

Markdown was created by John Gruber[^1] in 2004.

[^1]: John Gruber is the author of Daring Fireball blog.

Emoji (GitHub-Flavored)

:rocket: :fire: :thumbsup: :warning:

GitHub-Flavored Markdown (GFM) extends standard Markdown with features specifically useful for developers and collaboration:

Auto-linked References

Alert Blocks (New in GitHub)

> [!NOTE]
> This is a note.

> [!TIP]
> This is a tip.

> [!WARNING]
> This is a warning.

> [!CAUTION]
> This is a caution.

These render as beautifully styled callout boxes in GitHub READMEs and issues.

Mermaid Diagrams

GitHub supports Mermaid diagrams inside fenced code blocks:

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

This renders as an interactive flowchart diagram — no images or external tools needed.

Math Expressions (LaTeX)

GitHub supports LaTeX math in Markdown:

Inline: $E = mc^2$

Block:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

Best Use Cases for Markdown

• GitHub README files: Every open-source project needs a well-formatted README. Use headings, badges, installation instructions, and code examples.
• Technical documentation: Tools like MkDocs, Docusaurus, and GitBook use Markdown files as the source for beautiful documentation sites.
• Blog posts: Platforms like DEV.to, Hashnode, and Hugo static sites accept Markdown directly. Write once, publish anywhere.
• Note-taking: Apps like Obsidian, Notion, and Logseq use Markdown as their native format. Your notes remain portable and future-proof.
• Email drafts: Write in Markdown, convert to rich text. Many email clients and extensions support this workflow.
• Presentations: Tools like Marp and Slidev let you create slide decks from Markdown files.

Pro Tips for Better Markdown

• Add a blank line between elements: Paragraphs, lists, and headings need blank lines before and after them to render correctly. This is the #1 cause of formatting issues.
• Use reference-style links for readability: If you link to the same URL multiple times, use [text][ref] syntax to keep your source clean.
• Escape special characters with backslash: To display literal *, #, [, ], use \*, \#, \[, \].
• Use two spaces at the end of a line for a line break: Or use <br> for explicit line breaks within a paragraph.
• Keep lines under 80–120 characters: This makes Markdown readable as source code and easier to diff in Git.

Markdown Editor Comparison