Markdown Complete Guide: Syntax, Tips & Real-World Uses (2026)

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It lets you format plain text using simple symbols — asterisks, hashes, brackets — that render as styled HTML. The core idea: a Markdown file should be readable as-is, even without being rendered.

Today, Markdown is everywhere: GitHub READMEs, documentation sites, blogging platforms (Ghost, Hashnode, Dev.to), note-taking apps (Notion, Obsidian, Bear), messaging tools (Slack, Discord), and static site generators (Jekyll, Hugo, Astro). Learning Markdown is one of the most practical writing skills a developer or technical writer can have.

Headings

Use # symbols to create headings. The number of # signs corresponds to the heading level (H1–H6):

# H1 — Page Title
## H2 — Section
### H3 — Subsection
#### H4
##### H5
###### H6

Best practice: Use only one H1 per document (the page title). Use H2 for major sections and H3 for subsections. Avoid skipping levels (e.g., going from H2 to H4) for proper document structure and accessibility.

Emphasis: Bold, Italic, Strikethrough

**bold text**          → renders as bold
*italic text*          → renders as italic
__also bold__
_also italic_
***bold and italic***
~~strikethrough~~      → crossed-out text
`inline code`          → monospace, not rendered as Markdown

Tip: Prefer ** for bold and * for italic to avoid ambiguity — underscores inside words (like some_variable_name) can behave unexpectedly in some parsers.

Lists

Unordered Lists

Use -, *, or + as bullet markers (pick one and be consistent):

- First item
- Second item
  - Nested item (indent 2 spaces)
  - Another nested item
- Third item

Ordered Lists

Use numbers followed by a period. The actual numbers do not matter — most parsers render them sequentially regardless:

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

Task Lists (GitHub-Flavoured Markdown)

Create interactive checklists that render as checkboxes on GitHub:

- [x] Set up project repository
- [x] Write README
- [ ] Configure CI/CD pipeline
- [ ] Deploy to production

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
[Reference-style link][ref-id]

[ref-id]: https://example.com "Optional title"

![Alt text](image.jpg)
![Alt text](image.jpg "Image title")
[![Linked image](badge.svg)](https://example.com)

Auto-links: Wrap a URL in angle brackets to make it clickable without link text: <https://example.com>

Reference-style links keep your prose readable when you have many links — define the URLs at the bottom of the document, reference them by a short label throughout the text.

Code

Inline Code

Wrap text in single backticks for inline code: `console.log("hello")`. Use double backticks if the code contains a backtick itself: ``use `backticks` like this``

Fenced Code Blocks

Use triple backticks (or tildes) with an optional language identifier for syntax highlighting:

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

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

```sql
SELECT id, name, email
FROM users
WHERE active = 1
ORDER BY created_at DESC;
```

Supported language identifiers include: bash, css, diff, dockerfile, go, html, java, json, kotlin, markdown, php, python, ruby, rust, scss, sql, typescript, xml, yaml.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> You can have blank lines inside blockquotes.
>
> > Nested blockquote (attribution, for example)

Blockquotes are useful for callout notes, warnings, quotes from documentation, and nested replies in discussions.

Tables (GFM)

GitHub-Flavoured Markdown (GFM) adds table support. Use pipes | and hyphens - to define columns and alignment:

| Tool          | Category  | Free? |
|---------------|-----------|-------|
| JSON Formatter| Developer | Yes   |
| Regex Tester  | Developer | Yes   |
| Image Resizer | Image     | Yes   |

| Left align | Center align | Right align |
|:-----------|:------------:|------------:|
| Cell       | Cell         | Cell        |
| Data       | Data         | Data        |

Colons in the separator row control alignment: :--- = left, :---: = center, ---: = right.

Horizontal Rules

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

---
***
___

Footnotes (Extended Markdown)

This is a sentence with a footnote.[^1]

[^1]: This is the footnote text, rendered at the bottom of the page.

Escaping Special Characters

Prefix any Markdown-special character with a backslash to render it literally:

\*Not italic\*        → renders as *Not italic*
\# Not a heading      → renders as # Not a heading
\[Not a link\](url)  → renders as [Not a link](url)

Characters that need escaping: \ ` * _ { } [ ] ( ) # + - . !

HTML Inside Markdown

Most Markdown parsers allow raw HTML inline. This is useful for features Markdown does not support natively:

  
Click to expand
  Hidden content here.


Highlighted text

Ctrl+C

Text with a line break
continuing on the same block.

Markdown Flavours

Standard Markdown (CommonMark) is the base. Different platforms extend it:

• GitHub-Flavoured Markdown (GFM): Adds tables, task lists, strikethrough, auto-linking, and syntax highlighting in fenced code blocks
• MDX: Markdown + JSX — write React components inside Markdown documents. Used in Next.js, Docusaurus, Astro
• Obsidian Flavour: Adds wiki-links ([[Page Name]]), callout blocks, and canvas support
• Pandoc Markdown: Supports citations, definition lists, superscript, subscript, and complex academic document features

Where Markdown Is Used

• GitHub: README.md, wiki pages, issue comments, pull request descriptions, GitHub Discussions
• Documentation: MkDocs, Docusaurus, GitBook, ReadTheDocs, VitePress
• Note-taking: Obsidian, Notion, Bear, Joplin, Logseq
• Blogging: Ghost, Hashnode, Dev.to, Jekyll, Hugo, 11ty, Astro
• Messaging: Slack (*bold*, `code`, ```blocks```), Discord, Mattermost
• Presentations: Marp, Slidev, reveal.js
• Email: Some email clients (Superhuman, HEY) render Markdown
• AI prompting: ChatGPT, Claude, Gemini all render Markdown responses

Quick Reference Cheatsheet

# H1  ## H2  ### H3

**bold**   *italic*   ~~strike~~   `code`

- unordered   1. ordered   - [x] task

[text](url)     ![alt](img.jpg)

> blockquote

```lang
code block
```

| Col1 | Col2 |
|------|------|
| A    | B    |

---   (horizontal rule)

[^1]  footnote reference     [^1]: footnote text