markdown语法以及GitHub Flavored Markdown介绍

Markdown适合干什么

提供简单高效的文档编写方式,文档编写同时使用标记符排版,文档结构同经过解析后的呈现效果相似,也就是说它一种所见即所得的文档编写方式,鉴于标记符的简单,不仅使得经过解析后内容具有简洁的排版效果,而且源文档本身的结构清晰易于理解,很适合于书写简洁轻量级的文档。总之,有一句话来说,Markdown是一门用于结构化文本内容交流的简单易用的标记语言。

Markdown不是HTML

相较于HTML,Markdown只提供了少量的标记用于内容的组织和排版,当然Markdown解析器可以将Markdown转换为HTML代码,同时你可以在Markdown源码中混合使用HTML标签。

**注:**html中的块级标签(div,table,pre,p)等可以在markdown源码中使用,但是存在的限制是块级开始标签和结束标签与markdown内容要用空行隔开,并且块级标签前面不能有缩进,并且在块级标签中的任何markdown源码不会被转换器进行转换处理,会原样输出(行内标签不存在这个问题)

**注:**网页中要想显示html保留字符(&, <, >)必须使用相应的实体字符( &amp;,&lt;,&gt;,但是在markdown中你可以直接使用html保留字符(也可用实体字符),markdown解析器会将其转换为实体字符的,所以显示的还是保留字符本身(当然,在使用html标签时,解析器可以识别标签而不会直接显示标签的)

Markdown扩展

Markdown的基本语法是非常有限的,一些网站(如:github)和软件(如:Pandoc)出于使用需求对Markdown语法进行了扩展,比如对表格显示的支持等。

**注:**不同的扩展实现之间是互不兼容的

Markdown基本语法

块级元素

段落

对应html中的<p>标签,语法:前后有一个以上空行的若干连续文本行被当成一个段落

注:

  1. 如果紧挨的是块级元素,前后没必要有一个以上的空行

  2. 空行指的是仅有空格,制表,换行符的行

  3. 源码中连续文本行中的制表,多个空格,换行符等连续空白都将被显示为一个空格,也就是说源码中段落首行的缩进以及文本中插入的换行都不会达到你预期的效果,首行缩进是不被推荐的,至于要段落强制换行,可通过在要换行的地方插入两个上空格再按下回车实现(其实质是解析器会在这个地方插入一个<br/>标签)

标题:

对应html中的<h*>标签,两种语法,使用#作为内容开头或者用=或-为内容添加底线

**注:**使用#时,出于美观的目的常常给内容尾部也添加#(数量无所谓),=用于h1,-用于h2(数量无所谓)

块引用:

对应html中的<blockquote>标签,语法:以>开头的文本行

注:

  1. 如果被引用的内容符合段落语法(即是连续的文本行),那么可以使用块引用的简写语法,你只需要在段落首行前用>标记即可,当然你若不嫌费事你也可标记每行文本

  2. 一个块引用是可以分段的,其实就是将每段的首行前添加>

  3. 块引用是可以嵌套的,每深一层嵌套则增加一个>,比如:»,»>等

  4. 块引用中的内容别的markdown语法都有效

示例:

这是一个块引用的内容段落,它为什么要用这种奇怪的语法呢?

那你得问问它的创始人了,可是你不知到谁是创始人,麻烦呀!

这还是块引用不过已经是另一个段落了,另一个段落?是呀!就好比有人跟你说

你已经到了另一个国家一样,对就是这样的

嘿嘿,嵌套嵌套嵌套,我就是恶心的嵌套,我还有一个名字就做递归

函数递归,什么?没听过,看来你不是一个真正的程序员

躲在世界最为幽静角落的代码:pass

代码块

对应html中的<pre>标签,语法:每行代码内容缩进1tab或4空格直到结束

**注:**代码块中的对字符<,>,&的处理符合markdown常规处理逻辑,即还是显示它们自己,并且在代码块中html标签也是会显示为自己的而不会发生html作用,代码块中除了对实体字符显示的markdown语法有效其他语法均无效,正是利用代码块的这个特性,你可以在代码块中显示markdown源码

示例:

<div class="foo">

    2014 xiaowenbin

</div>

import httpClient

def test():

    app = httpClient("https")

    result = app.fetch("www.google.com")

    return result

我已经不是代码了

列表:

对应html中的<ul>和<ol>标签,语法:

  • 无序列表的项使用*,+,-加空格开头标记

  • 有序列表的项使用number.加空格开头标记

注:

  1. 每个标记对应一个列表项,且标记到行首可以有少于等于3个空格

  2. 一个列表项中可以有若干个段落(用空行隔开的文本行),各段落的第一行必须缩进1tab或4空格

  3. 列表项之间如果用空行隔开则列表项的内容被<p>标签包裹

  4. 如果普通文本行内容以列表项标记开头可以使用转义符\,对标记进行转义,例:\*, 1998\.

  5. 列表项中使用块引用时,块引用部分上下都用空行隔开,且>要缩进1tab或4空格

  6. 列表项中使用代码块时,代码块部分上下都用空行隔开,且代码块要缩进2tab或8空格,注:直接写代码就可以了,无需什么特殊标记

示例:

  • 第一个列表项,仅仅是一个简单的列表项

  • 第二个列表项,含有若干个段落

    这里是列表项的第一段落的第一行

这是第一段落的第二行

这里是列表项的第二段落的第一行  

这是第二段落的第二行

  • 第三个列表项,放一个块引用:

    这是块引用内容,将块引用内容

    放在列表中

  • 第四个列表项,放代码块:

      def test():
    
          pass
    
  • 第五个列表项,我有一个子列表

    • 子列表项1

    • 子列表项2

分隔线

对应html中的<hr>标签,语法:上下有空白行,一行中含有三个以上的*或-,行内可以有空格,但不能再有别的内容

**示例:**真正切切的分割线


行内元素

超链接

对应html中的<a>标签,语法:

直接定义链接,[link](http://blog.wikty.com "this is link title")

引用定义链接,[reference-link][linkid]

定义被引用链接,[linkid]: http://blog.wikty.com "this is link title"

注:

  1. 直接定义链接,就是在源码定义链接的位置直接显示链接

  2. 定义引用链接的出发点在于,有的链接可能会在页面中使用很多次,每次都通过直接定义很麻烦,所以你可以在页面任意处定义被引用的链接,之后使用引用语法使用它

  3. 其实引用链接的定义语法较为宽松,上面只是其中的一种而已

  4. linkid是不区分字母大小写的

  5. 在引用链接时linkid可以留空,这意味着你在引用以reference-link作为id的链接定义

  6. 推荐将引用链接的定义放在使用链接的段落后面或者整个文件的最后面

示例:

(为了方便查看每个超链接都是用空行隔开形成段落,超链接本身是行内元素是不会换行的)

普通超链接

含有title属性

我的站点

google

强调

对应html中的<strong>和<em>标签,语法:单个*或_包裹转换为<em>,两个*或_包裹转换为<strong>

注:

  1. 加粗和斜体是可以嵌套的

  2. 标记符号和内容之间不能有空格

代码行

对应html中的<code>标签,语法:使用反引号包裹内容

注:

  1. 如果你打算在代码中插入反引号,则你可以使用多个反引号包裹代码行

  2. 定界的反引号和代码行内容之间可以插入空格

  3. 代码行中的<, >, &都会直接显示

示例:

yeild x,y: return x*y

Markdown要点

  1. markdown中使用块级html标签时,要同markdown内容用空行隔开并且标签内的任何markdown语法均无效

  2. html中的保留字符(<, >, &)在markdown中会被转换为实体字符后原样显示

  3. 段落中强制换行的语法是插入两个以上空格后按下回车

  4. 块引用的分段和嵌套

  5. 代码块和代码行中所有的内容原样显示(html的保留字符,html标签,markdown的标记符),这样才能保证代码块内容可以放置html代码和markdown代码,并且代码块要用空行和周围隔开

  6. 在markdown源码中,使用markdown标记符和直接使用标记符对应的html标签的区别在于,使用html标签则内容不会被markdown解析器处理

  7. 列表项中使用多个段落,每个段落首行缩进4空格

  8. 列表项中使用引用,引用标记符缩进4个空格

  9. 列表项中使用代码块,代码块整体缩进8个空格

  10. 列表的嵌套,使用4个空格对子列表嵌套,有序和无序都一样

  11. 分隔线与周围内容要使用空白行隔开

  12. 利用超链接语法创建页面中的锚点,点击这里回到页首[gohome](./#pagehead)

GFM: Github Flavored Markdown

  1. GFM中不将_包裹的内容视为强调语法,因为github会处理很多跟代码有关的东西,而变量名中含有_是很常见的

  2. 虽然markdown中提供了链接,邮箱的快捷写入方式,但是GFM提供的方式更为简洁,只需直接写入即可转换为链接形式

  3. 因为说明代码变动是删除标记很有用,所以GFM对中划线(删除线)提供了支持,用~~包裹内容

  4. GFM对代码块提供了新的语法支持,传统markdown中通过整体4空格的缩进来标明代码,GFM中为了避免多写缩进,提供了'‘‘包裹内容来表示代码块,并且你可以在开始标记后面紧跟代码的语言名,可以进行高亮显示代码

  5. GFM提供了表格显示支持,用-分隔表头行和表体行,用|分隔列

     First Header  | Second Header
    
     ------------- | -------------
    
     Content Cell  | Content Cell
    
     Content Cell  | Content Cell
    
     | First Header  | Second Header |
    
     | ------------- | ------------- |
    
     | Content Cell  | Content Cell  |
    
     | Content Cell  | Content Cell  |
    
     | Name | Description          |
    
     | ------------- | ----------- |
    
     | Help      | Display the help window.|
    
     | Close     | Closes a window     |
    
     | Left-Aligned  | Center Aligned  | Right Aligned |
    
     | :------------ |:---------------:| -----:|
    
     | col 3 is      | some wordy text | $1600 |
    
     | col 2 is      | centered        |   $12 |
    
     | zebra stripes | are neat        |    $1 |
    
  6. 在传统markdown语法中,段落认为是连续的文本行,通常情况下这些连续文本整体是写成一行的,这样在显示时会跟据空间布局进行伸缩,如果要强制换行的话需要使用插入br的语法(即行尾添加两个以上空格后在换行,如果直接插入换行符将导致换行符替换为空格,这完全扭曲了写作者的意图),GFM中对此进行了改进,直接插入的换行在显示时就是一个换行

  7. GFM对列表进行了增强,提供了任务列表的概念, 其实就是在渲染显示时在每个列表项的前面添加了checkbox用以表示该项任务是否已经完成(有序,无序列表都可以用以改进),并且任务列表是允许嵌套的

     - [x] this is a complete task
    
     - [ ] this is an incomplete task
    
  8. 创建的引用会被自动转换为链接

     * SHA: 17bb13a686306dd0e95428d89311e45342532db0
    
     * User@SHA: mojombo@17bb13a686306dd0e95428d89311e45342532db0
    
     * User/Repository@SHA:
    
     * mojombo/jekyll@17bb13a686306dd0e95428d89311e45342532d
    
     * #Num: #1
    
     * User#Num: mojombo#1
    
     * User/Repository#Num: mojombo/jekyll#1
    
  9. 在github中一些符号具有特殊的作用,留待以后研究:r, :, @, #

Xiao Wenbin
Xiao Wenbin
Natural Language Processing Engineer

My research interests include machine learning, information retrieval and natural language processing.

Related