Markdown Basic Syntax #

Markdown is a lightweight markup language with a simple syntax that allows people to focus more on the content itself rather than on formatting. It uses an easy-to-read, easy-to-write plain text format to create documents, can be mixed with HTML, and can be exported to HTML, PDF, and its own .md format. Because of its simplicity, efficiency, and readability, Markdown is widely used on platforms like Github, Wikipedia, Jianshu, etc.

Try it out with our Online Markdown Editor.

Don’t be intimidated by “markup” or “language.” Markdown’s syntax is very simple, with fewer than ten commonly used symbols, which is more than enough for daily writing and can be fully mastered in less than half an hour. These few symbols allow for elegant and immersive writing, focusing on content rather than struggling with layout, achieving a state of “clear mind, focused writing.”

Let’s start by learning about Markdown Headings.

---

Markdown Headings #

To create a heading, add a hash mark (#) before a word or phrase. The number of #s represents the heading level. For example, adding three #s creates a third-level heading (<h3>) (e.g., ### My Header).

Markdown Syntax	HTML	Rendered Output
# Heading level 1	<h1>Heading level 1</h1>	Heading level 1
## Heading level 2	<h2>Heading level 2</h2>	Heading level 2
### Heading level 3	<h3>Heading level 3</h3>	Heading level 3
#### Heading level 4	<h4>Heading level 4</h4>	Heading level 4
##### Heading level 5	<h5>Heading level 5</h5>	Heading level 5
###### Heading level 6	<h6>Heading level 6</h6>	Heading level 6

Alternate Syntax #

You can also identify a first-level heading by adding any number of == characters below the text, or a second-level heading with -- characters.

Markdown Syntax	HTML	Rendered Output
Heading level 1 ===============	<h1>Heading level 1</h1>	Heading level 1
Heading level 2 ---------------	<h2>Heading level 2</h2>	Heading level 2

Best Practices #

Different Markdown applications handle the space between the # and the heading differently. For compatibility, use a single space between the # and the heading.

✅  Do this	❌  Don’t do this
# Here's a Heading	#Here's a Heading

---

Markdown Paragraphs #

To create a paragraph, use a blank line to separate one or more lines of text.

Markdown Syntax	HTML	Rendered Output
I really like using Markdown. I think I'll use it to format all of my documents from now on.	<p>I really like using Markdown.</p> <p>I think I'll use it to format all of my documents from now on.</p>	I really like using Markdown. I think I’ll use it to format all of my documents from now on.

Paragraph Best Practices #

Do not indent paragraphs with spaces or tabs.

✅  Do this	❌  Don’t do this
Don't put tabs or spaces in front of your paragraphs. Keep lines left-aligned like this.	This can result in unexpected formatting problems. Don't add tabs or spaces in front of paragraphs.

---

Markdown Line Breaks #

To create a line break (<br>), add two or more spaces at the end of a line, then press Enter.

Markdown Syntax	HTML	Rendered Output
This is the first line. And this is the second line.	<p>This is the first line.<br> And this is the second line.</p>	This is the first line. And this is the second line.

Line Break Best Practices #

Almost every Markdown application supports two or more spaces for a line break, known as “trailing whitespace,” but this is controversial because it’s hard to see spaces in an editor, and many people intentionally or unintentionally add two spaces after every sentence. For this reason, you may want to use a different method for line breaks. Fortunately, almost every Markdown application supports another way: the HTML <br> tag.

For compatibility, add “trailing whitespace” or the HTML <br> tag at the end of the line to create a line break.

There are two other methods I don’t recommend. CommonMark and several other lightweight markup languages support adding a backslash (\) at the end of the line for a line break, but not all Markdown applications support this, so it’s not recommended from a compatibility perspective. Additionally, at least two lightweight markup languages support creating a line break by simply pressing Enter without adding anything at the end of the line.

✅  Do this	❌  Don’t do this
First line with two spaces after. And the next line.	First line with a backslash after.\ And the next line.
First line with the HTML tag after.<br> And the next line.	First line with nothing after. And the next line.

---

Markdown Emphasis #

Emphasize text by making it bold or italic.

Bold #

To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word or phrase for emphasis, add two asterisks on each side of the part to be bolded.

Markdown Syntax	HTML	Rendered Output
I just love **bold text**.	I just love <strong>bold text</strong>.	I just love bold text.
I just love __bold text__.	I just love <strong>bold text</strong>.	I just love bold text.
Love**is**bold	Love<strong>is</strong>bold	Loveisbold

Bold Best Practices #

Markdown applications do not consistently handle underscores in the middle of a word or phrase. for compatibility, use asterisks for bolding in the middle of a word or phrase.

✅  Do this	❌  Don’t do this
Love**is**bold	Love__is__bold

Italic #

To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word, add one asterisk on each side of the letters, with no space in between.

Markdown Syntax	HTML	Rendered Output
Italicized text is the *cat's meow*.	Italicized text is the <em>cat's meow</em>.	Italicized text is the cat’s meow.
Italicized text is the _cat's meow_.	Italicized text is the <em>cat's meow</em>.	Italicized text is the cat’s meow.
A*cat*meow	A<em>cat</em>meow	Acatmeow

Italic Best Practices #

To emphasize text with both bold and italic, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word or phrase, add three asterisks on each side of the part to be emphasized, with no space in between.

✅  Do this	❌  Don’t do this
A*cat*meow	A_cat_meow

Bold and Italic #

To emphasize text with both bold and italic, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word or phrase, add three asterisks on each side of the part to be emphasized, with no space in between.

Markdown Syntax	HTML	Rendered Output
This text is ***really important***.	This text is <strong><em>really important</em></strong>.	This text is really important.
This text is ___really important___.	This text is <strong><em>really important</em></strong>.	This text is really important.
This text is __*really important*__.	This text is <strong><em>really important</em></strong>.	This text is really important.
This text is **_really important_**.	This text is <strong><em>really important</em></strong>.	This text is really important.
This is really***very***important text.	This is really<strong><em>very</em></strong>important text.	This is really**very**important text.

Bold and Italic Best Practices #

Markdown applications do not consistently handle underscores added in the middle of a word or phrase. For compatibility, use asterisks to bold and italicize the middle of a word or phrase for emphasis.

✅  Do this	❌  Don’t do this
This is really***very***important text.	This is really___very___important text.

---

Markdown Blockquotes #

To create a blockquote, add a > symbol in front of a paragraph.

> Dorothy followed her through many of the beautiful rooms in her castle.

Blockquotes with Multiple Paragraphs #

Blockquotes can contain multiple paragraphs. Add a > symbol on the blank line between paragraphs.

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

Nested Blockquotes #

Blockquotes can be nested. Add a >> symbol in front of the paragraph you want to nest.

> Dorothy followed her through many of the beautiful rooms in her castle.
>
> > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.

Blockquotes with Other Elements #

Blockquotes can contain other Markdown formatted elements. Not all elements can be used, so you’ll need to experiment to see which ones work.

> #### The quarterly results look great!
>
> - Revenue was off the chart.
> - Profits were higher than ever.
>
>   _Everything_ is going according to **plan**.

---

Markdown Lists #

You can organize items into ordered or unordered lists.

Ordered Lists #

To create an ordered list, add a number followed by an English period before each list item. The numbers don’t have to be in mathematical order, but the list should start with the number 1.

Markdown Syntax	HTML	Rendered Output
1. First item 2. Second item 3. Third item 4. Fourth item	<ol> <li>First item</li> <li>Second item</li> <li>Third item</li> <li>Fourth item</li> </ol>	1. First item 2. Second item 3. Third item 4. Fourth item
1. First item 1. Second item 1. Third item 1. Fourth item	<ol> <li>First item</li> <li>Second item</li> <li>Third item</li> <li>Fourth item</li> </ol>	1. First item 1. Second item 1. Third item 1. Fourth item
1. First item 8. Second item 3. Third item 5. Fourth item	<ol> <li>First item</li> <li>Second item</li> <li>Third item</li> <li>Fourth item</li> </ol>	1. First item 8. Second item 3. Third item 5. Fourth item
1. First item 2. Second item 3. Third item 1. Indented item 2. Indented item 4. Fourth item	<ol> <li>First item</li> <li>Second item</li> <li>Third item <ol> <li>Indented item</li> <li>Indented item</li> </ol> </li> <li>Fourth item</li> </ol>	1. First item 2. Second item 3. Third item 1. Indented item 2. Indented item 4. Fourth item

Ordered List Best Practices #

CommonMark and a few other lightweight markup languages let you use a parenthesis ()) as a delimiter (e.g., 1) First item), but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. For compatibility, use periods only.

