Markdown Basic Syntax

Overview

Despite some variations, most applications support the basic elements of Markdown. These elements are essential for you to be able to format a document. But make no mistake, using only the basics of Markdown you can create well-designed sites for Web.

NOTE: Whenever possible, when there are syntax variations from one Markdown processor to another, these will be noted in the article.

Titles

Every document has or should have a title, correct? So, let's start with it.

The symbol used to format a title in Markdown is the hash # one. When building the title, format the code by placing a hash at the beginning of the line, demarcating the header.

For example:

# Level 1 title

It will be converted to HTML's h1 tag.

<h1>Level 1 title</h1>.

NOTE: the h1 tag represents the most important title of the HTML, usually the title of the article.

The number of hashes that you use at the beginning of the line indicates the level of the title, therefore, the formatting ### My title creates a level 3 heading.

NOTE: When we talk about level, we talk about the titles converted to HTML. In HTML, the title levels range from 1 to 6, denoted by the h1, h2, h3, h4, h5 and h6 tags.

EXAMPLES

# Level 1 title

<h1>Level 1 title</h1>

## Level 2 title

<h2>Level 2 title</h2>

### Level 3 title

<h3>Level 3 title</h3>

#### Level 4 title

<h4>Level 4 title</h4>

##### Level 5 title

<h5>Level 5 title</h5>

###### Level 6 title

<h6>Level 6 title</h6>

Alternative syntax

Markdown offers a different syntax for constructing level 1 and 2 headings. Instead of using the hash at the beginning of the line, add equal signs == below level 1 headings and minus signs - for level 2 headers.

EXAMPLES

Level 1 title
===============

<h1>Level 1 title</h1>

Level 2 title
---------------

<h2>Level 2 title</h2>

Some Markdown editors allow you to use only one equal sign = or one dash - below the text, but this can cause formatting problems in other editors that are not compatible with this syntax.

Titles: best practices

You may encounter compatibility issues when we talk about the space between the hash sign # at the beginning of the line and the title text.

It is always recommended to add at least one space between them, in addition to providing a better reading of your document, you will still have more editing support among the Markdown applications.

Table 1.3 exemplifies the correct construction of the title.

Paragraphs

The simplest formatting in Markdown is the paragraph. To create one, simply separate a piece of text with a blank line, creating fragmentations that the Markdown processor will interpret as paragraphs.

EXAMPLES

Markdown is important for every programmer.

Learning Markdown is essential for a successful career.

<p>Markdown is important for every programmer.</p>

<p>Learning Markdown is essential for a successful career.<p>

Paragraphs: best practices

Usually the paragraph is stuck at the beginning of the line, that is, avoid indenting it using spaces of any kind, neither blanks nor tabs.

NOTE: The paragraph must be indented when it is within a list.

Table 1.5 exemplifies the correct use of Markdown formatting for constructing a paragraph.

Line breaks

In HTML a line break is represented by the br tag.

To generate a line break in Markdown, insert two or more blank spaces at the end of the line and press the Enter key.

EXAMPLES

First line of the document.
Second line of the document.

<p>First line of the document.<br>

Second line of the document.</p>

Line break: best practices

The use of white space to create line breaks, although compatible with most applications, can cause formatting problems.

Here are some points:

• Blank spaces after the line are difficult to notice.
• People can add blank spaces at the end of the line, due to habit or carelessness.
• Some text editors, such as Sublime Text, have settings that remove white space before and after the line when saving the document.

A viable alternative to avoid any problems with line breaks is to use the HTML br tag directly in your documents.

NOTE: It is interesting to remember that most Markdown applications are also compatible with HTML tags, that is, you can merge Markdown formatting with HTML formatting in the same document.

NOTE: In some applications, just pressing the Enter key is enough to create a line break

NOTE: Variations of Markdown, such as CommonMark, interpret the use of a backslash \ as an indicator of a new line.

Pressing the Enter key or using the backslash \, although valid, is not recommended as compatibility depends on the Markdown program.

Table 1.7 shows the correct syntax for creating a new line.

Emphasis

Similar to a WYSIWYG editor, like Microsoft Word, Markdown also offers formatting to emphasize the text.

Among the most popular emphasis formats are bold and italics, which can also be applied using the Markdown syntax.

Bold in Markdown

To bold a text in Markdown, place two asterisks ** before the content and two asterisks ** after the content.

EXAMPLES

**This part of the text** will be bold.

<strong>This part of the text</strong> will be bold.

