The Complete Markdown Guide

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. It uses plain-text formatting syntax that converts to HTML — the philosophy being that a Markdown document should be readable as-is, without looking like it's been marked up with tags or formatting instructions.

The name is a play on "markup" — instead of marking text up with tags (like HTML does), Markdown keeps documents readable while adding structure through minimal, intuitive punctuation. A heading is created with #, bold text with **asterisks**, and links with [text](url) notation.

Markdown has become ubiquitous in technical writing and development contexts. GitHub renders Markdown automatically in READMEs, issues, and comments. Stack Overflow, Reddit, Discord, Slack, Notion, Obsidian, and countless other platforms support Markdown formatting. Understanding Markdown is increasingly a baseline skill for anyone working in technical fields.

Headings

# Heading 1 (largest)
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6 (smallest)

Headings create a document hierarchy. H1 is typically used once per page as the main title; H2 for major sections; H3 and below for subsections.

Emphasis

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___
~~Strikethrough text~~

Lists

Unordered list:
- First item
- Second item
  - Nested item (2 spaces or tab indent)
  - Another nested item
- Third item

Ordered list:
1. First item
2. Second item
3. Third item

Task list (GitHub Flavored Markdown):
- [x] Completed task
- [ ] Incomplete task

Links and Images

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

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

Reference-style links:
[Link text][reference-name]
[reference-name]: https://example.com "Optional title"

Blockquotes and Horizontal Rules

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes are also possible.

---
(Three dashes, asterisks, or underscores create a horizontal rule)

Inline Code and Code Blocks

Inline code: Use `backticks` for inline code.

Fenced code block with syntax highlighting:
```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

Extended Markdown syntax adds features beyond the original spec. Most modern platforms support these extensions, particularly GitHub Flavored Markdown (GFM).

Tables

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

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

Tables are supported in GitHub Flavored Markdown and most modern Markdown renderers. The alignment row (:--- for left, :---: for center, ---: for right) is required for tables to render correctly.

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Definition Lists

Term
: Definition of the term.

Another Term
: First definition.
: Second definition.

Collapsible Sections (HTML in Markdown)

Standard Markdown doesn't support collapsible sections, but platforms that render HTML-in-Markdown (like GitHub) support the HTML <details> element:

<details>
<summary>Click to expand</summary>

This content is hidden until the summary is clicked.
You can include **Markdown** inside.

</details>

One of Markdown's persistent frustrations is that there is no single definitive standard. The original specification by John Gruber left many ambiguities, and different platforms implemented extensions and resolved ambiguities differently. This led to the proliferation of "Markdown flavors."

Markdown is always transformed into HTML by a parser before being displayed. Understanding this transformation helps you predict how your Markdown will render and debug rendering issues.

# Hello World

**Bold** and *italic*

- Item 1
- Item 2

[Link](https://example.com)

<h1>Hello World</h1>
<p><strong>Bold</strong> and
<em>italic</em></p>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
<p><a href="https://example.com">
  Link</a></p>

This is why understanding HTML fundamentals helps with Markdown — you can often predict or explain Markdown behavior by thinking about the HTML it will produce. Conversely, in Markdown flavors that support HTML-in-Markdown, you can embed raw HTML for features Markdown doesn't support natively.

Markdown excels in contexts where documents need to be both human-readable as plain text and rendered with formatting. Here's where it genuinely shines: