前言:之前项目组leader就要求用markdown来写一些产品说明文档,初次接触markdown当时确不知道是啥,写着感觉特别别扭,习惯了word排版形式,刚来接触这个一直不太习惯,跌跌撞撞好久都未曾理解所以然,所以花下心思想细细学习一番。看网上说markdown语法都很简单,但是个人经过理解后发现,要懂它还得花一段时间去适应一下,至于其好处,确实没发现多少,我个人倒是觉得很繁琐。不过大家推崇一定有其原因,还是赶潮流用用这个吧。
此文参照于Markdown语法说明(简体中文版),对于其中的说明一定要细细理解,亲身实践才算是真懂,看似简单,其实得花一些时间研究下,以下是笔记内容。
Markdown语法
段落和换行
一个 Markdown 段落是由一个或多个连续的文本行组成,在书写的时候它的前后要有一个以上的空行,在真正呈现的时候段落前后也是会有空行显示的,(空行的定义是显示上看起来像是空的,便会被视为空行。比方说,若某一行只包含空格和制表符,则该行也会被视为空行)。普通段落不该用空格或制表符来缩进。
「由一个或多个连续的文本行组成」这句话其实暗示了 Markdown 允许段落内的强迫换行(插入换行符),即两个空格加一个回车即可实现强制换行。
普通段落前后空行这点,是markdown的基础,隔了好久才发现这是非常有用的,可以避免很多奇怪的问题,(比如说段落后插入代码块,用tab键突然不灵了)总之,在markdown里重视段落这个东西,并且牢记一段段落前后总有空行,除非你实现强制换行除外。
代码区块及代码
- 代码块开始需要首行4个空格或者tab键,而采用“紧紧为其中的文字进行标记是代码标记。
- 代码区块会一直持续到没有缩进的那一行(或者文件的结尾)
- 代码区块–换行,由于第2条,所以换行只需要按空格键,在新一行按tab键,将新一行转成代码区块后,会和上一行做拼接,由此就达到换行效果。
- 代码区块中的markdown语法不会被转换,一般*号就是*号,不会被作为强调。
列表
- 列表内换行–两个空格加上一个enter键(其实可以等同于段落的换行)但是按了enter键之后下一行会自动加上列表编号,只需把列表编号删掉就可实现换行。
- 列表下如果想不用列表了,改为段落,则直接两下enter键即可实现段落的输入。总之,列表区域或者单个列表前后总是有一个空行的。
- 列表下的段落–列表下想要另外开辟一个段落,还属于当前列表段,每个段落前都必须缩进4个空格或一个制表符,这也解释了为什么在列表里插入代码块需要缩进8个空格或2个制表符,值得注意的是列表里的段落前后仍然应保持空一行的习惯。
列表嵌套
- 列表里嵌套列表–列表里需要嵌套,那么首行就必须要缩进。首先实现换行,然后缩进(即采取tab键)其次用列表符号即可。
- 列表里嵌套引用–同理,如果列表里需要嵌入引用,那么也需在首行缩进之后再输入引用的标记符号>。
列表里嵌入代码块,那么需要缩进2次,多嵌入一层,那么就需要多缩进一次。因为列表里另起一个段落需要缩进一次,再缩进一次即成为嵌入代码块。
值得注意的是,如果列表里嵌套的列表,那么3次缩进可以在里面一层列表产生代码块,但是外围一层列表貌似采用2次缩进无法产生代码块,只能通过代码块代码pre,code这样的标记产生代码块了。本质原因是因为2次缩进,是为内层的嵌套列表开辟新的段落,冲突了,所以产生代码块没有用。
分隔线
你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内不能有其他东西。如下的方式:
链接
Markdown 支持两种形式的链接语法: 行内式和参考式两种形式。不管是哪一种,链接文字都是用 [方括号] 来标记的。
要建立一个行内式的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可,如果你还想要加上链接的 title 文字,只要在网址后面,用双引号把 title 文字包起来即可,例如:
This is [an example](http://example.com/ "Title") inline link.
[This link](http://example.net/) has no title attribute.
这个链接示例jixu,如果你是要链接到同样主机的资源,你可以使用相对路径:
See my [About](/about/) page for details.
参考式链接参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记。比如下文:
This is [an example] [id] reference-style link.
然后你得在文中其它地方将其标注出来,如下标注此标注不能紧跟着段落内容中,需自成一行进行标记,一般可以放在文末进行标记:
[id]: http://example.com/ "Optional Title Here"
这种链接标记的形式值得注意:
- 方括号(前面可以选择性地加上至多三个空格来缩进),里面输入链接文字
- 接着一个冒号
- 接着一个以上的空格或制表符
- 接着链接的网址
- 选择性地接着 title 内容,可以用单引号、双引号或是括弧包着
实际使用参考式比较美观,但是相对比较麻烦,本人主要还是以行内式链接为主。
强调
Markdown 使用星号*和底线_作为标记强调字词的符号,被 * 或\ _ 包围的字词会被转成用 em 标签包围(即字体呈现斜体),用两个* 或_ 包起来的话,则会被转成 \strong标签包围(即字体加粗)
图片
Markdown使用一种和链接很相似的语法来标记图片,同样也允许两种样式:行内式和参考式。
行内式的图片语法看起来像是,和链接进行对比可以发现其实就是多了个感叹号,引用的方式也基本一样:
![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")
此种语法和链接其实是很想相似的。
参考式的图片语法则长得像这样:
![Alt text][id]
「id」是图片参考的名称,图片参考的定义方式则和链接参考一样,可以在文中的任意地方定义
[id]: url/to/image "Optional title attribute"
到目前为止,Markdown 还没有办法指定图片的宽高,如果你需要的话,你可以使用普通的 \img 标签。
反斜杠
通过反斜杠可以将一些需要强调的字符进行呈现,类似于代码里的转义字符,在本文中已经使用过很多转义了。