Markdown Syntax: The Complete Cheat Sheet for Developers

What Is Markdown and Why Should You Learn It?

Markdown is a lightweight markup language that lets you format text using simple, readable syntax. Created by John Gruber and Aaron Swartz in 2004, it was designed so that the source text looks natural even before conversion to HTML.

Today, Markdown is everywhere. GitHub uses it for README files and issue comments. Slack, Discord, and Reddit use Markdown for message formatting. Static site generators like Jekyll, Hugo, and Gatsby render Markdown into web pages. Note-taking apps like Notion, Obsidian, and Bear are built on Markdown. Learning Markdown syntax is one of the highest-leverage skills for any developer or technical writer.

Headings

Headings use the hash symbol (#). The number of hashes determines the heading level, from <h1> through <h6>:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Always put a space after the hash. Most style guides recommend using only one H1 per document (the title), then H2 for major sections and H3 for subsections.

Text Formatting

Markdown provides several ways to emphasize and format text:

You can also use underscores (_italic_, __bold__), but asterisks are preferred because they work inside words: un**frigging**believable renders correctly, while un__frigging__believable may not.

Links and Images

Inline Links

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

Reference Links

Reference links keep URLs out of the text flow, making long documents cleaner:

Read the [official docs][docs] for more info.

[docs]: https://example.com/documentation

Images

Images use the same syntax as links, prefixed with an exclamation mark:

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

The alt text is critical for accessibility — screen readers use it to describe the image to visually impaired users. If your images need to be processed for the web, consider converting them to optimized formats and using proper minified HTML for the fastest delivery.

Lists

Unordered Lists

Use -, *, or + followed by a space:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered Lists

Use numbers followed by a period. The actual numbers do not matter — Markdown auto-numbers the output:

1. First step
2. Second step
3. Third step
   1. Sub-step A
   2. Sub-step B

Task Lists (GitHub Flavored Markdown)

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish

Task lists render as interactive checkboxes on GitHub, making them ideal for pull request checklists and project tracking in README files.

Code Blocks and Syntax Highlighting

Code formatting is one of Markdown's most powerful features for developers.

Inline Code

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

Fenced Code Blocks

Use triple backticks for multi-line code. Add the language name for syntax highlighting:

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

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

Our Markdown to HTML Converter uses highlight.js for syntax highlighting, supporting over 190 languages with beautiful color themes. The output is sanitized with DOMPurify to prevent XSS when embedding converted HTML in your pages.

Diff Blocks

Show additions and removals with the diff language identifier:

```diff
- const oldVar = "before";
+ const newVar = "after";
```

For comparing larger blocks of text, our Text Diff Checker provides a full side-by-side or unified diff view with character-level highlighting.

Blockquotes

Prefix lines with > to create blockquotes:

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

Blockquotes are commonly used for quoting other sources, callout boxes, and important notes in documentation.

Tables

Tables use pipes (|) and hyphens (-):

| Column 1 | Column 2 | Column 3 |
|----------|:--------:|---------:|
| Left     | Center   |    Right |
| aligned  | aligned  |  aligned |

Column alignment is controlled by colons in the separator row:

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

You do not need to align the pipes in the source — Markdown processors handle the formatting. But aligned pipes make the raw source more readable.

Horizontal Rules and Line Breaks

Create a horizontal rule (<hr>) with three or more hyphens, asterisks, or underscores on a separate line:

---
***
___

For line breaks within a paragraph, end the line with two or more spaces, or use a backslash (\) at the end of the line. An empty line creates a new paragraph.

Advanced Markdown Features

HTML in Markdown

Markdown allows inline HTML for features that Markdown does not natively support — like colored text, definition lists, or complex layouts:

This is <span style="color: red">red text</span> in Markdown.

<details>
<summary>Click to expand</summary>
Hidden content here.
</details>

When mixing HTML and Markdown, ensure your HTML output is minified for production. Our HTML Minifier strips unnecessary whitespace and comments while preserving your content structure.

Footnotes

This claim needs a source[^1].

[^1]: Source: https://example.com/research

Escape Characters

Use a backslash to display literal Markdown characters:

\*This is not italic\*
\# This is not a heading
\[This is not a link\]

Characters that can be escaped: \ ` * _ {} [] () # + - . ! |

Automatic Links

URLs wrapped in angle brackets are automatically converted to clickable links:

<https://example.com>
<email@example.com>

Most GitHub Flavored Markdown processors also auto-link bare URLs without angle brackets.

Converting Markdown to HTML

Markdown is a source format — it needs to be converted to HTML for web display. The conversion process parses the Markdown syntax and outputs equivalent HTML tags.

Common Markdown parsers include:

• marked.js — Fast JavaScript parser, supports GFM, used by our Markdown to HTML Converter.
• markdown-it — Pluggable JavaScript parser with extensive extension support.
• Python-Markdown — The standard Python library for Markdown processing.
• Pandoc — Universal document converter that handles Markdown plus dozens of other formats.
• CommonMark — A strict specification that resolves ambiguities in the original Markdown spec.

When converting Markdown for use in web applications, always sanitize the output to prevent XSS attacks. Our converter uses DOMPurify to strip potentially dangerous HTML while preserving safe formatting.

After converting Markdown to HTML, you need CSS to style the output. If you need to match specific patterns in your Markdown source, our Regex Tester can help you build and test patterns for custom preprocessing.

Quick Reference Table

Frequently Asked Questions

Conclusion

Markdown strikes a rare balance: it is simple enough to learn in ten minutes yet powerful enough to write entire books. The syntax is intuitive — **bold**, *italic*, # heading — and the output is clean, semantic HTML.

Bookmark this cheat sheet for quick reference, and when you need to convert Markdown to HTML, use our free Markdown to HTML Converter. It renders your Markdown in real time with syntax highlighting, sanitized output, and a live preview — entirely in your browser, with no data sent to any server.