How to Use Markdown (Complete Syntax Reference)

Markdown is a lightweight text formatting language that converts plain text into structured HTML. Created by John Gruber in 2004, it has become the default writing format for developers, technical writers, and content creators across the web. GitHub READMEs, documentation sites, blogs, forums, note-taking apps, and chat platforms all use Markdown.

The syntax is designed so the plain text version is readable on its own, even without rendering. This guide covers every major Markdown element with examples you can copy and use. To convert Markdown to HTML or HTML back to Markdown, use our Markdown to HTML Converter or HTML to Markdown Converter.

Headings

Headings use the # symbol. The number of symbols indicates the heading level.

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

Rules:

• Put a space between # and the text
• Leave a blank line before and after the heading
• Only use one H1 per document (for SEO and accessibility)
• Don’t skip levels (go from H2 to H3, not H2 to H4)

Text Formatting

Bold and Italic

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~

Rendered:

• bold text
• italic text
• bold and italic
• strikethrough

You can use underscores instead of asterisks (_italic_ and __bold__), but asterisks are more common and work mid-word (un**frigging**believable), while underscores don’t (un__frigging__believable may not render correctly).

Line Breaks

Markdown doesn’t treat a single newline as a line break. Two consecutive newlines create a new paragraph. For a line break within a paragraph, use one of these methods:

Line one with two trailing spaces
Line two (soft break)

Line one with a blank line below

Line two (new paragraph)

The trailing-spaces method is invisible and easy to lose in editors that trim whitespace. Many writers prefer using a <br> tag instead for clarity.

Links and Images

Links

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

The first creates a standard hyperlink. The second adds hover text. The third auto-links a bare URL. Reference-style links keep your text clean when using the same URL multiple times:

Read the [documentation][docs] or check the [changelog][docs].

[docs]: https://example.com/docs "Documentation"

Images

Images use the same syntax as links with an ! prefix:

![Alt text](image.png)
![Screenshot of the dashboard](./images/dashboard.png "Dashboard")

The alt text inside brackets describes the image for screen readers and displays when the image fails to load. Always write meaningful alt text.

Markdown doesn’t support image sizing natively. Use HTML for dimensions:

<img src="image.png" alt="Alt text" width="400">

Lists

Unordered Lists

- Item one
- Item two
  - Nested item
  - Another nested item
- Item three

You can use -, *, or + for bullets. Pick one and be consistent within a document.

Ordered Lists

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

The actual numbers don’t matter for rendering. Markdown auto-numbers them. However, starting with 1. for each item helps readability in the source and prevents confusion during editing.

Task Lists

GitHub-flavored Markdown supports checkboxes:

- [x] Write the introduction
- [x] Add code examples
- [ ] Review for errors
- [ ] Publish

Task lists render as interactive checkboxes on GitHub and many other platforms.

Code

Inline Code

Wrap short code references in backticks:

Use the `console.log()` function to debug.

Rendered: Use the console.log() function to debug.

Code Blocks

For multi-line code, use triple backticks with an optional language identifier for syntax highlighting:

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

Supported language identifiers include javascript, python, bash, html, css, json, yaml, sql, go, rust, java, typescript, ruby, php, c, cpp, and many more. The exact set depends on the renderer.

Indented code blocks (4 spaces or 1 tab) also work but don’t support syntax highlighting:

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

Fenced blocks with backticks are preferred over indented blocks because they support language specification and are less error-prone when adjacent to lists.

Tables

| Name   | Role       | Location  |
| :----- | :--------: | --------: |
| Alice  | Engineer   | Portland  |
| Bob    | Designer   | Seattle   |
| Carol  | Manager    | Denver    |

Column alignment:

• :--- left-aligned (default)
• :---: centered
• ---: right-aligned

The outer pipes and alignment of columns are optional but improve readability in the source. This minimal version also works:

Name | Role | Location
--- | --- | ---
Alice | Engineer | Portland

Tables in Markdown are limited to simple grids. For merged cells, spanning rows, or complex layouts, use HTML tables.

Blockquotes

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > Nested blockquotes work too.

Blockquotes are commonly used for:

• Quoting external sources
• Callout boxes in documentation
• Highlighting important notes

Horizontal Rules

Three or more hyphens, asterisks, or underscores on their own line:

