---
title: "Markdown Syntax Cheatsheet"
slug: "markdown-syntax"
category: "cheatsheets"
tags: ["cheatsheets", "markdown", "commonmark", "obsidian", "mdx"]
status: "stable"
last_updated: 2026-05-14
summary: "Markdown variants compared: CommonMark, GFM, Obsidian, MDX. Which syntax works where for tables, footnotes, math, callouts, and wikilinks."
related:
  [
    "[[tooling/obsidian]]",
    "[[tooling/quartz]]",
    "[[writing/editorial-style]]",
    "[[cheatsheets/regex-patterns]]",
    "[[cheatsheets/index|Cheatsheets]]",
  ]
---

## Overview

Markdown is a family, not a spec. CommonMark is the baseline; GitHub Flavored Markdown (GFM) adds tables and task lists; Obsidian adds wikilinks and callouts; MDX adds JSX. Pick the dialect by the target renderer. This card lists what works where so you do not write `[[wikilink]]` into a GitHub issue and expect it to render.

## Inline syntax (universal)

The basics work in every dialect.

| Syntax                       | Renders as                  |
| ---------------------------- | --------------------------- |
| `*emphasis*` or `_emphasis_` | _emphasis_                  |
| `**strong**` or `__strong__` | **strong**                  |
| `` `code` ``                 | `code`                      |
| `[text](url)`                | hyperlink                   |
| `![alt](url)`                | image                       |
| `<https://example.com>`      | autolink                    |
| `&copy;`                     | HTML entities pass through. |

Two trailing spaces force a hard line break. Most editors strip them; prefer a blank line plus a new paragraph.

## Block syntax

What dialect supports which block.

| Block                         | CommonMark | GFM      | Obsidian | MDX                |
| ----------------------------- | ---------- | -------- | -------- | ------------------ |
| Heading `# H1`                | yes        | yes      | yes      | yes                |
| Paragraph                     | yes        | yes      | yes      | yes                |
| Bullet list `- item`          | yes        | yes      | yes      | yes                |
| Ordered list `1. item`        | yes        | yes      | yes      | yes                |
| Fenced code (triple backtick) | yes        | yes      | yes      | yes                |
| Indented code (4 spaces)      | yes        | yes      | yes      | no (parser change) |
| Blockquote `> text`           | yes        | yes      | yes      | yes                |
| Horizontal rule `---`         | yes        | yes      | yes      | yes                |
| Table                         | no         | yes      | yes      | yes                |
| Task list `- [ ]`             | no         | yes      | yes      | yes                |
| Strikethrough `~~text~~`      | no         | yes      | yes      | yes                |
| Footnote `[^1]`               | no         | yes (GH) | yes      | with plugin        |
| Math `$x^2$`                  | no         | yes (GH) | yes      | with plugin        |
| Wikilink `[[page]]`           | no         | no       | yes      | with plugin        |
| Callout `> [!note]`           | no         | yes (GH) | yes      | with plugin        |
| JSX components                | no         | no       | no       | yes                |

GitHub renders math and footnotes through extensions; raw CommonMark does not.

## Tables

GFM tables look like this and are supported in GFM, Obsidian, and MDX.

```markdown
| Column A | Column B |
| -------- | -------- |
| Cell     | Cell     |
```

Align columns with colons:

```markdown
| Left | Center | Right |
| :--- | :----: | ----: |
```

Tables do not support multi-line cells in any standard dialect. Use HTML `<br>` for line breaks inside a cell.

## Footnotes

GFM and Obsidian both support footnotes; the syntax is identical.

```markdown
Statement with a footnote.[^1]

[^1]: The footnote text.
```

CommonMark does not include footnotes. Convert them to inline parenthetical notes when targeting strict CommonMark.

## Math

LaTeX math renders in GitHub, Obsidian, and Quartz; Reddit and Slack do not render it.

```markdown
Inline math: $E = mc^2$.

Display math:

$$
\int_{a}^{b} f(x)\,dx
$$
```

Use single dollar signs for inline, double for display. Escape literal dollar signs as `\$`.

## Callouts (admonitions)

GitHub-style callouts work in GitHub, Obsidian, and Quartz.

```markdown
> [!note]
> Normal note.

> [!tip]
> A useful tip.

> [!warning]
> A warning.

> [!caution]
> Use sparingly.
```

GitHub supports `note`, `tip`, `important`, `warning`, `caution`. Obsidian supports those plus `info`, `success`, `question`, `failure`, `danger`, `bug`, `example`, `quote`.

## Wikilinks (Obsidian and Quartz)

Wikilinks are an Obsidian invention; Quartz renders them too.

```markdown
[[slug]]
[[slug|Display Text]]
[[folder/slug]]
[[folder/slug|Display Text]]
[[slug#Section]]
```

GitHub and most other renderers display wikilinks as literal `[[text]]`. Use `[text](path)` when targeting GitHub.

## MDX extras

MDX is Markdown with JSX. The full Markdown grammar is preserved; the additions are JSX and ESM imports.

```mdx
import Note from "./Note"

# Heading

<Note variant="warning">A React component inline.</Note>

Some prose.
```

MDX changes a few parser behaviors: indented code blocks are gone (everything indented is treated as JSX), and HTML tags must self-close (`<br />`, not `<br>`).

## Frontmatter

YAML frontmatter at the top of a file is widely supported in static-site generators but not by GitHub or strict CommonMark.

```markdown
---
title: "Page Title"
date: 2026-05-14
---

Content begins here.
```

GitHub displays the YAML as a table when the file is a README; in other files it shows the raw `---` block.

## Common gotchas

- A single blank line is required between blocks; without it, two paragraphs merge or a heading attaches to the previous line.
- Lists need a blank line before the first item to start a new list after a paragraph.
- Code fences must use the same character (` ``` ` or `~~~`) at open and close, with no leading indent past the parent context.
- Tables in Quartz require a blank line before the first pipe; otherwise the renderer treats the row as a paragraph.
- Wikilinks render as literal text on GitHub. Convert to `[text](path)` for `README.md` files.
- Hard line breaks via two trailing spaces are invisible in code review. Use a blank line plus a new paragraph instead.

## Related

- [[tooling/obsidian]]
- [[tooling/quartz]]
- [[writing/editorial-style]]
- [[cheatsheets/regex-patterns]]
- [[cheatsheets/index|Cheatsheets]]