Markdown Cheat Sheet: Complete Syntax Guide

What Is Markdown and Why Use It?

Markdown is a lightweight markup language created by John Gruber in 2004 that lets you write formatted text using plain text syntax. Instead of clicking toolbar buttons or writing HTML tags, you use simple characters like # for headings, ** for bold, and - for lists. The syntax is designed to be readable even as raw text.

Markdown has become the standard for developer documentation, README files, blog posts, technical writing, and note-taking. It is used on GitHub, GitLab, Stack Overflow, Reddit, Notion, Obsidian, Jupyter notebooks, and thousands of other platforms. Learning Markdown is one of the highest-leverage skills a developer can acquire.

To practice and preview Markdown as you type, use our Markdown Preview tool. It renders your Markdown in real time, entirely in your browser.

Headings

Use hash symbols (#) to create headings. The number of hashes determines the heading level (1-6). Always leave a space between the hash and the heading text. Good practice is to use only one H1 per document.

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

<!-- Alternative syntax for H1 and H2 -->
Heading 1
=========

Heading 2
---------

Text Formatting (Emphasis)

*Italic text* or _italic text_
**Bold text** or __bold text__
***Bold and italic*** or ___bold and italic___
~~Strikethrough text~~ (GFM extension)
==Highlighted text== (some parsers)

<!-- Inline code -->
Use the `console.log()` function.

<!-- Subscript / Superscript (some parsers) -->
H~2~O (subscript)
X^2^ (superscript)

Prefer * for italic and ** for bold. The underscore variants can cause issues mid-word (e.g., file_name_here might be parsed as italic in some renderers). Strikethrough with ~~ is a GitHub Flavored Markdown (GFM) extension supported on most platforms.

Links and Images

<!-- Inline link -->
[BytePane](https://bytepane.com/)
[BytePane](https://bytepane.com/ "Developer Tools")  <!-- with title -->

<!-- Reference-style link -->
[BytePane][1]
[1]: https://bytepane.com/ "Developer Tools"

<!-- Autolink (GFM) -->
https://bytepane.com/  <!-- automatically becomes a link -->

<!-- Image -->
![Alt text](image.png)
![Alt text](image.png "Optional title")

<!-- Linked image -->
[![Alt text](image.png)](https://bytepane.com/)

<!-- Image with reference -->
![Logo][logo]
[logo]: /images/logo.png "BytePane Logo"

Always include descriptive alt text for images -- it improves accessibility and SEO. Reference-style links are useful in documents with many URLs because they keep the body text clean and make link management easier. If your URLs contain special characters, remember to URL-encode them.

Lists

<!-- Unordered list (use -, *, or +) -->
- Item 1
- Item 2
  - Nested item 2a
  - Nested item 2b
    - Deeply nested
- Item 3

<!-- Ordered list -->
1. First item
2. Second item
3. Third item
   1. Sub-item 3a
   2. Sub-item 3b

<!-- The actual numbers don't matter in most parsers -->
1. First
1. Second (still renders as 2)
1. Third (still renders as 3)

<!-- Task list / Checkbox (GFM) -->
- [x] Write the article
- [x] Add code examples
- [ ] Review and publish
- [ ] Promote on social media

<!-- Definition list (some parsers) -->
Term
: Definition of the term

Nest list items by indenting with 2 or 4 spaces (depending on the parser). Task lists with checkboxes are a GFM extension and are widely used in GitHub issues, pull request descriptions, and project management. For numbered lists, using 1. for every item makes reordering easier since you do not need to renumber.

Code Blocks and Syntax Highlighting

Inline code uses single backticks. Code blocks use triple backticks (fenced code blocks) or 4-space indentation. Fenced code blocks support syntax highlighting by specifying the language after the opening backticks.

<!-- Inline code -->
Run `npm install` to install dependencies.

<!-- Fenced code block with syntax highlighting -->
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

```json
{
  "name": "BytePane",
  "tools": 50,
  "free": true
}
```

<!-- Indented code block (4 spaces) -->
    function oldStyle() {
        return "no syntax highlighting";
    }

<!-- Diff syntax highlighting -->
```diff
- const old = "removed line";
+ const new = "added line";
```

Popular language identifiers include: javascript, typescript, python, bash, json, html, css, sql, yaml, go, rust, diff. For JSON-specific formatting, our JSON Formatter provides more features than basic code blocks. Compare code differences with our Diff Checker.

Tables

Tables are a GFM extension. Use pipes (|) to separate columns and hyphens (-) to create the header separator. Control alignment with colons in the separator row.

<!-- Basic table -->
| Tool | Category | Link |
| --- | --- | --- |
| JSON Formatter | Data | [Open](/json-formatter/) |
| Regex Tester | Text | [Open](/regex-tester/) |
| Color Converter | Design | [Open](/color-converter/) |

<!-- Aligned columns -->
| Left-aligned | Center-aligned | Right-aligned |
| :--- | :---: | ---: |
| Text | Text | Text |
| More text | More text | $99.99 |

<!-- Formatting inside table cells -->
| Feature | Supported |
| --- | --- |
| **Bold** text | Yes |
| `inline code` | Yes |
| [Links](/) | Yes |
| Images | Yes |
| Lists | No |
| Nested tables | No |

Tables do not need to be perfectly aligned in the source -- most renderers normalize the spacing. For complex data, consider linking to a JSON representation instead. Our JSON Formatter can help format the data for embedding.

Blockquotes and Horizontal Rules

<!-- Blockquote -->
> This is a blockquote.
> It can span multiple lines.

> Nested blockquotes:
>> This is a nested quote.
>>> Three levels deep.

> **Tip:** You can use formatting inside blockquotes,
> including `code`, **bold**, and [links](/).

<!-- Horizontal rule (any of these work) -->
---
***
___

Blockquotes are commonly used for quoting external sources, callout boxes, and important notes. GitHub renders blockquotes with special styling when they start with keywords like [!NOTE], [!WARNING], or [!TIP].

<!-- GitHub Alert syntax -->
> [!NOTE]
> This is a note with special styling on GitHub.

> [!WARNING]
> This is a warning callout.

> [!TIP]
> This is a helpful tip.

> [!IMPORTANT]
> Critical information goes here.

> [!CAUTION]
> Proceed with care.

HTML in Markdown

Most Markdown parsers allow raw HTML for features that Markdown does not support natively. This is useful for collapsible sections, keyboard shortcuts, complex layouts, and custom styling.

<!-- Collapsible section -->
<details>
<summary>Click to expand</summary>

Hidden content goes here.
You can use **Markdown** inside HTML blocks.

</details>

<!-- Keyboard shortcuts -->
Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.

<!-- Centered text -->
<div align="center">
  <h3>Centered Heading</h3>
  <p>Centered paragraph text.</p>
</div>

<!-- Colored text (limited platform support) -->
<span style="color: #FF5733">Colored text</span>

<!-- Line break without a new paragraph -->
Line one<br>
Line two (same paragraph)

Be aware that HTML support varies across platforms. GitHub sanitizes HTML and removes <script> tags and event handlers. If you are writing HTML-heavy content, consider using our HTML Formatter to optimize the output.

Footnotes, Abbreviations, and Advanced Syntax

<!-- Footnotes (GFM and many parsers) -->
This claim needs a source[^1].
Another referenced fact[^note].

[^1]: Source: RFC 7231, Section 6.
[^note]: This is a longer footnote with multiple paragraphs.

    Indent continuation lines with 4 spaces.

<!-- Abbreviation (some parsers) -->
The HTML specification is maintained by the W3C.

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

<!-- Emoji (GFM) -->
:rocket: :fire: :thumbsup: :warning:

<!-- Table of Contents (auto-generated by some platforms) -->
[[toc]]
<!-- or -->
[TOC]

<!-- Escape special characters -->
\*Not italic\*
\# Not a heading
\[Not a link\]()

Footnotes are part of the GFM specification and are supported on GitHub, GitLab, and most static site generators. They automatically create numbered references at the bottom of the document with back-links. Emoji shortcodes are replaced with actual emoji characters on platforms that support them.

Markdown for README Files

A well-structured README is the front door to any open-source project. Here is a template that covers all the essential sections using the Markdown syntax from this guide.

# Project Name

![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-1.0.0-green)

> Brief description of the project in one or two sentences.

## Features

- Feature one with **bold** emphasis
- Feature two with `code` highlighting
- Feature three with [link to docs](/)

## Installation

```bash
npm install project-name
```

## Usage

```javascript
import { feature } from 'project-name';
feature.run();
```

## API Reference

| Method | Parameters | Returns |
| --- | --- | --- |
| `run()` | `options: Object` | `Promise<Result>` |
| `stop()` | none | `void` |

## Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

## License

MIT

Test your README rendering with our Markdown Preview tool before pushing to GitHub. You can also validate any JSON configuration files referenced in your project documentation.

Markdown Editors and Tools

For quick previews without installing anything, our Markdown Preview tool renders your Markdown in real time with GFM support. It is perfect for testing README files, documentation drafts, and blog posts before publishing.

Markdown Best Practices

1. Use ATX headings consistently -- Stick to # syntax rather than underline syntax. It is clearer, more widely supported, and easier to search.
2. Leave blank lines around blocks -- Put a blank line before and after headings, code blocks, lists, and blockquotes. This prevents parsing ambiguities across different Markdown engines.
3. Use fenced code blocks with language identifiers -- Always specify the language for syntax highlighting. It makes code dramatically more readable.
4. Keep lines under 120 characters -- While Markdown wraps automatically, shorter lines make diffs cleaner and the source easier to read in editors.
5. Use reference-style links for long documents -- They keep the body text clean and make link updates easier since each URL appears only once.
6. Always add alt text to images -- This improves accessibility, SEO, and provides context when images fail to load.
7. Test across renderers -- Different platforms parse Markdown slightly differently. Preview your content on the target platform before publishing. Use our Markdown Preview for quick testing.
8. Use a linter -- Tools like markdownlint enforce consistent style and catch common errors like duplicate headings, trailing spaces, and missing blank lines.

Frequently Asked Questions

What is the difference between Markdown and GitHub Flavored Markdown (GFM)?

Standard Markdown (CommonMark) defines the basic syntax for headings, paragraphs, links, images, emphasis, code, and blockquotes. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists (checkboxes), strikethrough text, autolinked URLs, syntax-highlighted fenced code blocks, and footnotes. GFM is used on GitHub, GitLab, and many documentation platforms.

How do I create a table in Markdown?

Use pipes (|) to separate columns and hyphens (-) to create the header row separator. For alignment, add colons: :--- for left-align, :---: for center, ---: for right-align. Tables are a GFM extension and are supported on most platforms including GitHub, GitLab, and many static site generators.

Can I use HTML inside Markdown?

Yes, most Markdown parsers allow inline HTML for features that Markdown does not support natively, such as <details> for collapsible sections, <kbd> for keyboard shortcuts, or complex table layouts. However, security-conscious platforms like GitHub sanitize HTML and remove script tags and event handlers. Raw HTML reduces portability across Markdown renderers.

Related Articles