---
***
___

All three produce the same horizontal line. Use them to separate sections visually.

Where Markdown Is Used

GitHub and GitLab: README files, pull request descriptions, issue comments, and wiki pages all render Markdown. GitHub-Flavored Markdown (GFM) adds features like task lists, tables, and autolinked URLs.

Documentation sites: Tools like MkDocs, Docusaurus, VitePress, and Jekyll convert Markdown files into full documentation websites. Write content in .md files and the framework handles navigation, search, and styling.

Blogs and CMS platforms: Static site generators (Hugo, Eleventy, Astro) use Markdown for blog posts. WordPress and Ghost also support Markdown editing.

Note-taking apps: Obsidian, Notion, Bear, and Typora use Markdown as their native format. Your notes are portable plain text files, not locked into a proprietary format.

Chat and forums: Slack, Discord, Reddit, and Stack Overflow all support subsets of Markdown for message formatting.

Technical writing: API documentation, internal wikis, runbooks, and architecture decision records are commonly written in Markdown for version control compatibility.

Converting Markdown to HTML

Every Markdown document maps to HTML elements:

Markdown	HTML
# Heading	<h1>Heading</h1>
**bold**	<strong>bold</strong>
*italic*	<em>italic</em>
[text](url)	<a href="url">text</a>
	<img src="src" alt="alt">
`code`	<code>code</code>
> quote	<blockquote>quote</blockquote>
- item	<ul><li>item</li></ul>

The conversion is deterministic: the same Markdown always produces the same HTML structure. Different renderers may vary in whitespace or attribute ordering, but the semantic output is identical.

Common Formatting Pitfalls

Forgetting blank lines. A heading, list, or code block immediately after a paragraph may not render correctly. Always add a blank line before and after block-level elements.

Inconsistent list markers. Mixing -, *, and + in the same list can confuse some parsers. Pick one marker and stick with it.

Trailing spaces. Some editors strip trailing whitespace, which breaks the two-space line break syntax. Use explicit <br> tags or blank lines instead.

Special characters in URLs. Parentheses in URLs break link syntax: [link](https://example.com/page_(1)) fails. Use URL encoding: [link](https://example.com/page_%281%29).

Nested lists. Inconsistent indentation in nested lists is the most common source of broken rendering. Use exactly 2 or 4 spaces per level and be precise.

Convert Markdown Now

Our Markdown to HTML Converter renders any Markdown text to clean HTML with live preview. Need to go the other direction? The HTML to Markdown Converter converts HTML pages back to Markdown, preserving headings, links, lists, and formatting.

Frequently Asked Questions

What is the difference between Markdown and HTML?

Markdown is a shorthand syntax that converts to HTML. HTML is the actual markup language browsers render. Markdown is faster to write and easier to read in plain text, but HTML offers full control over every element, attribute, and style. When Markdown’s syntax is too limited (e.g., custom classes, complex tables, embedded forms), you can drop in raw HTML and most renderers will pass it through unchanged.

Which Markdown flavor should I use?

CommonMark is the standardized specification and the safest choice for broad compatibility. GitHub-Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, and autolinks. If you write primarily for GitHub, use GFM. For documentation sites, check which flavor your static site generator supports. When in doubt, stick to CommonMark features since they work everywhere.

Can I use Markdown in emails?

Most email clients don’t render Markdown natively. However, you can write in Markdown and convert it to HTML before pasting it into your email. Some tools like Markdown Here (a browser extension) automate this process. The converted HTML uses inline styles that email clients can display correctly.

How do I create a table of contents in Markdown?

Markdown has no built-in table of contents feature. You create one manually using links to heading anchors. Most renderers auto-generate IDs from heading text: ## My Section becomes #my-section. Link to it with [My Section](#my-section). Documentation generators like MkDocs and Docusaurus can auto-generate a table of contents from your heading structure.

Is there a way to add footnotes in Markdown?

Standard Markdown doesn’t include footnotes, but several extended flavors support them. The common syntax is: Text with a footnote[^1] and then [^1]: This is the footnote content. at the bottom of the document. GitHub-Flavored Markdown, PHP Markdown Extra, and Pandoc all support this syntax. If your renderer doesn’t support footnotes, use parenthetical references or endnotes as plain text.