__This part of the text__ will be bold.

<strong>This part of the text</strong> will be bold.

Markdown**Is**Easy**To**Learn

Markdown<strong>Is</strong>Easy<strong>To</strong>Learn

NOTE: As shown in the examples above, you can replace asterisks with underscores, using two underscores __ before and after the content also bolds the text in Markdown.

Bold: best practices

Both the use of two asterisks and the use of two underscores can apply bold formatting to content.

However, the use of underscores in the middle of a word can lead to formatting problems depending on the Markdown processor, therefore, it's best to use asterisks in this case.

Table 1.9 demonstrates the recommended use of Markdown formatting to bold in between text.

Italics in Markdown

Similar to bold, italic formatting in Markdown also uses an asterisk * or an underscore _, but in the case of italics, use only one asterisk * before the content and one asterisk * after the content.

EXAMPLES

*This part of the text* will be in italics.

<em>This part of the text</em> will be in italics.

_This part of the text_ will be in italics.

<em>This part of the text</em> will be in italics.

Markdown*Is*Easy*To*Learn

Markdown<em>Is</em>Easy<em>To</em>Learn

To italicize the middle of a word in Markdown, use an asterisk before and after the content.

Example:

Mar*kdo*wn

Italics: best practices

Always use an asterisk * when italicizing the middle of a word, this will avoid compatibility problems with Markdown processors.

Table 1.11 shows the recommended markup to italicize the middle of the content.

Bold and Italic

Only bold or only italics? If you want, you can combine the two formats to highlight any content.

To apply bold and italics simultaneously, add three asterisks *** or three underscores ___ around the text to be highlighted.

If you are going to emphasize the middle of a word with both formats, give preference to the use of asterisks, in this case, three asterisks ***.

EXAMPLES

***This part of the text*** will be bold and italicized.

<strong><em>This part of the text</em></strong> will be bold and italicized.

This is really ___important___.

This is really <strong><em>important</em></strong>.

This is really __*important*__.

This is really <strong><em>important</em></strong>.

This is really **_important_**.

This is really <strong><em>important</em></strong>.

This text is ***really*** important.

This text is <strong><em>really</em></strong> important.

Bold and Italics: best practices

To avoid compatibility problems with Markdown applications, when highlighting the middle of a word, combining bold and italics, give preference to the use of three asterisks.

Table 1.13 demonstrates the indicated formatting to combine bold and italics.

Blockquote

To mark content as blockquote in Markdown, use the greater than sign > at the beginning of the paragraph.

For example, this Markdown tag:

> Blockquote content.

Would result in this HTML output:

Blockquote content.

Blockquote with multiple paragraphs

If you need a blockquote containing several paragraphs within it, use the greater than sign > in front of each of these paragraphs and separate them by a line containing only the greater than sign.

NOTE: The greater than sign > must be placed on the line that separates the paragraphs, doing so the Markdown processor can interpret your markup correctly.

Let's look at an example:

> First paragraph of the blockquote.
>
> Second paragraph of the blockquote.

The output in HTML:

First paragraph of the blockquote.

Second paragraph of the blockquote.

Nested Blockquotes

In addition to inserting several paragraphs within a blockquote you can also nest them, that is, inserting blockquotes within blockquotes, complex? Let's simplify.

To create a nested block use two greater than signs >> before the paragraph.

Example:

> Blockquote content.
>
>> This paragraph will be interpreted as a nested blockquote.

Rendering in HTML:

Blockquote content.

This paragraph will be interpreted as a nested blockquote.

Blockquote with other elements

The versatility of blockquotes allows the insertion of other Markdown elements within them.

NOTE: Some Markdown elements may not be rendered correctly when placed inside a blockquote, this varies greatly between Markdown processors.

> #### H4 title within the block
>
> - First element of the list within the blockquote.
> - Second element of the list within the blockquote.
>
>  *Italic text* part of paragraph without formatting **bold text**.

The output in HTML:

H4 title within the block

• First element of the list within the blockquote.
• Second element of the list within the blockquote.

Italic text part of the paragraph without formatting bold text.

Lists

Lists are essential in organizing topics in your document. A list facilitates the visualization of elements that may be related to each other.

To create a list in Markdown we use numbers for ordered lists and dashes -, or plus signs +, or asterisks * for unordered lists .

Ordered lists

Let's start by ordering the elements of our list, for that we put a number followed by a period and the text of the element.

It is worth noting that the numbers of the elements do not need to be in ascending numerical order, however, the first element of the list must start with the number one 1.

