Markdown Syntax

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”

Markdown 语法

概述

宗旨

Markdown 的目标是实现「易读易写」。

可读性,无论如何,都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布,并且看起来不会像是由许多标签或是格式指令所构成。Markdown 语法受到一些既有 text-to-HTML 格式的影响,包括 SetextatxTextilereStructuredTextGrutatextEtText,而最大灵感来源其实是纯文本电子邮件的格式。

总之, Markdown 的语法全由一些符号所组成,这些符号经过精挑细选,其作用一目了然。比如:在文字两旁加上星号,看起来就像*强调*。Markdown 的列表看起来,嗯,就是列表。Markdown 的区块引用看起来就真的像是引用一段文字,就像你曾在电子邮件中见过的那样。

兼容 HTML

Markdown 语法的目标是:成为一种适用于网络的书写语言。

Markdown 不是想要取代 HTML,甚至也没有要和它相近,它的语法种类很少,只对应 HTML 标记的一小部分。Markdown 的构想不是要使得 HTML 文档更容易书写。在我看来, HTML 已经很容易写了。Markdown 的理念是,能让文档更容易读、写和随意改。HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown 的格式语法只涵盖纯文本可以涵盖的范围。 Continue reading “Markdown 语法”