MarkDown语法小结

MarkDown语法小结

by 终曲 2019.3.1

1. 关于MarkDown

Q1 ： 什么是MarkDown

Markdown 是一个 Web 上使用的文本到HTML的转换工具，可以通过简单、易读易写的文本格式生成结构化的HTML文档

Q2 : MarkDown有哪些特点

易读易写 是Markdown的宗旨，MarkDown尽量减少书写内容中的标签，命令，使得的文件更加接近于纯文本，这样在记录文本内容时，可以更加专注于书写内容，而不是标签和命令

2. 简单语法

tips：本文只记录MarkDown的简单语法，内容基对于官方文档的理解，如有疑问，请查看官方文档 ，官方文档（英文）欢迎纠错讨论

2.1 区块元素

2.1.1 段落和换行

一个 Markdown 段落是由一个或多个连续的文本行组成, 它的前后要有一个以上的空行（空行的定义是显示上看起来像是空的，便会被视为空行。比方说，若某一行只包含空格和制表符，则该行也会被视为空行）。普通段落不该用空格或制表符来缩进。

标准 Markdown 不支持自然换行（literal new line），有些渲染器扩展支持自然换行。由于渲染效果各异，书写时建议使用标准语法以达到最佳兼容效果。
MarkDown换行机制

1. 使用Html或MarkDown的块元素时，自动换行，如<div> 或 分割线
2. 使用</br>强制换行（不建议）
3. MarkDown识别到 空行（当一行内只含制表符和换行符时，将会被识别为空行，多个空行仅会换一行）
4. 让MarkDown为你添加</br>标签（操作为段尾加两个以上空格+回车）

不符合换行机制的，将会被当做连续内容处理

2.1.2 标题

Markdown 支持两种标题的语法，类 Setext（支持2级） 和类 atx（支持6级）
形式
Setext 写法

最高级标题(h1)  
===
 
二级标题（h2)  
---   

换行后在下一行连续加入三个或以上的 = 或者 - 即可声明标题等级

atx 写法

# 这是一级标题（H1，通常用于文档标题）  
## 这是二级标题（H2，有些渲染器会为二级标题添加 hr 底线）  
### 这是三级标题（H3）  
#### 这是四级标题（H4）  
##### 这是五级标题（H5）  
###### 这是六级标题（H6）

实际操作中，可以选择性的对##标签进行闭合处理（如果你觉得美观），行尾的#数量也不用和开头一样（行首的井字符数量决定标题的阶数）

#和标题内容之间（不论是开头还是结尾），需保留至少一个空格

# 这是 H1 #
## 这是 H2 ##
### 这是 H3 ######

2.1.3 区块引用

在引用内容前加 > 符号即可，建议使用引用前插入一行空行

鲁迅 
> 这话我没说过

鲁迅

这话我没说过

如果引用内容分为多行，可以在引用内容每行的行首加入 > ,也可以偷懒只在引用内容的第一行加

鲁迅 
> 我即使是死了,钉在棺材里了,也要在墓里,用这腐朽的声带喊出  
> 这话我没说过

等同于

鲁迅 
> 我即使是死了,钉在棺材里了,也要在墓里,用这腐朽的声带喊出  
  这话我没说过

鲁迅

我即使是死了,钉在棺材里了,也要在墓里,用这腐朽的声带喊出
这话我没说过

2.1.4 列表

MarkDown支持有序列表和无序列表

无序列表

使用 * , + , - 作为列表标记

* 1
+ 2
- 3

效果为

• 1

• 2

• 3

有序列表

使用数字接着一个英文句点（句点与内容间加入一个或以上空格）

1.  第一行
2.  第二行
4.    第三行
3.    第四行

效果为

1. 第一行
2. 第二行
3. 第三行
4. 第四行

tips: 有趣的事情发生了，虽然文本中序列数写的是1243，但解析效果仍为1234，这是由于列表解析为Html的<ol>,<li>标签
解析后：

<ol>
<li>第一行</li>
<li>第二行</li>
<li>第三行</li>
<li>第四行</li>
</ol>

虽然如此，但是建议首行的序列号一定要填写正确，因为Markdown 可能会支持有序列表的 start 属性

列表嵌套

子列表写法

1.一级有序列表内容

   1. 二级有序列表内容1
      * 三级无序列表1
      * 三级无序列表2
      * 三级无序列表3
   2. 二级有序列表内容2
   3. 二级有序列表内容3

次一级列表比上一级多加三个空格（必须是3个空格）

效果
1.一级有序列表内容

1. 二级有序列表内容1
   • 三级无序列表1
   • 三级无序列表2
   • 三级无序列表3