NOTE: To create an indented element, insert a tab before the number that marks the element. In some Markdown processors you can also insert 3 spaces before numbering, the result is similar, but this can vary depending on the application, when in doubt use TAB.

EXAMPLES

1. First element
2. Second element
3. Third element
4. Fourth element

<ol>
    <li>First element</li>
    <li>Second element</li>
    <li>Third element</li>
    <li>Fourth element</li>
</ol>

1. First element
1. Second element
1. Third element
1. Fourth element

<ol>
    <li>First element</li>
    <li>Second element</li>
    <li>Third element</li>
    <li>Fourth element</li>
</ol>

1. First element
8. Second element
3. Third element
5. Fourth element

<ol>
    <li>First element</li>
    <li>Second element</li>
    <li>Third element</li>
    <li>Fourth element</li>
</ol>

1. First element
2. Second element
3. Third element
    1. Indented element
    2. Indented element
4. Fourth element

<ol>
    <li>First element</li>
    <li>Second element</li>
    <li>Third element</li>
    <ol>
        <li>Indented element</li>
        <li>Indented element</li>
    </ol>
    </li>
    <li>Fourth element</li>
</ol>

Unordered lists

An unordered list is a sequence of elements denoted usually by some symbol to the left of the element, there is no numerical sequence here.

The Markdown markup for creating unordered lists is the plus sign +, or the dash -, or the asterisk *.

Place one of these three signs before the list item to demarcate it, followed by a blank space and the content of the element.

NOTE: Indent an element in the list by inserting a tab before the element markup.

EXAMPLES

- First element
- Second element
- Third element
- Fourth element

<ul>
    <li>First element</li>
    <li>Second element</li>
    <li>Third element</li>
    <li>Fourth element</li>
</ul>

* First element
* Second element
* Third element
* Fourth element

<ul>

    <li>First element</li>

    <li>Second element</li>

    <li>Third element</li>

    <li>Fourth element</li>

</ul>

+ First element
* Second element
- Third element
+ Fourth element

<ul>

    <li>First element</li>

    <li>Second element</li>

    <li>Third element</li>

    <li>Fourth element</li>

</ul>

- First element
- Second element
- Third element
    - Indented element
    - Indented element
- Fourth element

<ul>
    <li>First element</li>
    <li>Second element</li>
    <li>Third element</li>
    <ul>
        <li>Indented element</li>
        <li>Indented element</li>
    </ul>
    </li>
    <li>Fourth element</li>
</ul>

Adding elements

Markdown allows you to insert other elements in the middle of a list without breaking its continuity.

To preserve the formatting of the list, indent the different element by 4 spaces or a tab.

Paragraphs

* This is the first element on the list.
* This is the second element on the list.
    A paragraph added without breaking the list continuity.
* And finally the third item on the list.

The result would be this:

• This is the first element on the list.
• This is the second element on the list.

• A paragraph added without breaking the list continuity.

• And finally the third item on the list.

Blockquote within the list

* This is the first element on the list.
* This is the second element on the list.

    > Blockquote in the middle of the list.

* And finally the third item on the list.

The result would look like this:

• This is the first element on the list.

• This is the second element on the list.

  Blockquote in the middle of the list.

• And here's the third item on the list.

Code block

When inserting a code block in a list, indent it eight spaces or two tabs.

Below is an example of a list with a code block inside it.

1. Let's first open our index.html file.
2. Locate the code block shown below:

        <html>
            <head>
            <title>My website title</title>
        </head>

3. Change the page title.

The result looks like this:

1. Let's first open our index.html file.

2. Locate the code block shown below:

   <html>
       <head>
       <title>My website title</title>
   </head>

3. Change the page title.

Note that the numerical sequence of the list has not changed even with the insertion of the code block between the elements.

Images

