Overview
Nearly all Markdown applications support the basic syntax outlined in John Gruber’s original design document. There are minor variations and discrepancies between Markdown processors, those are noted inline wherever possible.
Headings
To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).
| Markdown |
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
Alternatively, on the line below the text, add any number of == characters for heading level 1 or — characters for heading level 2.
| Markdown |
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 Best Practices
Markdown applications don’t agree on how to handle a missing space between the number signs (#) and the heading name. For compatibility, always put a space between the number signs and the heading name.
| ✅ Do this |
❌ Don’t do this |
| # Here’s a Heading |
#Here’s a Heading |
Paragraphs
To create paragraphs, use a blank line to separate one or more lines of text.
| Markdown |
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
Unless the paragraph is in a list, don’t 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. |
Line Breaks
To create a line break (<br>), end a line with two or more spaces, and then type return.
| Markdown |
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
You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people accidentally or intentionally put two spaces after every sentence. For this reason, you may want to use something other than trailing whitespace for line breaks. Fortunately, there is another option supported by nearly every Markdown application: the <br> HTML tag.
For compatibility, use trailing white space or the <br> HTML tag at the end of the line.
There are two other options I don’t recommend using. CommonMark and a few other lightweight markup languages let you type a backslash () at the end of the line, but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. And at least a couple lightweight markup languages don’t require anything at the end of the line — just type return and they’ll create a line break.
| ✅ Do this |
❌ Don’t do this |
First line with two spaces after.
And the next line.First line with the HTML tag after.<br>
And the next line. |
First line with a backslash after.
And the next line.First line with nothing after.
And the next line. |
Emphasis
You can add emphasis by making text 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 for emphasis, add two asterisks without spaces around the letters.
| Markdown |
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 don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold the middle of a word for emphasis.
| ✅ 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 for emphasis, add one asterisk without spaces around the letters.
| Markdown |
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
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to italicize the middle of a word for emphasis.
| ✅ Do this |
❌ Don’t do this |
| A*cat*meow |
A_cat_meow |
Bold and Italic
To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces around the letters.
| Markdown |
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 reallyveryimportant text. |
Bold and Italic Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold and italicize the middle of a word for emphasis. Continue reading “Markdown Syntax”