✅  Do this	❌  Don’t do this
1. First item 2. Second item	1) First item 2) Second item

Unordered Lists #

To create an unordered list, add a dash (-), asterisk (*), or plus sign (+) in front of each list item. Indent one or more items to create a nested list.

Markdown Syntax	HTML	Rendered Output
- First item - Second item - Third item - Fourth item	<ul> <li>First item</li> <li>Second item</li> <li>Third item</li> <li>Fourth item</li> </ul>	- First item - Second item - Third item - Fourth item
* First item * Second item * Third item * Fourth item	<ul> <li>First item</li> <li>Second item</li> <li>Third item</li> <li>Fourth item</li> </ul>	_ First item _ Second item _ Third item _ Fourth item
+ First item + Second item + Third item + Fourth item	<ul> <li>First item</li> <li>Second item</li> <li>Third item</li> <li>Fourth item</li> </ul>	+ First item + Second item + Third item + Fourth item
- First item - Second item - Third item - Indented item - Indented item - Fourth item	<ul> <li>First item</li> <li>Second item</li> <li>Third item <ul> <li>Indented item</li> <li>Indented item</li> </ul> </li> <li>Fourth item</li> </ul>	- First item - Second item - Third item - Indented item - Indented item - Fourth item

Unordered List Best Practices #