2. 二级有序列表内容2
3. 二级有序列表内容3

(csdn有序列表中插入无序列表会有问题)

2.1.5 代码区块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落文件的方式去排版，而是照原来的样子显示，Markdown 会用 <pre> 和 <code> 标签来把代码区块包起来
在文档编写时，如需要显示代码原文，则需要构建一个代码区块，实际使用中有三种方法构建代码区块
方法1 使用缩进或制表符（官方推荐写法）
缩进 4 个空格或是 1 个制表符可以构建一个代码区块，区块范围至最后一次缩进或文件结尾

写法

区块外
    （空一行）
（四个空格或一个制表符）区块
（四个空格或一个制表符）区块

区块结束

效果

---

区块外

区块  
区块  

区块结束

---

tips：区块前要加入一行空行

方法2 使用三个 ` 标记区块范围（tap键上边，~键）
写法

```
区块  
```

效果

区块  

方法3 直接使用区块标签<pre>和<code>
写法

<pre><code>区块</code></pre> 

效果

区块

tips: 方法1其实就是转化成为了方法3的写法，其中<pre>标签创建区块范围，<code>标签维持区块内代码的转译

2.1.6 分割线与表格

分割线

三个或者三个以上的 - , * ,_ 都可以产生分割线(推荐使用 * )

---
----
***
*****
___
____

效果

---

---

---

---

---

---

表格

表头|表头|表头
-|:-:|-:
内容|内容|内容
内容|内容|内容

效果

表头	表头	表头
内容	内容	内容
内容	内容	内容

2.2 区段元素

2.2.1 链接

推荐写法

方法1 仅链接写法（行内式）
    [这是一个百度链接](https://www.baidu.com/) 

方法2 链接并显示title（行内式）
    [这是一个百度链接](https://www.baidu.com/ "链接并显示title")

方法3 链接并显示title（参考式）
    [这是一个百度链接][id]
    （空行）
    [id]: https://www.baidu.com/  "title为百度"

效果1

这是一个百度链接

效果2

这是一个百度链接

效果3

这是一个百度链接

2.2.2 强调（简单行内样式）

MarkDown的一些简单行内样式
Markdown 使用星号 * 和底线 _ 作为标记强调字词的符号，被 * 或 _ 包围的字词会被转成用 <em> 标签包围(斜体)，用两个 * 或 _ 包起来的话，则会被转成 <strong>（加粗）

*内容1*

_内容2_

**内容3**

__内容4__  

效果

内容1

内容2

内容3

内容4

tips：*和_必须与内容相接，如果你的 * 和 _ 两边有空白的话，它们就只会被当成普通的符号，如果内容中含有多个* 和 _可以用反斜杠 \ 将他转译普通符号

此外还有一些其他常用样式

***这是斜体加粗的文字***
~~这是加删除线的文字~~  

效果
这是斜体加粗的文字
这是加删除线的文字

2.2.3 代码

在行内显示小段代码，可以用反引号 ` 号包围代码

Use the `printf()` function.

效果

Use the printf() function.

使用两个反引号，也可以得到同样效果

Use the ``printf()`` function.

效果

Use the printf() function.

2.2.4 图片

类似于链接，图片也拥有行内式和参考式两种写法

推荐写法

方法1 图片（行内式）
    ![Baidu](img.png) 

方法2 图片并显示title（行内式）
    ![Baidu](img.png "Baidu")

方法3 图片并显示title（参考式）
    ![Baidu][Baidu]
    （空行）
    [Baidu]: img.png  "Baidu"

效果1

效果2

效果3

tips： Markdown 还没有办法指定图片的宽高，如果你需要的话，你可以使用普通的 <img> 标签

2.3 其他

2.3.1 转译问题

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

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

代码的转译可按情况使用<code>标签， 反引号 ` 包围，或直接生成一个代码区块

2.3.2 对Html的兼容

Html的元素内使用Md的标签将不会被处理，比如 *强调*
代码1

<table>
    <tr>
        <td>*content1*</td>
        *<td>content2</td>*
    </tr>
</table>

效果1

---

**

*content1*

content2

---

代码2

<p>*强调*</p>

效果2

---

*强调*

---

在Md标签中Html标签大部分都可以正常使用，使用纯Html标签也会生效
代码1

*<p>强调</p>*

效果1

---

强调

---

代码2

*<div>强调</div>*

效果2

强调

3.小结

由于想使用MarkDown来整理文档，本人主要参考官方文档对简单语法进行了整理，并进行了适当补充，相信本文内容已经足够完成大部分文档工作了，由于官方文档说明版本相对落后，可能出现小部分异同或缺漏，欢迎补充指正

by 累的要死的 终曲