What Is Markdown?

Markdown was created by John Gruber in 2004 with the goal of allowing people to write using a plain-text format that could then be converted to HTML. The key insight was that formatting conventions already used in plain-text email — asterisks around words to indicate bold, greater-than signs for quotations — could be formalised into a parser.

The original Markdown specification is available on John Gruber's Daring Fireball website. Because the original spec left some edge cases ambiguous, the community developed CommonMark — a strict, unambiguous Markdown specification with a comprehensive test suite.

GitHub Flavored Markdown (GFM) extends CommonMark with tables, strikethrough, task lists, and autolinks. GFM is what GitHub uses for READMEs, issues, pull request descriptions, and wiki pages.

Quick tip: Markdown files use the .md extension. To write and preview Markdown instantly without installing anything, use the ToolMasta Markdown Preview tool — it renders your Markdown live as you type.

Headings

Headings are created with hash symbols (#). The number of hashes determines the heading level, corresponding to H1 through H6 in HTML.

# Heading 1      (HTML: <h1>)
## Heading 2     (HTML: <h2>)
### Heading 3    (HTML: <h3>)
#### Heading 4   (HTML: <h4>)
##### Heading 5  (HTML: <h5>)
###### Heading 6 (HTML: <h6>)

An alternative syntax for H1 and H2 uses underlines (setext style):

Heading 1
=========

Heading 2
---------

The hash style (ATX headings) is more universally supported and is the preferred modern approach. Always leave a space between the hash(es) and the heading text — some parsers require it per the CommonMark specification.

Bold, Italic, and Strikethrough

Emphasis is applied using asterisks (*) or underscores (_). Asterisks are recommended because underscores within words can behave unexpectedly in some parsers.

**bold text**            → <strong>bold text</strong>
*italic text*            → <em>italic text</em>
__bold with underscores__
_italic with underscores_
***bold and italic***    → <strong><em>bold and italic</em></strong>
~~strikethrough~~        → <del>strikethrough</del> (GFM only)
Note: Strikethrough (~~text~~) is a GitHub Flavored Markdown extension. It is not part of the CommonMark specification and will not render in all Markdown processors — check your target platform.

Blockquotes

Blockquotes are created by prefixing lines with a greater-than sign (>). They can be nested and can contain other Markdown elements.

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

> Outer quote
>> Nested quote (indented further)

> ### Blockquote with heading
> You can include **bold** and *italic* text, lists, and code inside blockquotes.

Ordered and Unordered Lists

Unordered Lists

Use a hyphen (-), asterisk (*), or plus (+) followed by a space. All three are interchangeable, but mixing them within the same list is allowed by CommonMark and can be used intentionally or avoided for consistency.

- First item
- Second item
  - Nested item (indent with 2 spaces)
  - Another nested item
- Third item

Ordered Lists

Use numbers followed by a period (1.). The actual numbers do not need to be sequential — most processors renumber them automatically. However, the list must start with 1 in some processors.

1. First item
2. Second item
3. Third item
   1. Nested ordered item
   2. Another nested item

Task Lists (GFM)

GitHub Flavored Markdown supports checkboxes in lists using [ ] (unchecked) and [x] (checked):

- [x] Completed task
- [ ] Incomplete task
- [x] Another completed task

Inline Code and Code Blocks

Inline Code

Wrap code in single backticks for inline code formatting:

Use the `console.log()` function to debug.
Run `npm install` to install dependencies.

Fenced Code Blocks

Use triple backticks (```) or triple tildes (~~~) to create code blocks. Optionally specify a language immediately after the opening fence for syntax highlighting:

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

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

```sql
SELECT * FROM users WHERE active = 1;
```

The language identifier after the opening fence is used by syntax highlighters like Prism.js and highlight.js. Common identifiers include: javascript, typescript, python, bash, sql, json, html, css, yaml.

Indented Code Blocks

The original Markdown spec also recognises code blocks created by indenting lines with four spaces or one tab. Fenced code blocks are preferred in modern usage as they support language identifiers and are less prone to accidental triggering.

Inline Links

[Link text](https://example.com)
[Link with title](https://example.com "Optional title shown on hover")

Reference Links

Reference links separate the URL from the link text, keeping the body of the document readable:

[Link text][reference-id]

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

Autolinks

URLs and email addresses wrapped in angle brackets are automatically linked:

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

In GFM, bare URLs like https://example.com are autolinked without angle brackets.

Images

Image syntax is identical to link syntax but prefixed with an exclamation mark (!). The text in square brackets becomes the alt attribute:

![Alt text](image.png)
![Alt text](https://example.com/image.png "Optional title")


![Alt text][image-ref]
[image-ref]: image.png "Optional title"

Markdown does not support specifying image dimensions natively. To set width or height, use inline HTML: <img src="image.png" alt="Alt text" width="400">.

Tables (GFM)

Tables are a GitHub Flavored Markdown extension. Use pipes (|) to separate columns and hyphens to create the header separator row. Column alignment is controlled by colons in the separator row:

| Left       | Centre     | Right      |
| :--------- | :--------: | ---------: |
| Cell 1     | Cell 2     | Cell 3     |
| Longer cell| Short      | 42         |

The colon in :--- aligns left, :---: aligns centre, ---: aligns right. Cells do not need to be padded with spaces to align — the markdown source does not need to be visually aligned for tables to render correctly.

Horizontal Rules

A horizontal rule (<hr>) is created using three or more hyphens, asterisks, or underscores on a line by themselves:

---
***
___

Leave a blank line before and after to avoid accidentally triggering a setext heading (where a line of hyphens after text creates an H2).

HTML in Markdown

Most Markdown processors pass raw HTML through to the output. This allows using HTML elements that Markdown cannot express natively:

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

Text with <sub>subscript</sub> and <sup>superscript</sup>.

<span style="color: red;">Red text</span>

Be aware that some platforms sanitise HTML in Markdown for security reasons. GitHub allows a limited subset of HTML in Markdown; platforms like Reddit strip all HTML. Check your target platform's policy before relying on inline HTML.

Escaping Characters

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

\*Not italic\*     → displays literal asterisks
\# Not a heading  → displays literal hash
\[Not a link\]    → displays literal brackets
\`Not code\`      → displays literal backtick

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

To write and preview all of these elements live, use the ToolMasta Markdown Preview tool. For a deeper look at when to choose Markdown vs HTML for your project, read our guide on Markdown vs HTML.

Try It Free — No Signup Required

Write Markdown in the left panel and see the rendered HTML output in real time on the right. Supports all CommonMark and GFM syntax including tables, task lists, and fenced code blocks.

Open Markdown Preview