Markdown Syntax Cheat Sheet: A Complete Reference

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. Its design philosophy is simple: a Markdown-formatted document should be publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions. The syntax is intentionally minimal, using characters like asterisks, hashes, and brackets that visually suggest the formatting they produce.

When processed by a Markdown parser, the plain text is converted into valid HTML. For example, text surrounded by double asterisks (**bold**) becomes <strong>bold</strong>. This makes Markdown ideal for content that needs to be readable in both its source and rendered forms.

Since 2004, Markdown has evolved through community efforts. The CommonMark specification (2014) standardized the language's ambiguities, and GitHub Flavored Markdown (GFM) added popular extensions like tables, task lists, and fenced code blocks. Today, Markdown is supported by platforms including GitHub, GitLab, Reddit, Stack Overflow, Notion, Obsidian, Hugo, Jekyll, Astro, and thousands of other tools.

Headings

Headings are created by prefixing the line with hash characters (#). The number of hashes corresponds to the heading level, from H1 (one hash) through H6 (six hashes):

• # Heading 1 — renders as <h1>
• ## Heading 2 — renders as <h2>
• ### Heading 3 — renders as <h3>
• #### Heading 4 — renders as <h4>
• ##### Heading 5 — renders as <h5>
• ###### Heading 6 — renders as <h6>

There must be a space between the hash characters and the heading text. Some parsers also support an alternative syntax for H1 and H2 using underlines with equals signs (===) and dashes (---), respectively, but the hash syntax is more widely used and recommended.

Best practice: Use heading levels sequentially (do not skip from H2 to H4) to maintain a logical document structure that is accessible to screen readers and search engines.

Text Emphasis

Markdown provides straightforward syntax for emphasizing text:

• *italic* or _italic_ — renders as italic (<em>)
• **bold** or __bold__ — renders as bold (<strong>)
• ***bold italic*** or ___bold italic___ — renders as bold italic
• ~~strikethrough~~ — renders as strikethrough text (GFM extension)

The asterisk syntax (* and **) is generally preferred over underscores because it works consistently in the middle of words. For example, un*frigging*believable renders correctly with asterisks, but un_frigging_believable may not be parsed as emphasis in all processors.

Paragraphs and Line Breaks

Paragraphs are separated by one or more blank lines. Simply pressing Enter once does not create a new paragraph in most Markdown processors — the text continues on the same line when rendered.

To create a line break within a paragraph (a <br> tag), end the line with two or more trailing spaces before pressing Enter. Alternatively, some parsers support a backslash (\) at the end of the line for the same effect. The trailing-spaces method is the original Markdown convention, but it can be invisible and confusing, so many style guides prefer the backslash approach or the use of HTML <br> tags.

Lists

Unordered Lists

Create unordered (bulleted) lists by starting each line with a dash (-), asterisk (*), or plus sign (+):

• - First item
• - Second item
• - Third item

For consistency, choose one marker style and stick with it throughout your document. Dashes are the most common convention.

Ordered Lists

Create ordered (numbered) lists by starting each line with a number followed by a period:

• 1. First item
• 2. Second item
• 3. Third item

Interestingly, the actual numbers do not matter — Markdown will render a sequential numbered list regardless. You can even write 1. for every item, and the rendered output will still be numbered 1, 2, 3. However, using the correct numbers makes the source text more readable.

Nested Lists

Indent list items by two or four spaces (depending on the parser) to create nested lists:

• - Parent item
•   - Child item
•     - Grandchild item

You can mix ordered and unordered lists within nested structures.

Task Lists (GFM)

GitHub Flavored Markdown supports task lists (checkboxes):

• - [x] Completed task
• - [ ] Incomplete task

On GitHub, these render as interactive checkboxes that collaborators can check and uncheck directly in issues and pull requests.

Links

Markdown supports several link formats:

Inline Links

[Link text](https://example.com) — the most common format. You can add an optional title attribute: [Link text](https://example.com "Title text")

Reference Links

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

• [Link text][reference-id] — in the text
• [reference-id]: https://example.com "Optional title" — at the bottom of the document

Automatic Links

Wrapping a URL in angle brackets creates an automatic link: <https://example.com>. In GFM, bare URLs are also auto-linked without angle brackets.

Email Links

<email@example.com> creates a clickable email link. Some parsers apply basic encoding to help reduce spam harvesting.

Images

Image syntax is identical to link syntax but prefixed with an exclamation mark:

![Alt text](image-url.jpg)

With an optional title: ![Alt text](image-url.jpg "Image title")

Reference-style images work the same way: ![Alt text][image-id] with the reference defined elsewhere in the document.

Markdown does not natively support image sizing or alignment. For more control, you can use raw HTML: <img src="image.jpg" alt="Alt text" width="400">. Many extended Markdown parsers also support custom syntax for image dimensions.

Code

Inline Code

Wrap text in backticks for inline code: `const x = 42;` renders as const x = 42;

If your code contains backticks, use double backticks as the delimiter: ``code with a ` backtick``

Code Blocks (Indented)

Indent every line of the block by four spaces or one tab to create a code block. This is the original Markdown syntax for code blocks but has largely been superseded by fenced code blocks.

Fenced Code Blocks (GFM)

Wrap code in triple backticks (```) for fenced code blocks. Add a language identifier after the opening backticks for syntax highlighting:

```javascript

function greet(name) {

  return `Hello, $${name}!`;

}

```

Common language identifiers include javascript, python, html, css, bash, json, sql, typescript, java, go, rust, and c. The supported languages depend on the syntax highlighting library used by the platform.

Blockquotes

Prefix lines with a greater-than sign (>) to create blockquotes:

> This is a blockquote.

>

> It can span multiple paragraphs.

Blockquotes can be nested by adding additional > characters:

> Outer quote

>> Nested quote

You can include other Markdown elements inside blockquotes, including headings, lists, and code blocks.

Horizontal Rules

Create a horizontal rule (thematic break) with three or more hyphens, asterisks, or underscores on a line by themselves:

• --- (hyphens)
• *** (asterisks)
• ___ (underscores)

These all render as an <hr> element. Hyphens are the most common convention. Be careful with hyphens — if the preceding line contains text, the hyphens may be interpreted as an H2 heading underline instead of a horizontal rule. Adding a blank line before the rule avoids this ambiguity.

Tables (GFM)

Tables are a GitHub Flavored Markdown extension. They use pipes (|) and hyphens (-):

| Header 1 | Header 2 | Header 3 |

|----------|----------|----------|

| Cell 1 | Cell 2 | Cell 3 |

| Cell 4 | Cell 5 | Cell 6 |

You can control column alignment with colons in the separator row:

• :--- — left-aligned (default)
• :---: — center-aligned
• ---: — right-aligned

The outer pipes are optional in most parsers, and the columns do not need to be perfectly aligned in the source — the parser handles that. However, aligning them makes the source much more readable.

Escaping Characters

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

• \* — literal asterisk
• \# — literal hash
• \[ — literal square bracket
• \| — literal pipe
• \\ — literal backslash

This is essential when your text naturally contains characters that have special meaning in Markdown.

HTML in Markdown

One of Markdown's most powerful features is that you can freely mix HTML into your document. Any block-level HTML element (like <div>, <table>, or <details>) can be included directly. The only requirement is that block-level HTML must be separated from surrounding Markdown content by blank lines.

This is useful for features that Markdown does not support natively, such as:

• Collapsible sections using <details> and <summary>
• Custom styling with <div> and class attributes
• Complex table layouts
• Embedded media with <video> or <iframe>

Note that Markdown formatting is not processed inside block-level HTML elements. Inside inline HTML elements (like <span>), Markdown may or may not be processed depending on the parser.

Common Use Cases for Markdown

GitHub READMEs and Documentation

Markdown is the default format for README files on GitHub, GitLab, and Bitbucket. A well-structured README with headings, badges, code examples, and tables makes your project approachable and professional. GitHub also renders Markdown in issues, pull requests, discussions, and wiki pages.

Static Site Generators

Static site generators like Hugo, Jekyll, Gatsby, Astro, and Eleventy use Markdown as the primary content format. You write your content in Markdown files with YAML front matter, and the generator converts them into a full website. This is popular for blogs, documentation sites, and personal portfolios.

Note-Taking

Applications like Obsidian, Notion, Bear, and Joplin use Markdown as their native format. Because Markdown files are plain text, your notes are future-proof — you can open them in any text editor decades from now, regardless of which application originally created them.

Technical Writing and Documentation

Tools like MkDocs, Docusaurus, and Read the Docs build beautiful documentation websites from Markdown source files. Technical writers benefit from Markdown's simplicity and the ability to version-control documentation alongside code using Git.

Email Composition

While email clients do not natively support Markdown, tools and browser extensions let you compose in Markdown and convert to formatted HTML before sending. This is faster than wrestling with rich-text editors for technical emails.

Tips for Writing Better Markdown

1. Use a consistent style. Choose one convention for lists (dashes vs. asterisks), emphasis (asterisks vs. underscores), and headings (ATX vs. Setext) and stick with it.
2. Add blank lines generously. Blank lines between different elements (headings, paragraphs, lists, code blocks) improve readability in both source and rendered form.
3. Use reference links for long URLs. Reference-style links keep your text readable when URLs are long or appear multiple times.
4. Preview before publishing. Use our Markdown Preview tool to check how your document renders before committing or publishing.
5. Use linting tools. Tools like markdownlint enforce consistent style rules and catch common mistakes.
6. Write meaningful alt text for images. The alt text in ![Alt text](image.jpg) is important for accessibility and SEO.