Markdown applications don’t agree on how to handle different delimiters in the same list. For compatibility, don’t mix and match delimiters in the same list — pick one and stick with it.

✅  Do this	❌  Don’t do this
- First item - Second item - Third item - Fourth item	+ First item * Second item - Third item + Fourth item

Nesting Other Elements in Lists #

To add another element in a list while preserving the continuity of the list, indent the element by four spaces or one tab, as shown in the following examples:

Paragraphs #

- This is the first list item.
- Here's the second list item.

  I need to add another paragraph below the second list item.

- And here's the third list item.

Blockquotes #

- This is the first list item.
- Here's the second list item.

  > A blockquote would look great below the second list item.

- And here's the third list item.

Code Blocks #

Code blocks are usually indented with four spaces or one tab. When they are placed in a list, indent them with eight spaces or two tabs.

1.  Open the file.
2.  Find the following code block on line 21:

        <html>
          <head>
            <title>Test</title>
          </head>

3.  Update the title to match the name of your website.

Images #

1.  Open the file containing the Linux mascot.
2.  Marvel at its beauty.

    <img src="/assets/images/tux.png" alt="Tux, the Linux mascot" loading="lazy" class="blog-image" />

3.  Close the file.

Lists #

You can nest an unordered list in an ordered list, or vice versa.

1. First item
2. Second item
3. Third item
   - Indented item
   - Indented item
4. Fourth item

---

Markdown Code #

