Markdown语法

当前文档仅用作个人学习笔记，来源： Markdown 中文文档

• 概述

  • 设计理念

    Markdown 致力于使阅读和创作文档变得容易.

    Markdown 视可读性为最高准则.Markdown 语法灵感最大的来源还是纯文本 email 的格式。

    Markdown 完全由标点符号组成, 这些标点经过仔细挑选以使他们看上去和表达的含义相同。

  • 内联HTML

    对于 Markdown 中未包含的标签, 可以直接使用 HTML.

    没有必要使用定界符或标识符来表明从 Markdown 切换到 HTML; 直接使用标签就行了.
    唯一的限制就是对于 HTML 块级元素，eg：<div> <table> <pre> <p> and so on 必须另起一行独放，并且开始和结束标签前面不能有任何缩进。MD会自动识别而不会在额外添加 <p> 标签

    This is a regular paragraph.
    <table>
        <tr>
           <td>Foo</td>
           <td>Foo</td>
           <td>Foo</td>
        </tr>
        <tr>
            <td>Foo</td>
            <td>Foo</td>
            <td>Foo</td>
        </tr>
    </table>
    This is another regular paragraph.
    

  • 特殊字符自动转义

    在HTML中，< 和 & 字符需要特殊对待，
    &符号用于表示HTML字符实体，如果想将它们用作字面量，必须将它们转义为字符实体 < 和 & .

    在MP中可以自由地使用这些字符，这些字符在生成HTML时会被自动转义。

    由于MP支持内联HTML，如果使用 < 作为HTML标签的定界符，MP不会进行转义。但若写成：

    4 < 5
    

    MP会转义为：

    4 < 5
    

    In a word, Markdown 的块级元素和内联元素中, < 和 & 总是被自动编码. 这使得用 Markdown 来写 HTML 代码很容易.

• 块级元素

  • 段落与换行

    段落就是连续行上的文本, 一个或多个空行划分不同的段落。

    Markdown 支持 "硬换行".只需要在行尾加上两个及以上的空格, 然后换行.

  • 标题

    Markdown 支持两种形式的标题, [Setext][1] 和 [atx][2].

    Setext 样式的标题使用的等号来表示一级标题, 使用连字符表示二级标题.任意长度都是可以的

    This is an H1
    =============
    
    This is an H2
    -------------
    

    Atx 样式的标题每行开头使用 1-6 井号, 对应 1-6 级标题.
    可以可选地“关闭"atx样式的标题,"关闭"的含义是 # This is an H1 # 左右两边都有#(起始的井号数量决定了标题的级别.)

    # This is an H1
    
    ## This is an H2 ##
    

  • 块引用

    Markdown 使用 email 样式的 > 字符作为块引用

    1. 最好对引用文本采取强制换行并在每一行行首放一个 > :

       > 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.
       

    2. 可以简便地只在每一个需要强制换行的段落的首行前加 > :

       > 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.
       

    3. 块引用可以嵌套 (例如, 块引用中包含块引用) , 只需添加额外层级的 > 即可:

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

    4. 块引用可以包含 Markdown 元素, 包括标题, 列表和代码块:

       > ## This is a header.
       >
       > 1.   This is the first list item.
       > 2.   This is the second list item.
       >
       > Here's some example code:
       >
       >    return shell_exec("echo $input | $markdown_script");
       

  • 列表

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

    1. 无序列表使用 * + - ，这些符号是可以互换的

       * red
       * blue
       * green
       
       + red
       + blue
       + green
       
       - red
       - blue
       - green
       

    2. 有序列表使用数字加句号

       1. one
       2. two
       3. three
       

       注意这里的序号对最终生成HTML是没有影响的。

    3. 为了美观，可以使用悬挂缩进来格式化列表项

    4. 如果列表项中有空行，Markdown会在生成HTML输出中用 <p> 来包裹它们。

       *   bird
       
       *   cccc
       

    5. 列表项中包含多个段落，列表项中每个段落都必须用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.
       

    6. 列表项中包含块引用时，块引用标记 > 需要缩进

       *   A list item with a blockquote:
           
           > This is a blockquote
           > inside a list item.
       

    7. 如果列表项中有代码块，代码块需要双倍缩进，8个空格或2个水平制表符

       * A list item with a code block:
               <code goes here>
       

    8. 有时候无意中触发有序列表

       1986. What a great season.
       

       如果行开头满足 number-period-space 模式，可以通过转义 period 来避免这种情况

       1986\. What a great season.
       

  • 代码块

    预格式化的代码块用于输出编程语言和标记语言。不同于段落，代码块中的行会被原样呈现。Markdown会用 <pre> 和
    <code> 标签包围代码。

    要插入代码块，只需要将每一行都缩进4个空格或1个水平制表符。

    This is a normal paragraph:
        
        This is a code block.
    

  • 水平线

    如果一行中只有三个以上的连字符，星号，或下划线则会在该位置生成一个 <hr /> 标签。星号和连字符之间允许有空格。

    ***
    ------
    - - -
    ___         
    

    ---

• 内联元素

  • 链接

    Markdown 支持两种链接形式: 内联 和 引用。这两种形式下链接文本的定界符都是 [中括号]。

    创建内联链接

    1. 在链接文本的右中括号后紧跟一对圆括号

    2. 在圆括号内放URL链接，以及可选标题，标题要用引号包围。

    3. 引用相同服务器下的本地资源，支持相对路径。

        [链接文本](http://url.com/ "可选标题")
       

       链接文本

    创建引用链接

    1. 在需要使用引用链接的位置声明引用链接

    2. 定义链接标签(链接标签的名称可以包含字母，数字，空格，和标点符号。但不区分大小写)

        /*声明引用链接*/
        [引用链接][sign]
        
        /*定义链接标签*/
        [sign]: <http://example.com/> "Title"
       

       引用链接

    PS.可以隐含链接标签，这时链接文本本身充当链接标签。

    /*隐含链接标签案例*/
    [Google][]
    
    /*这时链接文本"Google"充当链接标签*/
    [Google]: <http://www.google.com> "谷歌"
    

    Google

  • 强调

    Markdown中 * 和 _ 作为强调标记。

    /*星号和文本连接处不能有空格,这里星号和下划线可以互换*/
    *单星号*
    
    **双星号**
    

    单星号
    双星号

    PS.若文本中要使用星号和下划线，则需要转义

  • 内联代码

    又称“代码片段”，与块级元素中的代码块对比区分记忆。

    Markdown中输出一个代码片段，使用反引号 ` 标记(键盘英文输入法情况下，ESC下来的一个按键)。

    1. 若文本中包含反引号符号，可以使用多个反引号符号作为起始和结束标记

        ``There is a literal backtick (`) here.``
       

    2. 也可以使用空格区分起始和结束标记

        `` ` ``
       

  • 图片

    Markdown 使用类似链接的语法来插入图片，包含两种形式： 内联 与 引用。

    语法：在引用的基础上加感叹号

        //内联方式
        ![Alt text](imgurl "title")
        
        //引用方式
        ![Alt text][id]         //声明
        [id]: imgurl "title"    //标签定义
    

    PS: Markdown没有语法指定图片大小，如果要指定图片size，可以使用HTML <img> 标签。

• 其它

  • 自动链接

    一种 “自动” 创建URL和Email地址链接的简短形式。

    //用尖括号包围即可
    <http://example.com/>
    

  • 反斜杠转义

    使用反斜杠可以转义Markdown的语法符号为字面量。

    \*星号包围文本，而不是要Markdown的强调语法\*