Markdown Cheat Sheet: Complete Syntax Reference

Headings

Use # symbols, one per heading level. Leave a space after the #. Most renderers require a blank line before a heading when it follows body text.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Setext Style (H1 and H2 only)

Heading 1
=========

Heading 2
---------

Setext style works in CommonMark but looks confusing in raw form. Stick to ATX style (#) for consistency.

Emphasis and Inline Formatting

Inline Code with Backticks

Use `single backticks` for inline code.

To include a backtick inside code: ``use ` double backticks``

To include double backticks: ``` use `` triple ``` 

Horizontal Rules

---
***
___

(Three or more; dashes, asterisks, or underscores. Blank lines around recommended.)

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested (2 spaces)
    - Deeper (4 spaces)
- Item 3

* Also valid
+ Also valid

Ordered Lists

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

1. The numbers
1. don't have to
1. be sequential

Lists with Paragraphs

Separate list items with blank lines to make each item a paragraph (loose list):

- First item

  This paragraph is part of the first item (4-space indent).

- Second item

  Second paragraph of second item.

Task Lists (GFM)

- [x] Write article outline
- [x] Add code examples
- [ ] Review for accuracy
- [ ] Publish

Links

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

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

[Relative link](../other-page/)

[Reference-style link][ref-id]
[Another reference][website]

[ref-id]: https://example.com
[website]: https://example.org "Site title"

<https://example.com>          Auto-linked URL (angle brackets)
<user@example.com>            Auto-linked email

Reference-Style Link Tips

Put all your reference definitions at the bottom of the document. This keeps the prose clean and makes URLs easy to update when they change. Reference IDs are case-insensitive.

The [Markdown spec][spec] and [CommonMark][cm] have some differences.

[spec]: https://spec.commonmark.org/
[cm]: https://commonmark.org/ "CommonMark home"

Images

![Alt text](image.jpg)

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

![Reference-style image][logo]

[logo]: /assets/logo.png "Company Logo"

[![Clickable image](image.jpg)](https://example.com)
(Wrapping image in link syntax makes it clickable)

Alt text matters for accessibility and SEO. Describe what's in the image, not just what it looks like. An empty alt ![](decorative.jpg) tells screen readers to skip it — appropriate for purely decorative images.

Sizing Images

Standard Markdown has no syntax for image dimensions. Options:

<!-- Raw HTML (works in most renderers) -->
<img src="image.jpg" alt="Alt text" width="400" height="200">

<!-- GitHub doesn't support width/height on img tags -->
<!-- Pandoc supports custom attributes: -->
![Alt text](image.jpg){ width=400 height=200 }

Code Blocks

Fenced Code Blocks (Preferred)

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

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

```sql
SELECT * FROM users WHERE active = 1;
```

```
Plain block with no syntax highlighting
```

Common Language Identifiers

Indented Code Blocks (Legacy)

    // Indent 4 spaces or 1 tab
    function example() {
      return true;
    }

Indented blocks are CommonMark-standard but can't specify language. Use fenced blocks instead.

Tables

Tables are a GFM extension — not in CommonMark. Alignment is controlled by colons in the separator row.

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell     | Cell     | Cell     |
| Cell     | Cell     | Cell     |

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

Tips for usable tables:

• You don't need to align the pipe characters — just having them is enough
• Markdown inside cells works: **bold**, `code`, links
• For complex tables (merged cells, multiline), use HTML <table> directly
• Pipes at the start and end of rows are optional in most renderers

Blockquotes

> This is a blockquote.
> Continuation of the same blockquote.

> First paragraph.
>
> Second paragraph (blank line with > between).

> Nested blockquotes:
>> Second level
>>> Third level

> Blockquotes support other syntax:
> - List items
> - **Bold text**
> - `inline code`

GitHub Flavored Markdown (GFM) Extensions

GFM is the spec GitHub uses. It extends CommonMark with several features that have become de facto standard.

Strikethrough

~~This text is struck through~~

Autolinks

https://github.com/user/repo     (auto-linked without angle brackets in GFM)
user@example.com                  (auto-linked email in GFM)

GitHub-specific references:
@username                         (mention a user)
#123                              (link to issue/PR)
SHA-1 commit ref: a5c3785         (links to commit)

Footnotes (GFM / Pandoc)

This is text with a footnote.[^1]

Here's another.[^note]

[^1]: This is the footnote content.
[^note]: Footnotes can have identifiers, not just numbers.

Supported by GitHub, Pandoc, and most static site generators. Not in all renderers.

GitHub Alerts (GitHub-Specific)

> [!NOTE]
> Highlights information that users should take into account.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention.

> [!CAUTION]
> Negative potential consequences of an action.

Tables with Content

| Feature    | Support |
|------------|---------|
| **Bold**   | Yes     |
| `code`     | Yes     |
| [links][1] | Yes     |
| Newlines   | No      |

Frontmatter (YAML, TOML, JSON)

Frontmatter is metadata at the top of a Markdown file, delimited by ---. It's not part of Markdown spec itself — it's a convention used by static site generators (Jekyll, Hugo, Eleventy, Astro), documentation tools (Docusaurus), and other processors.

---
title: "My Article Title"
date: 2026-03-27
tags: ["markdown", "documentation"]
draft: false
author: "Developer"
description: "A longer description for SEO and social sharing."
---

# Article Content Starts Here

The frontmatter above is parsed separately and not rendered as content.

TOML Frontmatter (Hugo)

+++
title = "My Article"
date = 2026-03-27T00:00:00Z
tags = ["markdown"]
+++

JSON Frontmatter

{
  "title": "My Article",
  "date": "2026-03-27"
}

Content starts here (after the closing brace).

Embedding HTML

Most Markdown renderers allow raw HTML inline. This is useful when Markdown can't express what you need.

<!-- HTML comment (hidden in output) -->

<div class="callout">
  This is a custom styled block. Markdown **might not render** inside block HTML elements.
</div>

<span style="color: red;">Inline HTML works reliably</span> for inline elements.

<table>
  <tr><th>Column A</th><th>Column B</th></tr>
  <tr><td>Use HTML tables</td><td>for merged cells</td></tr>
</table>

GitHub sanitizes HTML in Markdown files — it strips <script>, on* event handlers, and some CSS. This is expected behavior, not a bug.

MDX: Markdown with JSX Components

MDX lets you import and use React (or other framework) components directly in Markdown. It's the format of choice for documentation sites built with Next.js, Astro, and Docusaurus.

---
title: "Using MDX"
---

import { Callout } from '../components/Callout'
import { CodeBlock } from '../components/CodeBlock'

# My MDX Document

Regular **Markdown** works normally here.

<Callout type="warning">
  This is a custom component. No blank lines needed around JSX elements.
</Callout>

You can mix prose and components freely.

<CodeBlock language="javascript" filename="example.js">
  {`const greeting = "Hello from MDX";`}
</CodeBlock>

Things to know about MDX:

• JSX expressions use {'{}'} — which conflicts with template engines like Nunjucks or Jekyll Liquid
• Comments use {'{ /* ... */ }'}, not HTML comments
• Self-closing tags must close: <br /> not <br>
• Class attribute must be className in JSX, not class

Rendering Differences Between Platforms

Markdown is not one spec. Different tools interpret the same syntax differently. Here's where things diverge:

Known Gotchas

• Trailing spaces: CommonMark uses two trailing spaces for a line break (<br>). Some renderers ignore this. Use <br> in HTML directly if you need it.
• Indented lists: Some renderers require 4-space indentation for nested lists; others accept 2. GFM uses 2.
• Lazy continuation: In CommonMark, you don't need > on every line of a blockquote. Not all renderers support this.
• ATX headings without space: #Heading is not valid in CommonMark. Always use # Heading.

Tips for Writing Good Documentation in Markdown

Structure for Scannability

Most people don't read docs — they scan for what they need. Use headings generously. Keep paragraphs short. Favor bullet lists over prose for multi-item content. Put the most important information first in each section.

Code Over Description

Show, don't tell. A code example communicates more precisely than a paragraph of explanation and is faster to read. Provide runnable, copy-pasteable examples. Specify the language on every code block.

Consistent Link Text

Never use "click here" or "this link." The link text should describe the destination: [Unix Timestamp Converter](/calculator/unix-timestamp/) not [click here](/calculator/unix-timestamp/). This matters for accessibility (screen readers read link text in isolation) and SEO.

Table Alternatives

Tables work for structured comparisons but get ugly fast. For two-column definition-style content, consider a definition list (HTML) or a series of h4 headings with paragraphs. For complex tables, use HTML directly.

Escaping Special Characters

\*   literal asterisk
\#   literal hash
\[   literal bracket
\`   literal backtick
\!   literal exclamation
\\   literal backslash

(Backslash escapes any character with Markdown meaning)

Tools