Markdown is basically a markup language used to create simple texts. It is widely used for project documentation, such as the well-known README.md files you see when visiting GitHub repositories.

With Markdown you can create headings, lists, tables, and code blocks, all in a standardized way. If Markdown's default options are not enough, you can also use HTML tags to enhance the text.

Created by John Gruber in 2004, it remains one of the most widely used markup languages. Markdown refers both to the plain-text formatting syntax and to the original Perl tool that converts it to HTML.

Markdown features

Below are the main Markdown features. Each example shows the syntax first, followed by the rendered result.

Text

Writing text is straightforward. To separate paragraphs, leave a blank line between them; a single line break is not enough.

Syntax:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Result:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Headings

Headings have six levels:

Syntax:

# Level 1 heading

## Level 2 heading

### Level 3 heading

#### Level 4 heading

##### Level 5 heading

###### Level 6 heading

Result:

Level 1 heading

Level 2 heading

Level 3 heading

Level 4 heading

Level 5 heading

Level 6 heading

Emphasis

Use two asterisks to make words and phrases bold.

Syntax:

An example of a **bold** word.

Result:

An example of a bold word.

Use one asterisk to make words and phrases italic.

Syntax:

An example of an *italic* word.

Result:

An example of an italic word.

Use three asterisks to make words and phrases bold and italic.

Syntax:

An example of ***bold and italic*** words.

An example of a word that is not \*\*bold\*\*.

An example of a word that is not \*italic\*.

Result:

An example of bold and italic words.

An example of a word that is not **bold**.

An example of a word that is not *italic*.

Put two tildes (~) on each side of text for strikethrough.

Syntax:

An example of ~~struck-through~~ text.

Result:

An example of struck-through text.

Use three hyphens on a line of their own to add a horizontal separator.

Syntax:

Text 01.

---

Text 02.

Result:

Text 01.

---

Text 02.

Lists

Create unordered lists with * (asterisks), + (plus signs), or - (hyphens).

Syntax:

* First step
* Second step
* Third step

Result:

• First step
• Second step
• Third step

For an ordered list, you can repeat 1. or number each item in sequence:

Syntax:

1. First step
1. Second step
1. Third step

Or:

1. First step
2. Second step
3. Third step

Result:

1. First step
2. Second step
3. Third step

Lists can also be nested:

Syntax:

1. First step
    1. Process 01
    1. Process 02
    1. Process 03
2. Second step
3. Third step
    * Option 01
    * Option 02
    * Option 03

Result:

1. First step
   1. Process 01
   2. Process 02
   3. Process 03
2. Second step
3. Third step
   • Option 01
   • Option 02
   • Option 03

Links

Put the link text in square brackets and its URL in parentheses.

Syntax:

Link: [Blog](/blog).

Result:

Link: Blog.

You can also create links with a tooltip that appears when you hover over them.

Syntax:

Link: [Blog](/blog "Site blog :)").

Result:

Link: Blog.

To display a URL directly, surround it with < and >.

Syntax:

Link: <https://your-blog.com/blog>

Result:

Link: https://your-blog.com/blog

Images

The syntax for images resembles that for links: put alternative text in square brackets and the image URL or path in parentheses, preceded by !.

Syntax:

![Markdown example](/blog/markdown.png)

Result:

As with links, you can add a title that appears on hover:

Syntax:

![Markdown example](/blog/markdown.png "Image title")

Tables

Build tables using | (pipes) and - (hyphens):

Syntax:

| Heading 01 | Heading 02 | Heading 03 |
|------------|------------|------------|
| R01 C01    | R01 C02    | R01 C03    |
| R02 C01    | R02 C02    | R02 C03    |
| R03 C01    | R03 C02    | R03 C03    |
| R04 C01    | R04 C02    | R04 C03    |

Result:

Heading 01	Heading 02	Heading 03
R01 C01	R01 C02	R01 C03
R02 C01	R02 C02	R02 C03
R03 C01	R03 C02	R03 C03
R04 C01	R04 C02	R04 C03

In addition to creating tables, you can align their columns as follows:

• :-- aligns left.
• --: aligns right.
• :-: centers the content.

Note: Cells do not have to be the same width.

Syntax:

| Product | Quantity in Stock | Cost |
| :-- | :-: | --: |
| Post-it notepad | 31 | R$ 7,64 |
| Pen | 135 | R$ 6,02 |
| Executive spiral planner | 18 | R$ 77,50 |
| Rolling backpack | 7 | R$ 231,75 |
| Triple pencil case | 14 | R$ 57,06 |

Result:

Product	Quantity in Stock	Cost
Post-it notepad	31	R$ 7,64
Pen	135	R$ 6,02
Executive spiral planner	18	R$ 77,50
Rolling backpack	7	R$ 231,75
Triple pencil case	14	R$ 57,06

Code blocks

For inline code, surround text with backticks (```). For example:

Syntax:

A snippet of code `on the same line`.

Result:

A snippet of code on the same line.

It is also possible to insert code blocks with multiple lines and formatting according to the type of code. For example, the code below is HTML:

Syntax:

```html
<!DOCTYPE html>
<html>
  <head>
    <title>HTML Page Title</title>
    <meta name="description" content="Page description" />
  </head>
  <body>
    <h1>Welcome to the site!</h1>
    <br />
    <p>Come back soon</p>
  </body>
</html>
```

Result:

<!DOCTYPE html>
<html>
  <head>
    <title>HTML Page Title</title>
    <meta name="description" content="Page description" />
  </head>
  <body>
    <h1>Welcome to the site!</h1>
    <br />
    <p>Come back soon</p>
  </body>
</html>

Blockquotes

For a blockquote, start the line with > (greater-than sign) and then add your text.

Syntax:

> This is a single-line quote

Result:

This is a single-line quote

To include multiple paragraphs in one quote, put a blank quoted line between them. Every line must begin with >.

Syntax:

> This is a quote with paragraphs
>
> Second paragraph of the quote

Result:

This is a quote with paragraphs

Second paragraph of the quote

To nest a quote inside another, add another >:

Syntax:

> Nested blockquotes
>
>> This is a nested quote

Result:

Nested blockquotes

This is a nested quote

Blockquotes can also contain other Markdown elements, such as a heading and a list:

Syntax:

> #### Level 4 heading inside a blockquote
>
> * First step
> * Second step
> * Third step with **bold** text

Result:

Level 4 heading inside a blockquote

• First step
• Second step
• Third step with bold text

Emojis

Many Markdown viewers support emoji shortcodes: the emoji name surrounded by colons (:).

Emojis
😄 :smile:	😎 :sunglasses:	💥 :boom:
🚀 :rocket:	🔥 :fire:	⚡ :zap:
🔰 :beginner:	♨️ :hotsprings:	🎸 :guitar:

See the complete emoji list for more examples.