Markdown is a lightweight markup language that lets you write formatted text using plain text syntax. It was created by John Gruber in 2004 with the goal of being readable as-is, without looking like HTML tags. Today, Markdown is used everywhere: GitHub READMEs, Jupyter notebooks, documentation sites, note-taking apps (Obsidian, Notion), and countless developer tools. This guide covers the complete syntax with practical examples.

Why Markdown?

The core appeal of Markdown is that the source is readable even without rendering. Compare **bold text** (Markdown) with <strong>bold text</strong> (HTML) — the Markdown version communicates meaning at a glance. Markdown also converts cleanly to HTML, PDF, Word, and other formats through tools like Pandoc.

Markdown has no single official standard — different platforms implement slightly different "flavors." The most widely used is GitHub Flavored Markdown (GFM), which adds tables, task lists, strikethrough, and syntax-highlighted code blocks to the original spec.

Headings

Headings are created with one to six hash symbols. The number of hashes corresponds to the HTML heading level:

# Heading 1 (h1)
## Heading 2 (h2)
### Heading 3 (h3)
#### Heading 4 (h4)
##### Heading 5 (h5)
###### Heading 6 (h6)

Best practice: use only one h1 per document (your main title). Use h2 for major sections and h3 for subsections. This matches the heading hierarchy expected by screen readers and SEO crawlers.

Emphasis: Bold, Italic, Strikethrough

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic***
~~Strikethrough~~ (GitHub Flavored Markdown only)

Prefer asterisks over underscores for bold and italic — they work more reliably in the middle of words and are consistent across all Markdown flavors. Underscores can cause issues in words like some_variable_name.

Lists

Unordered Lists

Use -, *, or + followed by a space. Be consistent — do not mix different markers in the same list:

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

Ordered Lists

Numbers followed by a period. The actual number doesn't matter — Markdown will auto-number them correctly:

1. First item
1. Second item (Markdown renumbers automatically)
1. Third item

Task Lists (GitHub Flavored Markdown)

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

Code: Inline and Blocks

Inline Code

Wrap code in single backticks for inline formatting: `variable_name` renders as variable_name. Use this for function names, variable references, file paths, and short commands within a sentence.

Fenced Code Blocks

Use triple backticks for multi-line code blocks. Add the language name immediately after the opening backticks for syntax highlighting:

Example fenced code block with language specifier:

  Triple backticks + javascript
  function greet(name) {
    // function body here
  }
  Triple backticks (closing)

  Triple backticks + sql
  SELECT id, name FROM users WHERE active = true;
  Triple backticks (closing)

Supported language identifiers include: javascript, typescript, python, java, go, rust, sql, bash, sh, json, yaml, html, css, markdown, diff, and dozens more.

Tables (GitHub Flavored Markdown)

Tables are created with pipe characters and hyphens. The second row (hyphens) is mandatory and defines column alignment:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A   | Cell B   | Cell C   |
| Cell D   | Cell E   | Cell F   |

Control alignment with colons in the separator row:

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

Creating tables manually is tedious. Use the Excel to Markdown Table generator — paste directly from Excel or Google Sheets and get a perfectly formatted Markdown table in one click.

Links and Images

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

![Alt text for image](path/to/image.png)
![Alt text with title](path/to/image.png "Image title")

Reference-style links keep the body of your document clean when you have many links:

[Link text][reference-id]

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

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> Blank lines inside continue the blockquote.
>
> > Nested blockquotes use double angle brackets.

Horizontal Rules

Three or more hyphens, asterisks, or underscores on their own line create a horizontal rule:

---
***
___

Escaping Special Characters

Backslash escapes any Markdown special character: \*literal asterisks\* renders as *literal asterisks* without bold formatting. Characters that can be escaped: \ ` * _ [ ] ( ) # + - . !

Raw HTML

Most Markdown processors allow raw HTML inline. This is useful for features Markdown doesn't natively support, like text color, superscript, subscript, or custom classes:

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

Markdown for GitHub READMEs: Best Practices

  • Start with a project logo or banner image if available
  • Include badges (build status, version, license) using shields.io
  • Add a Table of Contents for READMEs longer than ~500 words
  • Use fenced code blocks with language identifiers for all code samples
  • Include a "Getting Started" or "Installation" section near the top
  • Add a "Contributing" section and a "License" section
  • Test all links — broken documentation links are a common complaint

The Word & Character Counter can help you monitor your README length. For most projects, a README between 300 and 1,500 words strikes the right balance between completeness and readability.