Markdown 语法手册&书写风格建议（完整整理版）

作者: 5e44ebcb2a17 | 来源:发表于2018-03-23 14:28 被阅读8次

目录：

兼容HTML
- HTML标签知识补充
  - HTML块级元素
  - HTML内联元素
生成目录
区块元素
- 段落和换行
  - 书写风格建议
- 标题
  - 书写风格建议
- 引用
  - 书写风格建议
- 列表
  - 无序列表
    - 书写风格建议
  - 有序列表
    - 书写风格建议
- 代码区块
- 表格
- 分隔线（水平横线）
  - 书写风格建议
区段元素
- 链接
  - 行内式
  - 参考式
    - 隐式链接标记
  - 书写风格建议
    - 参考样式链接
- 强调
  - 书写风格建议
    - 加粗
    - 斜体
- 代码
  - 书写风格建议
- 图片
  - 行内式
  - 参考式
其他
- 自动链接
- 反斜杠
- 参考资料

兼容HTML

不在 Markdown 涵盖范围之内的标签，都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown，只要直接加标签就可以了。

需要注意的是，只有一些HTML区块元素（区块元素） ——比如 <div>、<table>、<pre>、<p> 等标签，必须在前后加上空行与其它内容区隔开，还要求它们的开始标签与结尾标签，不能用制表符或空格来缩进。

例如：

这是一个普通段落。

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

这是另一个普通段落。

在 HTML区块标签（区块元素） 间的 Markdown 格式语法将不会被处理。

比如，你在 HTML 区块内使用 Markdown 样式的**强调**会没有效果。

HTML 的 区段标签（内联元素） 如 <span>、<cite>、<del> 可以在 Markdown 的段落、列表或是标题里随意使用。

和处在HTML区块标签间不同，Markdown语法在 HTML区段标签（内联元素） 间是有效的。

HTML标签知识补充

什么是HTML区块标签（区块元素）和区段标签（内联元素）？

大多数 HTML 元素被定义为块级元素或内联元素。

块级元素在浏览器显示时，通常会以新行来开始（和结束）。

内联元素在显示时通常不会以新行开始。

HTML块级元素

<address> 定义地址
<caption> 定义表格标题
<dd> 定义列表中定义条目
<div> 定义文档中的分区或节
<dl> 定义列表
<dt> 定义列表中的项目
<fieldset> 定义一个框架集
<form> 创建 HTML 表单
<h1> 定义最大的标题
<h2> 定义副标题
<h3> 定义标题
<h4> 定义标题
<h5> 定义标题
<h6> 定义最小的标题
<hr> 创建一条水平线
<legend> 元素为
<fieldset> 元素定义标题
<li> 标签定义列表项目
<noframes> 为那些不支持框架的浏览器显示文本，于 frameset 元素内部
<noscript> 定义在脚本未被执行时的替代内容
<ol> 定义有序列表
<ul> 定义无序列表
<p> 标签定义段落
<pre> 定义预格式化的文本
<table> 标签定义 HTML 表格
<tbody> 标签表格主体（正文）
<td> 表格中的标准单元格
<tfoot> 定义表格的页脚（脚注或表注）
<th> 定义表头单元格
<thead> 标签定义表格的表头
<tr> 定义表格中的行

HTML内联元素

<a> 标签可定义锚
<abbr> 表示一个缩写形式
<acronym> 定义只取首字母缩写
<b> 字体加粗
<bdo> 可覆盖默认的文本方向
<big> 大号字体加粗
<br> 换行
<cite> 引用进行定义
<code> 定义计算机代码文本
<dfn> 定义一个定义项目
<em> 定义为强调的内容
<i> 斜体文本效果
<img> 向网页中嵌入一幅图像
<input> 输入框
<kbd> 定义键盘文本
<label> 标签为
<input> 元素定义标注（标记）
<q> 定义短的引用
<samp> 定义样本文本
<select> 创建单选或多选菜单
<small> 呈现小号字体效果
<span> 组合文档中的行内元素
<strong> 语气更强的强调的内容
<sub> 定义下标文本
<sup> 定义上标文本
<textarea> 多行的文本输入控件
<tt> 打字机或者等宽的文本效果
<var> 定义变量

生成目录

在需要生成目录的地方写 [TOC]。

区块元素

段落和换行

一个 Markdown 段落是由一个或多个连续的文本行组成。
段落的前后要有一个以上的空行。

