Markdown Cheat Sheet: Complete Syntax Guide with Examples

Important: Always put a space between the # and the heading text. #Heading will not render correctly in many parsers. Also, most style guides recommend using only one H1 per document — treat it as your page title.

There is an alternative syntax for H1 and H2 using underlines:

Both styles produce identical output. The # syntax is more common because it works for all six levels and is easier to scan visually.

Text Formatting

Bold and Italic

Convention: use **asterisks** for bold and *asterisks* for italic. The underscore variants exist but can cause issues inside words (e.g., some_variable_name might accidentally italicize).

Strikethrough

Renders as: This text is crossed out

Subscript and Superscript

Some Markdown parsers support these (including GitHub):

Support varies — these work in some flavors but not all.

Paragraphs and Line Breaks

Paragraphs are separated by a blank line:

For a line break within a paragraph (without starting a new paragraph), end a line with two spaces or use <br>:

The two-trailing-spaces approach is invisible and easy to lose during editing. Many developers prefer the explicit <br> tag for clarity.

Lists

Unordered Lists

Use -, *, or + as bullet markers:

Renders as:

• Item one
• Item two
  • Nested item
  • Another nested item
    • Deeply nested
• Item three

Ordered Lists

A useful trick: Markdown does not care about the actual numbers. This is valid and renders as 1, 2, 3:

This is helpful when you frequently reorder items — no renumbering needed. Some style guides recommend using 1. for every item; others prefer sequential numbering for readability in raw form.

Mixed Lists

You can nest ordered lists inside unordered lists and vice versa:

Links

Inline Links

Reference Links

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

The reference definitions can go anywhere in the document — most people put them at the bottom.

Autolinks

Most Markdown parsers automatically convert URLs into clickable links:

You can also use angle brackets for explicit autolinks:

Images

Images use the same syntax as links, prefixed with !:

Always include alt text. It is essential for accessibility and good practice for SEO. The alt text should describe the image content for users who cannot see it.

Images with Links

Wrap the image syntax in a link:

Reference-Style Images

Code

Inline Code

Use single backticks for inline code:

Code Blocks

Use triple backticks (fenced code blocks) with an optional language identifier for syntax highlighting:

Common language identifiers: javascript, typescript, python, bash, html, css, json, sql, rust, go, java, c, cpp, markdown.

You can also create code blocks by indenting every line with four spaces:

The fenced style with language tags is strongly preferred — it enables syntax highlighting and is much easier to read in raw form.

Diff Syntax

Some parsers support diff highlighting:

This is great for showing code changes. If you need to compare longer texts, our Text Diff tool can generate visual diffs for you.

Blockquotes

Prefix lines with >:

Renders as:

This is a blockquote. It can span multiple lines.

And include multiple paragraphs.

Nested Blockquotes

Blockquotes with Other Elements

Blockquotes can contain any other Markdown elements:

Tables

Tables use pipes | and hyphens -:

Renders as:

Column Alignment

Use colons in the separator row:

The table does not need to look pretty in raw Markdown. This ugly version renders identically:

But readable raw formatting is considered good practice, especially in collaborative projects.

Horizontal Rules

Any of these create a horizontal line:

Use horizontal rules to create visual separation between sections. Three hyphens --- is the most common convention.

Task Lists

Task lists (checkboxes) are a GitHub-Flavored Markdown extension that is now widely supported:

Renders as:

• Write the introduction
• Add code examples
• Review for typos
• Publish the post

Task lists are incredibly useful in GitHub issues and pull request descriptions for tracking progress.

Footnotes

Footnotes let you add references without cluttering the main text:

Footnotes are rendered at the bottom of the document with automatic numbering and back-links. They are supported in GitHub-Flavored Markdown, Jekyll, Hugo, and most modern parsers.

Escaping Characters

To display a literal character that would otherwise be interpreted as Markdown formatting, prefix it with a backslash:

Characters you can escape: \ ` * _ { } [ ] ( ) # + - . ! |

HTML in Markdown

Markdown supports inline HTML for anything that Markdown syntax cannot handle:

Other useful HTML in Markdown:

Use HTML sparingly. The whole point of Markdown is readability in raw form — if your document is mostly HTML, you might as well write HTML.

GitHub-Flavored Markdown Extras

GitHub extends standard Markdown with several features that have become widely adopted.

Alerts / Admonitions

Emoji Shortcodes

Some platforms render these as emoji. On others, you can paste Unicode emoji directly: 🚀 ⭐ ✅ ⚠️

Automatic URL Linking

GitHub and most modern parsers automatically turn URLs into clickable links without any special syntax needed.

Mentioning Users and Issues

In GitHub specifically:

Advanced Patterns

Definition Lists

Supported by some parsers (PHP Markdown Extra, Pandoc):

Table of Contents

Many tools auto-generate a table of contents from headings. You can also create one manually:

The anchor links are auto-generated from heading text: lowercase, spaces replaced with hyphens, special characters removed.

Embedding Videos and Media

Standard Markdown has no video support, but you can use an image as a clickable thumbnail:

Or use HTML directly:

Quick Reference Table

Here is a compact reference you can scan quickly:

Which Markdown Flavor Should You Use

Not all Markdown is created equal. Here are the main variants:

CommonMark is the standardized specification. If you want maximum portability, write CommonMark.

GitHub-Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, and autolinks. It is the de facto standard for developer documentation.

MultiMarkdown adds footnotes, definition lists, math, and metadata. Popular in academic writing.

Pandoc Markdown is the Swiss Army knife — it supports practically everything and can convert between dozens of formats.

For most people, writing GFM-compatible Markdown covers 95% of use cases and renders correctly on GitHub, GitLab, VS Code, Notion, Obsidian, and almost every other tool.

Markdown Best Practices

Use blank lines generously. Separate every block element (headings, paragraphs, lists, code blocks) with blank lines. Some parsers require this; all parsers handle it correctly.

Be consistent with list markers. Pick - or * for unordered lists and stick with it throughout your document.

Use fenced code blocks over indented ones. The fenced style with language identifiers enables syntax highlighting and is unambiguous.

Use reference links for repeated URLs. If the same URL appears multiple times, define it once as a reference.

Write meaningful alt text for images. Screen readers depend on it. Search engines use it. Your future self will appreciate knowing what that image was supposed to show.

Keep lines under 80-120 characters in source files when possible. This makes diffs cleaner and the raw text easier to read. Many Markdown editors soft-wrap, but version control diffs work line by line.

Tools to Make Markdown Easier

Writing Markdown in a plain text editor is fine, but the right tools make it faster:

• Markdown Editor — Write Markdown with live preview, syntax highlighting, and export options. Great for drafting blog posts and documentation.
• HTML to Markdown — Convert existing web content into clean Markdown. Useful when migrating documentation or capturing content from websites.
• Markdown to HTML — Generate HTML from your Markdown for embedding in places that do not render Markdown natively.
• Text Diff — Compare two versions of a document to see exactly what changed, line by line.

Wrapping Up

Markdown is one of those rare tools that is simple enough to learn in five minutes and powerful enough to use for the rest of your career. The syntax is minimal by design — the goal is to write content that is readable both as source text and as rendered output.

You do not need to memorize every element in this guide. Bookmark it, come back when you need something specific, and over time the syntax will become muscle memory. Start with headings, bold, lists, links, and code blocks — those five elements handle 90% of what you will ever need.

The remaining 10% — tables, footnotes, task lists, HTML blocks — are there when you need them. And now you know exactly where to find them.