1. First open the Markdown logo file.
2. See the Markdown logo on the screen.

    ![Markdown logo](https://markdown.net.br/assets/img/basic-syntax/markdown-logo-small.png)

3. You can close the file now.

Rendering in HTML would look like this:

1. First open the Markdown logo file.

2. See the Markdown logo on the screen.

   
3. You can close the file now.

Code

In Markdown, we can demarcate part of the content as code using backticks `. Place a backtick before and after the text that will be interpreted by the Markdown processor as code.

EXAMPLE:

`code`

<code>code</code>

Escaping backticks

You may encounter the following situation.

The content to which you intend to apply the code formatting already contains a backtick. Or if you want to use the backtick to highlight part of the text within the code itself.

Translating, you need to place a backtick inside a code demarcation without this backtick being interpreted as Markdown markup.

The solution is simple, duplicate the initial and the final backtick that surround the piece of code.

EXAMPLES

``Using `backtick` within the code markup.``

<code>Using `backtick` within the code markup.</code>

Code block

Markdown allows us to create code blocks by indenting the content 4 spaces or a tab.

See the following example:

    <html>
        <head>
        </head>
    </html>

The result:

<html>
    <head>
    </head>
</html>

Using Markdown's extended syntax we can create code blocks without indenting spaces, for that we need to use the fenced code blocks formatting.

Horizontal rules

Three asterisks in a row ***, or three dashes ---, or three underscores ___ create a horizontal rule in Markdown.

A line must contain only those characters for the Markdown processor to interpret the horizontal rule correctly.

***

---

_________________

Using any of the characters the result will be the same, see below.

NOTE: It is not necessary to stipulate a maximum number of characters to create a line, as long as you use at least 3 and the line only has these characters, you can enter as many as you want.

Horizontal rules: best practices

Always add a blank line before and after the horizontal rule mark. This is necessary due to the alternative syntax for creating titles, if you put three dashes --- directly below a line with content, this will be interpreted as a level 2 title.

Table 1.18 exemplifies the creation of horizontal rules in the correct way.

Links

Links are used to create connections between parts of your document. When it comes to creating a page for Web or even PDF files, being able to insert links is one of the indispensable features for editing these types of documents.

The basic syntax for creating links in Markdown is as follows:

• Place the text that will represent the link in square brackets, example:
  [The Best Markdown Site in the World].
• Then, the address of the link, also known as URL, in parentheses, example:
  (https://en.markdown.net.br)

Putting it all together.

Visit [The best Markdown site in the world](https://en.markdown.net.br).

And the output in HTML.

Visit The Best Markdown Site in the World

Adding titles

If you have a little experience with HTML you know that when the user places the mouse pointer over a link on the page, usually a small label describing the purpose of the link pops-up.

This label is what we call the title of link and to create it using Markdown just add inside the parentheses a text in quotes after the URL.

Example:

Visit [The Best Markdown Site in the World](https://en.markdown.net.br "The definitive reference for Markdown.").

Output in HTML, place the mouse over the link and see the title appear.

Visit The Best Markdown Site in the World

URLs and email addresses

You can also turn a URL into a link automatically by placing it between less than < and greater than > signs.

<https://en.markdown.net.br>
<email@host.com>

The result looks like this:

https://en.markdown.net.br
email@host.com

Emphasizing links

By adding asterisks around the link formatting, meaning, before the brackets and after the parentheses, you indicate to the Markdown processor that the link should be emphasized.

For example:

Visit website: *[Markdown reference](https://en.markdown.net.br)*.
I recommend the search engine: **[Duck Duck GO](https://duckduckgo.com/)**.

The output in HTML would look like this:

Visit website: Markdown reference
I recommend the search engine: Duck Duck GO.

You can also highlight a link using code formatting.

Example:

Review the section: [`code`](#code).

Result:

Review the section: code

Reference style Links

Markdown offers an alternative syntax for creating links that allows a cleaner view of your document.

With this syntax you can place the text that will be transformed into link in the middle of the paragraph with just one reference, at the end of the document add all links using the same references you created before.

NOTE: You can place the link reference anywhere in your document, I recommend it at the end for organization reasons.

As the creation of this reference link is divided into two parts, we will analyze each one of them.

First part of link

First we will create two sets of square brackets, inside the first place the text of the link, that is the text that will appear on the page, in the second place a label that will serve as a reference for the address of the link:

[Markdown - Wikipedia][1]

NOTE: The reference link label, placed inside the second pair of brackets, can be anything, numbers, words, phrases, can even include punctuation, it is up to you, as long as the reference to the link at the end of the document is the same.

Examples:

[Markdown - Wikipedia][wiki_markdown.1]
[John Gruber's Official Website][JOHN GRUBER]

NOTE: The reference label is also not case sensitive, ie wiki_markdown is the same as WIKI_MARKDOWN.

Second part of link

The second part indicates where that link points to, or to be specific, the link's URL.

To assemble the second part of the link we have to have the following:

1. A valid link reference label that you created earlier in your document, enclose it in square brackets, followed by a colon and at least one blank space (for example, [label]:).
2. The link address, optionally this URL can be between less than < and greater than > signs.
3. The title of link in double quotes "", single quotes '' or parentheses (), of course, the title is optional.

All the examples below are valid formattings for the second part of the link:

[1]: https://en.wikipedia.org/wiki/Markdown
[1]: https://en.wikipedia.org/wiki/Markdown "Markdown - Wikipedia"
[1]: https://en.wikipedia.org/wiki/Markdown 'Markdown - Wikipedia'
[1]: https://en.wikipedia.org/wiki/Markdown (Markdown - Wikipedia)
[1]: <https://en.wikipedia.org/wiki/Markdown> "Markdown - Wikipedia"
[1]: <https://en.wikipedia.org/wiki/Markdown> 'Markdown - Wikipedia'
[1]: <https://en.wikipedia.org/wiki/Markdown> (Markdown - Wikipedia)

I will emphasize again that you can place this second part of the link anywhere in your document, I add it at the end of the file for organization reasons

Putting all the pieces together

Here I will present you a situation where the use of reference links can keep your Markdown document easier to read.

Say you need to add one or more links to a website with more information about the content covered in that paragraph.

In Markdown it would look like this:

To learn more you can consult this Markdown article: [Wikipedia](https://en.wikipedia.org/wiki/Markdown "Markdown - Wikipedia"). Or the language documentation: [John Gruber](https://daringfireball.net/projects/markdown/ "Original documentation from Markdown.").

Note that adding links within the paragraph itself can make the text more difficult to read, especially if the person reading it does not know Markdown.

Since the links are important for the context of the paragraph, we cannot remove them, however there is a more effective way to clean up that paragraph using reference links.

To learn more you can consult this Markdown article: [Wikipedia][1]. Or the language documentation: [John Gruber][2].

[1]: <https://en.wikipedia.org/wiki/Markdown> "Markdown - Wikipedia"
[2]: https://daringfireball.net/projects/markdown/ "Original documentation from Markdown."

NOTE: Placing the less than < and greater than > signs around the link is optional.

The two formats above will have similar results in HTML:

To learn more you can consult this Markdown article: Wikipedia. Or the language documentation: John Gruber.

Reference Links: best practices

In some cases, you may encounter blank space in URLs, this can become a problem depending on the Markdown application.

To avoid formatting anomalies, use the encoded white space: %20.

Table 1.19 shows the formatting of white space in URL using encoding.

Images

The Markdown syntax for adding an image is as follows:

1. An exclamation point: !.
2. The alternative text of the image in square brackets: []
3. The full address of the image within parentheses: ()
4. Optional title in quotes, still in parentheses: ( "")

Example:

![Markdown is the simplest markup language in the world!](https://markdown.net.br/assets/img/markdown.jpg "Markdown logo")

The conversion to HTML looks like this:

Image and Link

To use an image as link:

1. Create a normal link format.
2. In the first pair of brackets in the link formatting, where you put the link text, use the image Markdown formatting you just learned.

Example:

[![An ancient stone in the desert](https://markdown.net.br/assets/img/shiprock.jpg "Shiprock, New Mexico By Beau Rogers")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv)

The result:

Escaping characters

To escape a character in Markdown, that is, to represent it literally in the document, insert a backslash before it.

Example:

\* The backslash before the asterisk causes the Markdown processor to interpret that line as a paragraph and not an element of a list.

The result looks like this:

* The backslash before the asterisk causes the Markdown processor to interpret this line as a paragraph and not an element of a list.

Characters you can escape

Table 1.20 shows what characters you can escape in Markdown using the backslash: \.

HTML and Markdown

Programmers who already have experience in HTML, sometimes mix the two syntaxes in the same document, that is, HTML and Markdown.

HTML can be useful in tasks like changing attributes of elements of your document such as colors, location, size, etc.

Place the HTML tags directly in your document.

**bold** <em>Italic</em>

The result looks like this:

bold italic

HTML and Markdown: best practices

It is important to note that not all Markdown processors are compatible with the HTML tags, in some cases, they support only a subset of these tags.

Trial and error can be a strategy. Try to format content using tags and check if the output in HTML is as expected, or of course, consult the application's documentation.

Do not indent the tags line in HTML, neither with blanks nor with tabs, this can interfere with the formatting of the element when converted.

Insert a blank line before and after block elements like: <div>, <table>, <pre>, <p>.

Avoid placing Markdown elements inside the content of HTML tags.

The code below, although compatible with some editors, has a mixture of syntax that can cause formatting problems.

<p>Italic **bold**</p>