例如：

这是第一个段落。
//空行
这是第二个段落。
//空行
这是第三个段落。
//空行
//空行
这是第四个段落。

Markdown 也允许段落内的强迫换行（插入换行符）。

如果想要 Markdown 段落在 段落内换行 的话，在需要换行的地方输入两个以上的空格然后回车。

书写风格建议

应当尽可能的避免使用换行符（段落内换行 / 两个以上的空格然后回车），因为他们没有被广泛认可的语义。

标题

Markdown 支持两种标题的语法，类 Setext 和类 atx 形式。

类 Setext 形式是用底线的形式，利用 = （等号，最高阶标题）和 - （减号，第二阶标题），任何数量的 = 和 - 都可以有效果

例：

This is an H1
=============


This is an H2
-------------

类 Atx 形式
- 形式一：在行首插入 1 到 6 个 # ，对应到标题 1 到 6 阶
  
  例：
```
# 这是 H1

## 这是 H2

###### 这是 H6
```
- 形式二：「闭合」类 atx 样式的标题，在行首插入 1 到 6 个 # ，在行尾加上 #，而行尾的 # 数量不用与开头数量一致（行首的 # 字符数量决定标题的阶数）
  
  例：
```
# 这是 H1 #

## 这是 H2 ##

### 这是 H3 ######
```

书写风格建议

建议：

类 atx 样式的形式一，且不要使用闭合的 #
在 # 和标题之间加入一个空格

不要在 # 前加入空格

# 这是 H1

## 这是 H2

###### 这是 H6

不要跳跃使用标题等级
在标题上下用空行隔开，除非标题在文档开头
```
# 这是 H1
//空行
## 这是 H2
//空行
//其他内容
```
避免在同一 Markdown 文件中使用相同的标题，原因是许多的 Markdown 解释器会依据标题的内容生成标题的IDs
英文标题开头建议使用首字母大写，除非标题内容总是以小写出现, 比如计算机代码，其他字母按照句子中原始大小写

# Header

# int main //计算机代码

# The header of the example

# The Header of the Example //不建议

尽可能避免使用长句子，总结长句子作为标题，然后将长句子作为标题下的第一小节。原因：以后引用方便，尤其是自动生成 IDs 或者生成 TOC

# Huge header

Huge header that talks about a complex subject.


# Huge header that talks about a complex subject //不建议

不要在标题中以 :（冒号）结尾

解释: 每一个标题都是接下来内容的简介，这也就正是冒号的作用。
要在标题中以 . 结尾

解释: 每一个标题都包含一个简短的句子，也就不需要句号来分隔他们。

引用

在被引用的内容前加上 > 符号。

例如：

> 这是一段引用内容
>
> 这是一段引用内容

效果如下：

这是一段引用内容

这是一段引用内容

Markdown 也允许只在整个段落的第一行最前面加上 > ：

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

效果如下：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

区块引用可以嵌套（例如：引用内的引用），只要根据层次加上不同数量的 >。

例如：

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level

效果如下：

This is the first level of quoting.

This is nested blockquote.

Back to the first level

引用的区块内也可以使用其他的 Markdown 语法，包括标题、列表、代码区块等：

> ## 这是一个标题。
> 
> 1. 这是第一行列表项。
> 2. 这是第二行列表项。
> 
> 给出一些例子代码：
> 
>     return shell_exec("echo $input | $markdown_script");

效果如下：

这是第一行列表项。

这是第二行列表项。

给出一些例子代码：
return shell_exec("echo $input | $markdown_script");

书写风格建议

在符号 > 后面接一个空格

建议：> a。

不建议不加空格或加多个空格：
```
>a
```
或
```
>  a
```
在每一行使用 > 符号，包括换行的句子

建议：
```
> Long line
> that was wrapped.
```
不建议：
```
> Long line
that was wrapped.
```
不要在单独的引用中使用空行

建议：
```
> a
>
> b
```
不建议：
```
> a

> b
```

列表

列表项目标记通常是放在最左边，但也可以缩进，最多缩进 3 个空格，项目标记后面则一定要接着至少一个空格或制表符。
如果列表项目间用空行分开，在输出 HTML 时 Markdown 就会将项目内容用 <p> 标签包起来
```
* Bird
* Magic
```
会被转换为：
```
<ul>
<li>Bird</li>
<li>Magic</li>
</ul>
```
但是：
```
* Bird

* Magic
```
会被转换为：
```
<ul>
<li><p>Bird</p></li>
<li><p>Magic</p></li>
</ul>
```
列表项目可以包含多个段落，每个项目下的段落都 必须缩进 4 个空格或是 1 个制表符

