Markdown Cheat Sheet & Complete Syntax Guide [2026]

Published April 19, 2026 · 8 min read · Markdown Previewer Tool

Markdown is the closest thing the web has to a universal writing format. Write it once and it renders cleanly on GitHub, in documentation sites, in note-taking apps, and in static site generators. This guide is both a quick-reference cheat sheet for when you forget the syntax and a full tutorial if you're learning Markdown for the first time.

1. What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004, with contributions from Aaron Swartz. The core design goal was plain-text readability: a Markdown file should be legible as-is, without rendering. The syntax uses familiar conventions from plain-text email — asterisks for emphasis, hyphens for lists — that people were already using informally.

When processed by a Markdown parser, it compiles to HTML. A heading written as # My Title becomes <h1>My Title</h1>. Bold written as **word** becomes <strong>word</strong>. The source file stays readable without any tooling; the rendered output is clean HTML.

In 2026, Markdown is used everywhere in software development and technical writing:

• README files — the standard format for repository documentation on GitHub, GitLab, and Bitbucket
• Documentation sites — platforms like Notion, Confluence, and MkDocs all accept Markdown
• Static site generators — Jekyll, Hugo, Gatsby, Eleventy, and Astro all build pages from Markdown files
• Blog platforms — Ghost and many headless CMS tools use Markdown natively
• Comments and forums — Reddit, Stack Overflow, and Discord all support Markdown for formatting comments
• Note-taking apps — Obsidian and Bear are built entirely around Markdown files
• Jupyter notebooks — Markdown cells sit alongside Python code cells for narrative documentation

2. Basic Syntax Reference

The following elements are supported by every conforming Markdown parser. They form the core of the language and work consistently across GitHub, VS Code, Notion, and static site generators.

Lists

Unordered lists use a hyphen, asterisk, or plus sign followed by a space. Ordered lists use numbers followed by a period. Nest lists by indenting two or four spaces (be consistent within a document).

- First item
- Second item
  - Nested item (2 spaces indent)
  - Another nested item
- Third item

1. Step one
2. Step two
3. Step three

Task Lists

Task lists (supported in GFM and most modern parsers) add interactive-looking checkboxes:

- [x] Write the introduction
- [x] Add the syntax table
- [ ] Review before publishing
- [ ] Add screenshots

Blockquotes

Use > at the start of a line to create a blockquote. Nest them with >>:

> This is a blockquote.
> It can span multiple lines.
>
>> This is a nested blockquote.

3. Extended Syntax (GFM)

CommonMark is the standardized Markdown specification. GitHub Flavored Markdown (GFM) extends it with features that are now expected by most developers. GFM is also the default flavor used by GitLab, Gitea, and many documentation tools.

GFM adds the following on top of CommonMark:

• Tables — pipe-delimited column syntax (covered in section 6)
• Task lists — - [ ] and - [x] checkboxes
• Fenced code blocks — triple backticks with an optional language identifier for syntax highlighting
• Strikethrough — ~~text~~
• Autolinks — bare URLs like https://example.com are automatically linked without needing the full link syntax
• Footnotes — [^1] inline references with [^1]: definition at the bottom
• Disallowed raw HTML — GFM sanitizes certain HTML tags in rendered output for security

If you're writing for GitHub READMEs or GitHub Pages, you're writing GFM. If you're writing for a custom static site generator or documentation tool, check which flavor it supports.

4. Code and Technical Formatting

Code formatting is one of Markdown's strongest features and the most important for technical documentation.

Inline Code

Wrap a word or phrase in single backticks for inline monospace formatting:

Run `npm install` to install dependencies.

This renders as: Run npm install to install dependencies.

Fenced Code Blocks

Use triple backticks to open and close a code block. Add a language identifier immediately after the opening backticks for syntax highlighting:

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

Common language identifiers: javascript, typescript, python, bash, sql, json, yaml, html, css, go, rust.

Alternatively, indent lines by four spaces to create a code block (older style, less common):

    This is a code block
    using indentation syntax

The fenced style with backticks is strongly preferred because it supports language labels and is visually clearer in the source.

5. Links and Images

Inline Links

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

Reference-Style Links

For documents with many links, reference-style keeps the prose clean:

Check out [SnapUtils][snaputils] for developer tools.

[snaputils]: https://snaputils.tools "Free developer tools"

The reference definitions can be placed anywhere in the document — typically at the bottom.

Images

Image syntax mirrors link syntax with a leading exclamation mark. The text in square brackets becomes the alt attribute:

![Alt text describing the image](https://example.com/image.png)
![Logo](./assets/logo.svg "SnapUtils logo")

Always write descriptive alt text. Screen readers announce it, and it appears if the image fails to load. An empty alt (alt="") is acceptable only for purely decorative images — use ![](url) to indicate intentionally empty alt.

6. Tables

Tables are a GFM extension (not in base CommonMark). Columns are separated by pipes (|). The second row is the header separator — dashes with optional colons for alignment:

| Name      | Role       | Language   |
|-----------|------------|------------|
| Alice     | Backend    | Go         |
| Bob       | Frontend   | TypeScript |
| Carol     | DevOps     | Python     |

Column alignment is controlled by colon placement in the separator row:

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

Tips for tables:

• Pipes at the start and end of each row are optional but improve readability
• Cell content does not need to be padded with spaces (though it helps visually)
• You cannot have multi-line cell content in standard Markdown tables — use HTML if you need that
• Tables do not require a blank line before them in most parsers, but adding one is safer

7. Common Markdown Mistakes

Most Markdown rendering issues trace back to a small set of predictable errors:

Forgetting a blank line before lists or headings

Many parsers require a blank line between a paragraph and a following list or heading. Without it, the list may render as plain text.

This paragraph needs a blank line after it.

- Otherwise this list might not render correctly

Using spaces instead of backticks for inline code

Adding spaces around a word does nothing in Markdown. Use backticks: `code`, not just spaces.

Not escaping special characters

Characters like *, _, #, [, ], and ` have special meaning in Markdown. To display them literally, prefix with a backslash:

\*This is not italic\*
\# This is not a heading

Inconsistent indentation in nested lists

Nested lists require consistent indentation. Some parsers require 4 spaces; others accept 2. Choose one and stick to it within a document. Mixing tabs and spaces almost always causes unexpected rendering.

Expecting SVG or HTML in environments that sanitize it

GitHub READMEs strip many HTML tags and all SVG. Don't rely on raw HTML for layout in contexts where you can't verify the output. Check the rendering environment's documentation.

Single newlines being ignored

A single newline between lines of text is treated as a space in most Markdown parsers — the lines will merge into one paragraph. To force a line break within a paragraph, end the line with two or more spaces. To start a new paragraph, leave a blank line.

8. Markdown Tool Comparison

Not all Markdown is the same. Different parsers and platforms support different feature sets. Here's how the major variants compare:

For most developers, GFM is the practical standard. It has the widest adoption and covers the features you'll need most often. Pandoc is worth learning if you frequently convert documents between formats or need LaTeX math rendering.

9. Frequently Asked Questions

What is the difference between Markdown and HTML?

Markdown is a lightweight shorthand that compiles to HTML. HTML is the raw markup that browsers render directly. Markdown is faster to write and more readable as plain text, but less flexible than HTML. Most Markdown processors allow you to mix in raw HTML when you need elements the Markdown syntax doesn't support natively — like <details> disclosure widgets or <sup> superscript.

What is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is GitHub's Markdown extension, built on top of the CommonMark specification. It adds tables, task lists (checkboxes), fenced code blocks with syntax highlighting, autolinks, strikethrough, and footnotes. GFM is also used by GitLab, Gitea, and many developer documentation platforms. It is the de facto standard for developer-facing documentation.

How do I add a line break in Markdown?

A single newline within a paragraph is treated as a space — the lines merge. To force a hard line break (a <br> tag), end the line with two or more spaces before pressing Enter. To start a new paragraph, leave a blank line between blocks of text. Some parsers also accept a backslash at the end of a line as a line break.

Can I use HTML inside Markdown?

Yes, in most contexts. Markdown processors generally pass raw HTML through to the output unchanged. This lets you use tags like <br>, <sup>, <sub>, <details>, and <summary> when Markdown alone isn't sufficient. Be aware that some platforms — including GitHub comments and many CMS tools — sanitize HTML for security, stripping tags they don't whitelist.

What tools render Markdown?

Markdown is rendered by VS Code (built-in Markdown preview with Ctrl+Shift+V), GitHub and GitLab README files and comments, Notion, Obsidian, Bear, static site generators like Jekyll, Hugo, Gatsby, and Eleventy, blogging platforms like Ghost, Reddit, Stack Overflow, Discord, and Jupyter notebooks. You can also use the SnapUtils Markdown Previewer to render any Markdown snippet instantly in your browser.