# Markdown Cheat Sheet

Course: [Markdown](https://www.devtutorials.ai/learn/markdown) · Section: Reference
Source: https://www.devtutorials.ai/learn/markdown/reference/cheat-sheet

> Every syntax rule, GFM extra, platform extension, frontmatter rule, AI-native file and check from the course on one page, with live boxes.

## Markdown Cheat Sheet

Everything from the course on one page. Each box is live: change it, and switch between **CommonMark**, **GitHub (GFM)** and **Docs site** to see where each feature works.

## Core Syntax

These work in every flavour.

| You want | You write | Notes |
|---|---|---|
| Heading | `# Title` … `###### Small` | a space after the `#` signs |
| Paragraph | text, then a blank line | one line break alone does not start a new line |
| Line break | end the line with `\` | two trailing spaces also work, but are invisible |
| Bold | `**bold**` | no spaces just inside the stars |
| Italic | `*italic*` | underscores inside words are safe |
| Bullet list | `- item` | one mark per file; 2 spaces to nest |
| Numbered list | `1. step` | only the first number counts; 3 spaces to nest |
| Link | `[text](path)` | nothing between `]` and `(` |
| Heading link | `[text](#refund-window)` | anchors are added by the renderer |
| Reference link | `[text][label]` and `[label]: url` | the label must match |
| Web address | `<https://example.com>` | a bare address is a link only in GFM |
| Image | `![alt text](path)` | always write alt text |
| Inline code | `` `npm test` `` | marks do nothing inside code |
| Code block | three backticks, a language, the code, three backticks | always close it |
| Quote | `> text` | `>>` for a quote in a quote |
| Divider | `---` with a blank line above | without the blank line it makes a heading |
| Escape | `\*`, `\#`, `\_`, `\[` | shows the mark as text |

````md runnable title="The core in one box"
# Refund policy

Refunds are allowed within **30 days** of delivery.\
After that, offer a *voucher*.

1. Open the order
2. Check the receipt
   - Card or bank transfer

See the [shipping guide](docs/shipping.md) and <https://commonmark.org>.

![Refund flow: request, check, approve](/markdown-assets/refund-flow.svg)

```bash
npm test
```

> Ask a lead if you are not sure.

---

2023\. A year, not a list.
````

## GFM Extras

| You want | You write | Without GFM |
|---|---|---|
| Table | header row, `\|---\|---\|`, rows | a paragraph of pipes |
| Right-aligned column | `---:` in the divider | — |
| Pipe in a cell | `\|` | the cell splits |
| Task list | `- [ ] open` and `- [x] done` | `[ ]` shown as text |
| Strikethrough | `~~old~~` | tildes shown as text |
| Footnote | `text[^1]` and `[^1]: note` | shown as text |
| Automatic links | `https://example.com` | plain text |

```md runnable title="The GFM extras"
| Plan | Price |
|---|---:|
| Basic | Free |
| Pro | ₹999 |

- [x] Fix refund rounding
- [ ] Add order search

~~3 days~~ 2 days.[^1]

[^1]: For card refunds.
```

## Platform Extensions

| You want | You write | Works on |
|---|---|---|
| Note or warning box | `> [!NOTE]`, `> [!WARNING]` (also TIP, IMPORTANT, CAUTION) | GitHub, many docs sites |
| Diagram | a code block with the hint `mermaid` | GitHub, most docs sites |
| Data about the file | YAML between two `---` lines at the very top | docs sites, AI tools |
| Collapsible section | `<details>`, `<summary>`, then a blank line | GitHub and most HTML-friendly renderers |
| Keyboard key | `<kbd>Ctrl</kbd>` | where HTML is allowed |
| Maths | `$a^2$` inline, `$$ … $$` on its own lines | GitHub and many docs sites; elsewhere write `\$` for a dollar sign |

````md runnable title="Platform extensions" dialect="docs"
---
title: Refund policy
owner: support-team
---

> [!WARNING]
> Refunds over ₹5,000 need a manager's approval.

```mermaid
flowchart LR
  A[Request] --> B[Check] --> C[Approve]
```

<details>
<summary>Show the refund times</summary>

- Card: up to 3 working days
- Bank transfer: up to 5 working days

</details>
````

## Frontmatter and YAML

| Rule | Example |
|---|---|
| First line is exactly `---` | nothing above it, not even a blank line |
| `key: value`, with a space after the colon | `title: Refund policy` |
| Quote values with `: ` or ` #` or a leading special character | `title: "Refunds: the rules"`, `channel: "#refunds"` |
| Quote numbers that must stay text | `version: "1.10"`, `zip: "012"` |
| Lists | `tags: [refunds, billing]` or lines starting `  - ` |
| Groups | a key, then indented keys below it, with spaces |
| Long text | `|` keeps line breaks, `>` folds them |
| Never | tabs in the indent |

## AI-Native Files

| File | Where | Loads | Must have |
|---|---|---|---|
| `AGENTS.md` | repo root; subfolders for local rules | every session | commands; only what the code cannot say; well under 150 lines |
| `CLAUDE.md` | repo root | every Claude Code session | `@AGENTS.md` to share one file |
| Cursor rule | `.cursor/rules/*.mdc` | when its `globs` match, or always | `description`, `globs`, `alwaysApply` |
| Skill | `.claude/skills/<name>/SKILL.md` (Codex: `.agents/skills/`, Cursor: `.cursor/skills/`) | name and description at start; body when picked | `name` matching the folder; a description with what, when and when not |
| Subagent | `.claude/agents/<name>.md` | when work is handed to it | `name`, `description`; a body with scope, checks and output format |
| Spec | `specs/<feature>.md` | when you point the agent at it | goal, non-goals, checkable acceptance criteria, no `TBD` |
| Codex subagent | `.codex/agents/<name>.toml` | when work is handed to it | `name`, `description`, `developer_instructions` |
| `llms.txt` | docs site root | when an AI tool fetches your docs | `#` title, `>` summary, `##` lists of `- [name](url): notes` |

The paths for the tool you picked:

```md runnable clean file=".claude/skills/refund-check/SKILL.md" title="SKILL.md skeleton" dialect="docs"
---
name: refund-check
description: "Checks a refund request against the refund policy. Use when a refund is requested or late. Do not use for shipping or tracking."
---

# Refund check

## Steps

1. Find the order.
2. Check the 30-day window.

## Output

One line: approve, voucher or needs approval, then the reason.
```

## The Course's Checks

| Id | Checks | From |
|---|---|---|
| `MD001`–`MD059` | headings, blank lines, code hints, alt text, bare links, link text | markdownlint rule ids |
| `AGT001`–`AGT004` | AGENTS.md size, commands, filler, hidden comments | this course |
| `SKL001`–`SKL005` | SKILL.md frontmatter, name, folder, description, length | this course, from the Agent Skills spec |
| `SUB001`–`SUB003` | subagent frontmatter, name, body | this course, from Claude Code's docs |
| `SPC001`–`SPC007` | spec goal, criteria, non-goals, vague words, open questions, conflicting numbers, unclear criteria | this course |
| `LNK001` | link to a file that does not exist | this course |
| `LLM001`–`LLM005` | llms.txt title, summary, headings, file-list items, notes | this course, from llmstxt.org |
| `STY001`–`STY004` | bold overuse, header inflation, deep bullets, emoji headings | this course |

## Pages in This Course

- [Markdown Basics](/learn/markdown/fundamentals/markdown-basics) · [Headings and Paragraphs](/learn/markdown/fundamentals/headings-and-paragraphs) · [Lists and Nesting](/learn/markdown/fundamentals/lists-and-nesting) · [Links and Images](/learn/markdown/fundamentals/links-and-images) · [Code Blocks](/learn/markdown/fundamentals/code-blocks) · [Tables and Quotes](/learn/markdown/fundamentals/tables-and-quotes) · [Escaping and HTML](/learn/markdown/fundamentals/escaping-and-html)
- [Markdown Flavors](/learn/markdown/team-docs/markdown-flavors) · [Docs as Code](/learn/markdown/team-docs/docs-as-code) · [Frontmatter Basics](/learn/markdown/team-docs/frontmatter-basics)
- [AGENTS.md Files](/learn/markdown/ai-native/agents-md) · [Skills and Subagents](/learn/markdown/ai-native/skills-and-subagents) · [Specs and Plans](/learn/markdown/ai-native/specs-and-plans) · [LLM-Friendly Docs](/learn/markdown/ai-native/llm-friendly-docs) · [Cleaning AI Output](/learn/markdown/ai-native/cleaning-ai-output) · [Capstone Project](/learn/markdown/ai-native/capstone)
- [Render Gotchas](/learn/markdown/reference/render-gotchas): symptoms, causes and fixes.