1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

2.  Suspendisse id sem consectetuer libero luctus adipiscing.

如果要在列表项目内放进引用，那 > 就需要缩进

- A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

如果要放代码区块的话，该区块就需要缩进两次，也就是 8 个空格或是 2 个制表符

- 一列表项包含一个列表区块：

        <代码写在这>

如果在行首出现数字-句点-空白，为了避免这样的冲突，可以在句点前面加上反斜杠

1986\. What a great season.

无序列表

无序列表使用星号（*）、加号（+）或是减号（-）作为列表标记。

* Red
+ Red
- Red

书写风格建议

建议使用 - ,星号 * 可能和加粗和斜体符号产生混淆，而 + 当前并不流行。

有序列表

有序列表则使用数接着一个英文句点字

//可以这样：
1. Bird
2. McHale
3. Parish

//也可以这样
1.  Bird
1.  McHale
1.  Parish

//甚至不用在意数字的正确性和连续性
3. Bird
1. McHale
8. Parish

很重要的一点是，在列表标记上使用的数字并不会影响输出的 HTML 结果，上面的列表所产生的 HTML 标记为：

<ol>
<li>Bird</li>
<li>McHale</li>
<li>Parish</li>
</ol>

书写风格建议

列表中内容的缩进层级必须和第一个列表项一致
如果每一个列表项只有一行, 不要在列表项之间增加空行，否则，在每一个列表项之间增加空行

//建议
- item 1
- item 2
- item 3

//不建议
- item 1

- item 2

- item 3

多行情况下：

//建议每项空行
- item that
  is wrapped

- item 2

- item 3

//不建议
- item that
  is wrapped
- item 2
- item 3

列表外建议留有一空行

//建议
Before text.

- list
- list

After text.

//不建议
Before text.
- item
- item
After text.

列表项结尾标点，除非
- 包含多个句子或者短语
- 以大写字母开头
否则, 如果以句号结尾的话，省略标点

代码区块

建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以了。

例如：

这是一个普通段落：

    这是一个代码区块。

实际效果为：

这是一个普通段落。

这是一个代码区块。

需要注意的是：一个代码区块会一直持续到没有缩进的那一行（或是文件结尾）。

例如：

Here is an example of AppleScript:

    tell application "Foo"
        beep
    end tell

实际效果为：

Here is an example of AppleScript:

tell application "Foo"
    beep
end tell

代码区块中，一般的 Markdown 语法不会被转换。

表格

用一空行包围表格。
不要缩进表格。
用 | 包裹表格的每一行。
竖直对齐所有表格边框。
将标题和内容用连字符分割，用对齐的 |。
| 周围必须要有一个空格，除非是外部的 |。
列的宽度通过列中最长的单元格确定。

Before.

| h    | Long header |
|------|-------------|
| abc  | def         |
| abc2 | def2        |

After.

分隔线（水平横线）

在一行中用三个及以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。也可以在星号或是减号中间插入空格。

* * *

***

*****

---

---------------------------------------

书写风格建议

使用 --- 来建立分割线（水平横线）

区段元素

链接

Markdown 支持两种形式的链接语法： 行内式和参考式两种形式。

但是，不管是哪一种，链接文字都是用 [方括号] 来标记。

行内式

在方块括号后面紧接着圆括号并插入网址链接，如果想要加上链接的Title 文字，在网址后面，用双引号把Title文字包起来即可。

例如：

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

以上两句语法最终生成如下：

<p>This is <a href="http://example.com/" title="Title">
an example</a> inline link.</p>

<p><a href="http://example.net/">This link</a> has no
title attribute.</p>

如果要链接到同域的资源，可以使用相对路径：

See my [About](/about/) page for details.

参考式

参考式的链接是在链接文字的括号后面再接上另一个方括号，而在第二个方括号里面要填入用以辨识链接的标记：

This is [an example][id] reference-style link.

也可以选择性地在两个方括号中间加上一个空格：

This is [an example] [id] reference-style link.

接着，在文件的任意处，把这个标记的链接内容定义出来：

[id]: http://example.com/  "Optional Title Here"

链接内容定义的形式为：

