Markdown使用中的注意事项

本文主要关注Markdown使用时的高级用法和一些容易出现问题的地方，Markdown的基础用法大家可以查看简书官方关于Markdown的指南。本文主要包含6个方面的内容:

一、空格的使用:

标题字符(#)，列表字符( - / + / * / 1. / 2.)，引用字符(>)和文本之间要保留一个字符的空格。这是最标准的 Markdown 写法。这会避免因为Markdown编辑器的差异而出现显示的效果不一致的情况出现。

• 标题字符(#):

  代码:

  # 一级标题## 二级标题### 三级标题#### 四级标题##### 五级标题###### 六级标题 

• 无序列表字符( - / + / * ):

  - 文本1+ 文本2* 文本3

• 有序列表字符(1. / 2. / 3.):

  1. 文本12. 文本23. 文本3

• 引用字符(>):

  > 引用文本

---

二、列表和代码块的对齐

（1）多级列表的对齐:

建立多级列表时，每个子级别都要比上个级别前面多打2个空格。

• 无序列表:

  - Item-1- Item-1-1  + Item-1-1-1    * Item-1-1-1-1* Item-1-2+ Item-2* Item-3

• 有序列表:

  1. Item-11.1. Item-1-1  1.1.1. Item-1-1-1    1.1.1.1. Item-1-1-1-11.2. Item-1-22. Item-26. Item-3

（2）一个列表内部多个段落的对齐:

对应列表中的包含多个段落时,该列表下对应的各个段落的开头都要与第一个段落的开头对齐,如下面的例子中Code Line 1,Code Line 2和Code Line 3的开头是对齐的.

* Item-1  * Code Line 1    Code Line 2    Code Line 3

编辑器解析的效果:

• Item-1
  
  • Code Line 1
    Code Line 2
    Code Line 3

（3）代码块的对齐

• 代码块内部的对齐:

  代码块使用字符构建时,文本的内容要与字符的位置对齐,如下面例子中的Code Line 1,Code Line 2和Code Line 3的开头都与字符的开头对齐了

  
Code Line 1
Code Line 2
Code Line 3


• 代码块与列表的对齐:

  在列表下的代码块字符的开头要与列表对应的段落开头对齐,比如下面这个例子对于Item-1.1下面的代码块,就是Item-1.1的开头与的开头对齐了

  • Item-1
    
    • Item-1.1
      
Code Line 1
Code Line 2
Code Line 3


---

三、网址链接的两种方式

Markdown关于添加图片和网址的语法很相似,只是插入图片的语法比插入网址前面多了一个感叹号”!”.它们都有两种插入方式,分别是:行内式和引用式(名字不重要,是我为了方便称呼自己取的)

注：Markdown不能设置图片的大小，如果必须设置，则应用HTML标记.

（1）行内式:

• 图片:

  [百度的图标](/path/to/img.jpg "Title(可以省略)")

• 网址:

  This is an link of [Google](https://www.google.com.hk).

（2）引用式:

• 图片:(显示链接中带括号的图片必须要使用引用式)

  ![百度的图标][id(id可以省略)]

• 网址:

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

---

四、脚注

脚注是在需要标记脚注文字的后面增加一个方括号，方括号中的内容必须以 ^ 开头，再接着是数字或字符串标记:

Footnotes[^1] have a label[^2] and a definition[^3].

接着，在文件的任意地方，可以把这个脚注的内容定义出来。脚注内容定义的形式就是前面引用的脚注的内容，接着一个冒号，再接着一个以上的空格，最后是脚注定义的内容：

[^1]: This is a footnote[^label]: A footnote on "label"[^!DEF]: The definition of a footnote.

Footnotes1have a label2 and a definition3.

---

五、分割线

注意:分割线要与上面的段落至少有一个空行，不然很容易导致上面一段被解析为标题。以下是原因：

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

  • Atx（注意#后面有个空格）

    # 一级标题## 二级标题### 三级标题

  • Setext（-与=数目任意，最好三个及以上，比较直观）

    一级标题======二级标题<hr />

• 在一行中使用三个或三个以上的*, - ,或 _ 可以添加分割线,中间插入空格,但是不能有其他字符.

以分割线要与上面的段落至少有一个空行，不然很容易导致上面一段被解析为标题。

---

六、流程图和序列图

（1）流程图

​```flowst=>start: Starte=>end: Endop1=>operation: My Operationsub1=>subroutine: My Subroutinecond=>condition: Yes or No?io=>inputoutput: catch something...st->op1->condcond(yes)->io->econd(no)->sub1(right)->op1​```

（2）序列图

​```sequenceAlice->Bob: Hello Bob, how are you?Note right of Bob: Bob thinksBob-->Alice: I am good thanks!​```

---

1. This is a footnote ↩
2. A footnote on “label” ↩
3. The definition of a footnote. ↩