Markdown Syntax: A Practical Cheat Sheet for Headings, Lists, Links, and Code

Markdown turns plain punctuation into structured text: # for headings, - for list items, [text](url) for links, and backticks for code. This cheat sheet covers the four constructs you reach for most, with copy-ready examples and notes on where CommonMark and GitHub Flavored Markdown (GFM) part ways.

Quick answer

The four building blocks, at a glance:

• Headings: one to six # characters, then a space and your text.
• Lists: -, *, or + for bullets; 1. for numbered items.
• Links: [visible text](https://example.com).
• Code: single backticks inline, three backticks for a fenced block.

Everything below expands on these, plus the GFM extras — tables, task lists, and language-tagged fences — that show up in everyday writing.

How it actually works

Headings

Markdown's original "atx" style puts one to six hash characters at the start of a line, mapping to <h1> through <h6>:

# Top-level heading
## Section heading
### Sub-section

The count of # sets the level. Both CommonMark and GFM require a space after the hashes — #Heading with no space is just text. Leave a blank line after a heading so parsers treat it as its own block. One practical note: when you write an article body for the web, the page title is usually the H1, so the body itself should start at ##.

Lists

Unordered lists take -, *, or + as the marker, and you can use whichever you like:

- First item
- Second item
  - Nested item (indent two spaces)

Ordered lists use a number followed by a period. The numbers you type don't change the output — the original rules let you write 1. on every line and still get 1, 2, 3 — but starting at 1. keeps the source readable, as John Gruber's syntax doc explains.

1. Outline the draft
2. Write the body
3. Edit and publish

GFM adds task lists: bullets with [ ] or [x].

- [x] Draft the post
- [ ] Add code examples

Links

An inline link wraps the visible text in square brackets, then the URL in parentheses:

Read the [CommonMark spec](https://spec.commonmark.org/) for the edge cases.

For a link inside your own site, drop the domain and use a relative path like [About](/about). When you reference the same URL several times, reference-style links keep the prose clean — label the link in brackets, then define the target on its own line:

See the [spec][cm] for details.

[cm]: https://spec.commonmark.org/

Code

Use single backticks for inline code, like git status. For multi-line code, fence it with three backticks and name the language right after the opening fence — most renderers then apply syntax highlighting. Here's the source you type:

def greet(name): return "Hello, " + name

That first word after the fence — the "info string" — names the language, per the GFM spec. If your sample itself contains three backticks, open the fence with four instead; the closing fence just has to be at least as long.

When to use it (and when to skip it)

Markdown is the right tool when content is mostly prose with light structure: blog posts, READMEs, documentation, notes, and issue comments. It stays readable as plain text, so your files outlast any single app or proprietary format.

It's the wrong tool when you need precise layout — multi-column pages, exact spacing, or tables with merged cells. Markdown maps to a small subset of HTML on purpose; for anything past that, you drop to raw HTML where the renderer allows it, or use a real layout tool. The two flavors also trip people up: a table or task list that renders on GitHub can show up as literal text in a strict CommonMark renderer, because tables and task lists are GFM extensions, not core CommonMark. When portability matters, lean on the constructs both support — headings, lists, links, emphasis, blockquotes, and fenced code.

How Carets fits in

A cheat sheet helps, but the syntax sticks faster when you can watch it render as you type. Carets is a native notes and code editor for iPhone, iPad, and Mac built for that: you write Markdown, plain text, and code with syntax highlighting in one editor, and your work stays in portable plain-text files.

Three things make it a good home for the syntax above. Markdown and code sit side by side, so a fenced python block highlights in the same place your notes live — no app-switching. Syntax highlighting covers code and config files, which makes the difference between a tagged fence and an untagged one obvious at a glance. And files, projects, and tags keep a growing cheat sheet, snippet library, or stack of drafts organized instead of scattered. Because it's native to Apple platforms rather than a web wrapper, editing stays quick on a phone as well as a Mac, and your files remain plain text you can open anywhere.

If you write Markdown across iPad and Mac, or keep a snippet library organized with files and tags, Carets is built for that workflow. Download Carets on the App Store for iPhone, iPad, and Mac.

Frequently asked questions

What's the difference between CommonMark and GFM?

CommonMark is a strict, unambiguous specification of core Markdown. GitHub Flavored Markdown is a superset that adds tables, task lists, strikethrough, and autolinks on top of it. Anything valid in CommonMark is valid in GFM, but not the other way around.

Do I need a blank line between Markdown elements?

Usually, yes. A blank line separates block elements — paragraphs, headings, lists, and code blocks. Leaving it out can fold a heading or list into the paragraph above it.

How do I show literal Markdown characters?

Escape them with a backslash. For example, \*not emphasized\* renders as plain asterisks, and 1986\. keeps a year from starting an accidental ordered list.

Which Markdown should I learn first?

Start with headings, lists, links, and fenced code. They cover the large majority of everyday writing and work in nearly every renderer. Add GFM tables and task lists once the basics are automatic.