方括号（前面可以选择性地加上至多三个空格来缩进），里面输入链接文字
接着一个冒号
接着一个以上的空格或制表符
接着链接的网址
选择性地接着 title 内容，可以用单引号、双引号或是括弧包着

注意：网址定义只有在产生链接的时候用到，并不会直接出现在文件之中。

下面这三种链接的定义都是相同：

[id]: http://example.com/  "Optional Title Here" //建议书写此格式
[id]: http://example.com/  'Optional Title Here'
[id]: http://example.com/  (Optional Title Here)

链接网址也可以用方括号包起来：

[id]: <http://example.com/>  "Optional Title Here"

也可以把 title 属性放到下一行，也可以加一些缩进，若网址太长的话，这样会比较好看：

[id]: http://example.com/longish/path/to/resource/here
      "Optional Title Here"

链接辨别标签可以有字母、数字、空白和标点符号，但是并不区分大小写，因此下面两个链接是一样的：

[link text][a]
[link text][A]

隐式链接标记

隐式链接标记功能可以省略指定链接标记，这种情形下，链接标记会视为等同于链接文字，要用隐式链接标记只要在链接文字后面加上一个空的方括号，例如将 "Google" 链接到 google.com，你可以简化成：

[Google][]

然后定义链接内容：

[Google]: http://google.com/

书写风格建议

参考样式链接

使用隐式链接
```
[a][]
```
定义必须写到文件末
必须以ID字符顺序排列
不要使用尖括号包裹URL
只用小写书写，小写可读性比大小写混合单词大很多
标题使用双引号

格式对齐

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

[google]: http://google.com/        "Google"
[yahoo]:  http://search.yahoo.com/  "Yahoo Search"
[msn]:    http://search.msn.com/    "MSN Search"

强调

星号 * 和底线 _ 是作为标记强调字词的符号。

用一个星号 * 和底线 _ 包围的字词为斜体。
用两个星号 * 和底线 _ 包围的字词为粗体。

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

效果为：

single asterisks

single underscores

double asterisks

double underscores

注意：

如果星号 * 和底线 _ 两边都有空白的话，它们就只会被当成普通的符号。
如果要在文字前后直接插入普通的星号或底线，可以用反斜线：
```
\*this text is surrounded by literal asterisks\*
```
效果如下：

*this text is surrounded by literal asterisks*

书写风格建议

加粗

使用双星号格式: **bold**

斜体

使用单星号格式: *italic*

代码

标记一小段行内代码，用反引号 ` 把它包起来
```
Use the `printf()` function.
```
使用多个反引号 ` 来开启/关闭代码区段
```
```
Use the `printf()` function.
```
```

书写风格建议

使用三个反引号 ``` 来开启/关闭代码区段
总是指定代码的语言。例如：
```
```php
$a = 1;
```
```

图片

图片标记和链接的语法很相似，同样也允许两种样式：行内式和参考式。

行内式

[图片上传失败...(image-f9c27f-1521786491657)]

[图片上传失败...(image-2a173b-1521786491657)]

语法定义：

一个惊叹号 !
接着一个方括号，里面放上图片的替代文字
接着一个普通括号，里面放上图片的网址，最后还可以用引号包住并加上选择性的 'title' 文字。

参考式

![Alt text][id]

[id]: url/to/image  "Optional title attribute"

另外，Markdown 无法指定图片的宽高，如果需要的话，可以使用普通的 <img> 标签。

其他

自动链接

用尖括号将网址或电子邮件地址包起来以创建自动链接

<http://example.com/>

所有自动链接必须以字串 http 开始。

反斜杠

利用反斜杠来插入一些在语法中有其它意义的符号。

例如用星号加在文字旁边的方式来做出强调效果

\*literal asterisks\*

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号：

\   反斜线
`   反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

Markdown 语法手册&书写风格建议（完整整理版）

兼容HTML

HTML标签知识补充

HTML块级元素

HTML内联元素

生成目录

区块元素

段落和换行

书写风格建议

标题

书写风格建议

引用

书写风格建议

列表

无序列表

书写风格建议

有序列表

书写风格建议

代码区块

表格

分隔线（水平横线）

书写风格建议

区段元素

链接

行内式

参考式

隐式链接标记

书写风格建议

参考样式链接

强调

书写风格建议

加粗

斜体

代码

书写风格建议

图片

行内式

参考式

其他

自动链接

反斜杠

参考资料

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

markdown编辑器