Markdown Cheat Sheet: Complete Syntax Guide

· 12 min read

Table of Contents

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004 that revolutionized how we write for the web. It lets you format plain text using simple, intuitive syntax that's both human-readable and machine-parsable.

Unlike HTML, which requires verbose tags and closing elements, Markdown uses natural symbols like asterisks, hashes, and brackets. This makes writing faster and the source text readable even without rendering. A Markdown document looks clean and logical in its raw form, which is why it's become the universal standard for technical documentation.

The philosophy behind Markdown is simple: writing should be easy, and the syntax should be invisible. When you read a Markdown file, you're reading content first, markup second. This is fundamentally different from traditional markup languages where tags often obscure the actual content.

Where Markdown Is Used

Markdown has become ubiquitous across the tech ecosystem and beyond:

Need to convert your Markdown to HTML for web publishing? Try our Markdown to HTML converter for instant, accurate conversion.

Pro tip: Markdown files use the .md or .markdown extension. Most platforms recognize both, but .md is more common and concise.

Headings and Document Structure

Headings are the backbone of document structure in Markdown. They create hierarchy, improve readability, and help both humans and search engines understand your content organization.

Basic Heading Syntax

Markdown supports six levels of headings using hash symbols (#). The number of hashes determines the heading level:

# Heading 1 (H1)
## Heading 2 (H2)
### Heading 3 (H3)
#### Heading 4 (H4)
##### Heading 5 (H5)
###### Heading 6 (H6)

Each heading level has semantic meaning. H1 is your document title, H2s are major sections, H3s are subsections, and so on. This hierarchy is crucial for accessibility and SEO.

Alternative Syntax for H1 and H2

Markdown also supports an alternative "underline" syntax for H1 and H2 headings:

Heading 1
=========

Heading 2
---------

While this syntax is valid, the hash syntax is more common and supports all six heading levels. Most developers prefer the consistency of using hashes throughout their documents.

Heading Best Practices

Quick tip: Many Markdown parsers automatically generate anchor links from headings, converting "Getting Started" to #getting-started. This enables deep linking to specific sections.

Text Formatting and Emphasis

Markdown provides intuitive syntax for common text formatting needs. These formatting options work inline within paragraphs and can be combined for more complex styling.

Bold and Italic Text

Emphasis is created using asterisks or underscores:

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___

Both asterisks and underscores work identically, but asterisks are more common. Choose one style and stick with it for consistency. Many style guides recommend asterisks because they're easier to type and more visually distinct.

Strikethrough and Other Formatting

Additional formatting options include:

~~Strikethrough text~~
`Inline code`
==Highlighted text== (some parsers)
X^2^ (superscript, some parsers)
H~2~O (subscript, some parsers)

Note that highlighted text, superscript, and subscript are extensions not supported by all Markdown parsers. GitHub Flavored Markdown (GFM) supports strikethrough but not highlighting by default.

Blockquotes

Blockquotes are created using the greater-than symbol (>):

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

>> Nested blockquotes are also possible.
>> Just add more > symbols.

Blockquotes are perfect for citations, pull quotes, or highlighting important information. They can contain other Markdown formatting, including headings, lists, and code blocks.

Horizontal Rules

Create visual breaks in your content with horizontal rules:

---
***
___

All three syntaxes produce the same result. Use three or more hyphens, asterisks, or underscores on their own line. Most developers prefer hyphens (---) for clarity.

Escaping Special Characters

To display literal Markdown characters, escape them with a backslash:

\*Not italic\*
\# Not a heading
\[Not a link\]

This is essential when you need to show Markdown syntax itself, like in documentation or tutorials.

Pro tip: When writing about code or technical topics, use inline code formatting (`backticks`) for function names, variables, file paths, and commands. This improves readability and helps readers distinguish code from prose.

Links and images use similar syntax in Markdown, making them easy to remember and use. Both support inline and reference-style formats for different use cases.

Creating Links

The basic link syntax is straightforward:

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

The link text appears in square brackets, followed immediately by the URL in parentheses. The optional title attribute appears in quotes after the URL and displays on hover.

Reference-Style Links

For documents with many repeated links, reference-style links keep your content cleaner:

[Link text][reference-id]
[Another link][reference-id]

[reference-id]: https://example.com "Optional title"

This approach separates link definitions from content, making the source more readable. It's particularly useful in long documents or when the same URL appears multiple times.

Automatic Links

URLs and email addresses can be automatically converted to links:

<https://example.com>
<[email protected]>

Many Markdown parsers also auto-link bare URLs without angle brackets, but this behavior isn't universal. Using angle brackets ensures consistent behavior across platforms.

Adding Images

Image syntax is nearly identical to links, with an exclamation mark prefix:

![Alt text](image.jpg)
![Alt text](image.jpg "Image title")
![Alt text][image-reference]

[image-reference]: image.jpg "Optional title"

The alt text is crucial for accessibility and SEO. It describes the image for screen readers and appears if the image fails to load. Always provide meaningful alt text that describes the image content and context.

Image Sizing and Alignment

Standard Markdown doesn't support image sizing or alignment. You'll need to use HTML for these features:

<img src="image.jpg" alt="Alt text" width="300">
<img src="image.jpg" alt="Alt text" style="float:right;margin:10px">

Most Markdown parsers allow inline HTML, making this a practical solution when you need more control over image presentation.

Quick tip: When linking to internal pages, use relative URLs (/about/) instead of absolute URLs (https://example.com/about/). This makes your content portable and works correctly in development environments.

Lists: Ordered, Unordered, and Task Lists

Lists are fundamental to organizing information in Markdown. They're simple to create and support nesting for complex hierarchies.

Unordered Lists

Create bullet lists using asterisks, hyphens, or plus signs:

* Item one
* Item two
* Item three

- Item one
- Item two
- Item three

+ Item one
+ Item two
+ Item three

All three symbols work identically. Choose one and use it consistently throughout your document. Most developers prefer hyphens for their visual clarity.

Ordered Lists

Numbered lists use numbers followed by periods:

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

Here's a useful feature: the actual numbers don't matter. Markdown automatically renumbers your list when rendered:

1. First item
1. Second item
1. Third item

This makes reordering items easier since you don't need to renumber everything manually. However, starting with 1. for every item can be confusing when reading the source.

Nested Lists

Create hierarchical lists by indenting items with spaces or tabs:

1. First item
   - Nested bullet
   - Another nested bullet
2. Second item
   1. Nested number
   2. Another nested number
      - Even deeper nesting

Use consistent indentation (typically 2-4 spaces) for each nesting level. Most parsers are flexible, but consistency improves readability.

Task Lists

GitHub Flavored Markdown introduced task lists for tracking to-dos:

- [ ] Unchecked task
- [x] Checked task
- [ ] Another unchecked task

Task lists are interactive on platforms like GitHub—you can check and uncheck items directly in the rendered view. They're perfect for project planning, issue tracking, and collaborative documents.

List Best Practices

Code and Code Blocks

Markdown excels at displaying code, making it the preferred format for technical documentation and programming tutorials.

Inline Code

Wrap inline code with single backticks:

Use the `console.log()` function to debug.
The `<div>` element is a container.

Inline code formatting preserves spacing and prevents Markdown interpretation. It's essential for mentioning code elements within sentences.

Code Blocks

Create code blocks using triple backticks (fenced code blocks):

```
function hello() {
  console.log("Hello, world!");
}
```

This is the modern, preferred syntax. It's cleaner and more flexible than the older indentation method (4 spaces or 1 tab).

Syntax Highlighting

Specify the programming language after the opening backticks for syntax highlighting:

```javascript
function hello() {
  console.log("Hello, world!");
}
```

```python
def hello():
    print("Hello, world!")
```

```css
.container {
  max-width: 1200px;
  margin: 0 auto;
}
```

Most Markdown parsers support dozens of languages. Common identifiers include javascript, python, java, css, html, bash, sql, and json.

Indented Code Blocks

The older method uses 4-space or 1-tab indentation:

    function hello() {
      console.log("Hello, world!");
    }

While still valid, this method doesn't support syntax highlighting and can be ambiguous. Fenced code blocks are recommended for all new content.

Escaping Backticks in Code

To show backticks within inline code, use double backticks:

``Use `backticks` for inline code``

For code blocks containing triple backticks, use four backticks to wrap the block.

Pro tip: When sharing code snippets, always include the language identifier for syntax highlighting. It dramatically improves readability and helps readers understand the context immediately.

Tables and Data Presentation

Tables in Markdown provide a clean way to present structured data. While the syntax is more complex than other Markdown elements, it's still far simpler than HTML tables.

Basic Table Syntax

Create tables using pipes (|) and hyphens:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

The header row is separated from data rows by a line of hyphens. Each column is separated by pipe characters. The outer pipes are optional but improve readability.

Column Alignment

Control text alignment using colons in the separator row:

| Left aligned | Center aligned | Right aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| Text         | Text           | Text          |

Formatting Within Tables

Tables support inline Markdown formatting:

| Feature | Status | Notes |
|---------|--------|-------|
| **Bold** | *Italic* | `Code` |
| [Links](url) | ~~Strike~~ | Normal |

However, tables don't support block-level elements like paragraphs, lists, or headings within cells.

Practical Table Examples

Here's a comparison table showing Markdown syntax variations:

Element Markdown Syntax Alternative Syntax Notes
Bold **text** __text__ Asterisks more common
Italic *text* _text_ Both widely used
Heading 1 # Heading Heading\n======= Hash syntax preferred
Heading 2 ## Heading Heading\n------- Hash syntax preferred
Unordered List - item * item or + item Hyphen most common
Horizontal Rule --- *** or ___ Three or more symbols

And here's a feature compatibility table for different Markdown flavors:

Feature Standard Markdown GitHub Flavored CommonMark
Tables ❌ No ✅ Yes ❌ No
Task Lists ❌ No ✅ Yes ❌ No
Strikethrough ❌ No ✅ Yes ❌ No
Auto-linking Limited ✅ Yes ✅ Yes
Emoji ❌ No ✅ Yes ❌ No
Footnotes ❌ No ✅ Yes ❌ No

Quick tip: Don't worry about perfect column alignment in your source Markdown. Most editors and parsers handle spacing automatically. Focus on content accuracy over visual alignment.

Advanced Markdown Syntax

Beyond the basics, Markdown supports several advanced features that enhance functionality and expressiveness.

Footnotes

Add footnotes for citations and additional information:

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Footnotes automatically number themselves and create links between the reference and the note. They're perfect for academic writing, citations, and supplementary information.

Definition Lists

Some Markdown processors support definition lists:

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Definition lists are ideal for glossaries, terminology sections, and structured key-value content.

Abbreviations

Define abbreviations that show full text on hover:

The HTML specification is maintained by W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

This feature improves accessibility by providing context for acronyms and abbreviations.

Custom IDs and Classes

Some parsers allow custom attributes on headings:

## Heading {#custom-id}
## Heading {.custom-class}
## Heading {#custom-id .custom-class}

This enables precise linking and styling control, particularly useful for documentation sites and technical content.

Math Equations

Many Markdown processors support LaTeX-style math equations:

Inline math: $E = mc^2$

Block math:
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Math support is essential for scientific, academic, and technical documentation. It's commonly used in Jupyter Notebooks and academic publishing platforms.

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown extends standard Markdown with features specifically designed for software development and collaboration.

What Makes GFM Different

GFM adds several practical features that have become widely adopted:

Syntax Highlighting

GFM supports extensive syntax highlighting for code blocks. Specify the language for automatic highlighting:

```ruby
def hello
  puts "Hello, world!"
end
```

GitHub supports over 200 programming languages and file formats, making it ideal for technical documentation.

Emoji Support

Add emoji using shortcodes:

:smile: :rocket: :tada: :+1:

Emoji can make documentation more engaging and help convey tone. However, use them sparingly in professional documentation to maintain credibility.

Username and Issue Mentions

GFM automatically links mentions and references:

@username will be notified
#123 links to issue 123
GH-123 also links to issue 123
username/repo#123 links to another repo's issue

These features streamline collaboration and make it easy to reference related work.

Commit SHA References

Reference commits by their SHA hash:

16c999e8c71134401a78d4d46435517b2271d6ac
mojombo@16c999e8c71134401a78d4d46435517b2271d6ac
mojombo/github-flavored-markdown@16c999e8c71134401a78d4d46435517b2271d6ac

GitHub automatically converts these to clickable links to the commit details.

Pro tip: When writing documentation for GitHub repositories, use GFM features liberally. They're designed specifically for software collaboration and are well-supported across the platform.

Best Practices and Common Pitfalls

Writing effective Markdown requires understanding both the syntax and the conventions that make documents maintainable and readable.

Consistency Is Key

Choose one style for each element and stick with it:

Consistency makes your source Markdown easier to read and edit, especially in collaborative environments.

Whitespace Matters

Proper whitespace improves both source readability and parsing reliability:

Line Length and Wrapping

Consider line length for better version control and collaboration:

Common Mistakes to Avoid

Accessibility Considerations

Write Markdown with accessibility in mind:

We use cookies for analytics. By continuing, you agree to our Privacy Policy.