Month: April 2021

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”