To represent a word or phrase as code, enclose it in backticks (`).

Markdown Syntax	HTML	Rendered Output
At the command prompt, type \nano`.`	At the command prompt, type <code>nano</code>.	At the command prompt, type nano.

Escaping Backticks #

If the word or phrase you want to represent as code contains one or more backticks, you can enclose it in double backticks ( ).

Markdown Syntax	HTML	Rendered Output
\`Use `code` in your Markdown file.```	<code>Use \code` in your Markdown file.`	Use `code` in your Markdown file.

Code Blocks #

To create a code block, indent each line of the block by at least four spaces or one tab.

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

Note: To create a code block without indentation, use fenced code blocks.

---

Markdown Horizontal Rule #

To create a horizontal rule, use three or more asterisks (***), dashes (---), or underscores (___) on a separate line, with nothing else on it.

***

---

_________________

Horizontal Rule Best Practices #

For compatibility, add blank lines before and after a horizontal rule.

✅  Do this	❌  Don’t do this
Try to put a blank line before... --- ...and after a horizontal rule.	Without blank lines, this would be a heading. --- Don't do this!

---

Markdown Links #

Link text is placed in square brackets, the link address is in the following parentheses, and the link title is optional.

Hyperlink Markdown syntax: [Link display name](Link address "Link title")

Corresponding HTML code: <a href="Link address" title="Link title">Link display name</a>

This is a link to Markdown Syntax.

Adding a Title to a Link #

The link title appears when the mouse hovers over the link. This title is optional and is placed in parentheses after the link address, separated by a space.

This is a link to Markdown Syntax.

URLs and Email Addresses #

Using angle brackets is a convenient way to turn a URL or email address into a clickable link.

</en>
<[email protected]>

Formatted Links #

To emphasize a link, add asterisks before and after the link syntax. To represent a link as code, add backticks inside the square brackets.

I love supporting the **[EFF](/en)**.
This is the _[Markdown Guide](/en)_.
See the section on [`code`](#code).

Reference-style Links #

Reference-style links are a special kind of link that makes URLs easier to display and read in Markdown. They are split into two parts: the part that stays inline with the text and the part that is stored elsewhere in the file to keep the text readable.

First Part of the Link #

The first part of a reference-style link is formatted with two sets of brackets. The first set of square brackets encloses the text that should be displayed as the link. The second set of brackets displays a label that is used to point to the link you have stored elsewhere in your document.

Although not required, you can include a space between the first and second sets of brackets. The label in the second set of brackets is case-insensitive and can contain letters, numbers, spaces, or punctuation.

The following example formats are equivalent for the first part of the link:

• [hobbit-hole][1]
• [hobbit-hole] [1]

Second Part of the Link #

The second part of a reference-style link is formatted with the following attributes:

• The label in brackets, followed by a colon and at least one space (e.g., [label]:).
• The URL for the link, which can optionally be enclosed in angle brackets.
• An optional title for the link, which can be enclosed in double quotes, single quotes, or parentheses.

The following example formats are equivalent for the second part of the link:

• [1]: /en
• [1]: /en "Hobbit lifestyles"
• [1]: /en 'Hobbit lifestyles'
• [1]: /en (Hobbit lifestyles)
• [1]: </en> "Hobbit lifestyles"
• [1]: </en> 'Hobbit lifestyles'
• [1]: </en> (Hobbit lifestyles)

You can place the second part of the link anywhere in your Markdown document. Some people place them immediately after the paragraph in which they appear, while others place them at the end of the document (like endnotes or footnotes).

Link Best Practices #

Different Markdown applications handle spaces in the middle of a URL differently. For compatibility, try to use %20 instead of spaces.

✅  Do this	❌  Don’t do this
[link](https://www.example.com/my%20great%20page)	[link](https://www.example.com/my great page)

---

Markdown Images #

To add an image, use an exclamation mark (!), followed by alt text in square brackets, and the image link in parentheses. You can add an optional image title text after the link in the parentheses.

Image insertion Markdown syntax: <img src="/blog/images/posts/Image link "Image title"" alt="Image alt" loading="lazy" class="blog-image" />.

Corresponding HTML code: <img src="Image link" alt="Image alt" title="Image title">

<img src="/assets/img/philly-magic-garden.jpg "Magic Gardens"" alt="This is an image" loading="lazy" class="blog-image" />

Linking Images #

To add a link to an image, enclose the Markdown for the image in square brackets, and then add the link in parentheses.

[<img src="/assets/img/shiprock.jpg "Shiprock"" alt="A picture of rocks in the desert" loading="lazy" class="blog-image" />](/en)

---

Markdown Escaping Characters #

To display characters that are normally used to format Markdown documents, add a backslash character \ before the character.

\* Without the backslash, this would be a bullet in an unordered list.

Escapable Characters #

The following characters can be escaped by using a backslash character.

| Character | Name | | --------- | ---------------------------------------------- | --------------------------------------- | | \ | backslash | | ` | backtick (see also escaping backticks in code) | | * | asterisk | | _ | underscore | | { } | curly braces | | [ ] | brackets | | ( ) | parentheses | | # | pound sign | | + | plus sign | | - | minus sign (hyphen) | | . | dot | | ! | exclamation mark | | | | pipe (see also escaping pipe in tables) |

Automatic Escaping of Special Characters #

In HTML files, two characters require special treatment: < and &. The < symbol is used for starting tags, and the & symbol is used to denote HTML entities. If you just want to use these symbols, you must use their entity forms, like < and &.

The & symbol can be quite troublesome for people writing web files. If you want to type “AT&T”, you have to write “AT&T”. You also have to convert & symbols within URLs. If you want to link to:

http://images.google.com/images?num=30&q=larry+bird

You must convert the URL to:

http://images.google.com/images?num=30&q=larry+bird

to put it in the href attribute of a link tag. Needless to say, this is easy to forget, and it’s probably one of the most common errors found by HTML validation.

Markdown allows you to use these symbols directly; it automatically escapes them for you. If you use the & symbol as part of an HTML entity, it will not be converted. In other cases, it will be converted to &. So if you want to insert a copyright symbol in your file, you can write:

©

Markdown will not modify this text. But if you write:

AT&T

Markdown will convert it to:

AT&T

A similar situation occurs with the < symbol. Because Markdown supports inline HTML, if you use the < symbol as a delimiter for an HTML tag, Markdown will not convert it. But if you write:

4 < 5

Markdown will convert it to:

4 < 5

It is important to note that within Markdown’s block-level and inline elements, the < and & symbols are automatically converted to HTML entities. This feature makes it very easy to write HTML with Markdown. (In HTML syntax, you have to manually convert all < and & to HTML entities.)

---

Markdown Inline HTML #

For tags not covered by Markdown, you can use HTML directly in the file. To use HTML, you don’t need to specify that it’s HTML or Markdown; just add the HTML tags to your Markdown text.

Inline-level Tags #

HTML inline-level tags like <span>, <cite>, and <del> are not restricted and can be used freely in Markdown paragraphs, lists, or headings. Depending on personal preference, you can even use HTML tags for formatting instead of Markdown syntax. For example, if you prefer the HTML <a> or <img> tags, you can use them directly instead of Markdown’s link or image syntax. When you need to change an element’s attributes (e.g., specifying a color for text or changing an image’s width), using HTML tags is more convenient.

Unlike block-level tags, Markdown syntax can be parsed within the scope of inline HTML tags.

This **word** is bold. This <em>word</em> is italic.

Block-level Tags #

Block-level elements—such as <div>, <table>, <pre>, <p>, etc.—must be separated by blank lines before and after to distinguish the content. Also, the start and end tags of these elements cannot be indented with tabs or spaces. Markdown will automatically recognize these block elements and avoid adding unnecessary <p> tags before and after the block tags.

For example, to add an HTML table to a Markdown file:

This is a regular paragraph.

<table>
  <tr>
    <td>Foo</td>
  </tr>
</table>

This is another regular paragraph.

Please note that Markdown syntax will not be processed within HTML block-level tags. For example, you cannot use Markdown’s *emphasis* inside an HTML block.

HTML Best Practices #

For security reasons, not all Markdown applications support adding HTML to Markdown documents. When in doubt, check the documentation of the respective Markdown application. Some applications only support a subset of HTML tags.

For block-level HTML elements like <div>, <table>, <pre>, and <p>, use blank lines to separate them from other content. Try not to indent HTML tags with tabs or spaces, as this may affect the formatting.

You cannot use Markdown syntax within HTML block-level tags. For example, <p>italic and **bold**</p> will not work.