# Markdown语法说明

## 标题

### Setext方式

    标题1
    =================

    标题2
    -----------------

使用setext只能显示 `<h1>` 和 `<h2>` 级别标题。更多级别的标题，请使用Atx方式。

### Atx方式

    # 标题1
    ## 标题2
    ###### 标题6

或者可以在后面添加若干 `#` ，并且不一定要和前面的 个数 对应：

    # 标题1 #
    ## 标题2 #
    ###### 标题6 ##

示例：

###### 标题6

## 段落

可以把整个Markdown文档理解为由若干段落组成的块，块与块之间或者通过空行来区分，或者通过特殊的开始字符来区分。常见的块有：

- 代码段， 使用 ````` 或 `<code></code>` 来分隔，可以占多行；或者使用4个空格或1个制表符来缩近的文本段
- 标题，使用 `#` 开头，只占一行
- 列表，以 `*|+|-` + 空格 或 数字+`.`+空格为列表开始
- 引用块， 以 `<`+空格 开始
- 定义段
- 分隔线
- 表格
- HTML块
- 文本段，多行文本，每行不以上面特殊字符 `#`, `+`, `-`, `*` 等开始的文本行，遇到空行则结束

### 代码段

有几种定义方法

1. 使用 `<code>` 定义

       <code>
       import os
       </code>

   结果：

       import os

   `<code>` 和 `</code>` 要独占一行

2. 使用 ````` 来定义，同样 ````` 在前后都要独占一行。

       ```
       import os
       ```

   结果：

       import os

3. 使用缩近块，每行要缩近4个空格或1个制表符，中间可以有空行，如：

           import os

           os.path

   结果：

       import os

       os.path

### 引用

行首使用 `>` 加上一个空格表示引用段落，内部可以嵌套多个引用。

    > 这是一个引用，
    > 这里木有换行，
    >
    > 在这里换行了。
    > > 内部嵌套

结果为：

> 这是一个引用， 这里木有换行，

> 在这里换行了。

> > 内部嵌套

### 列表

#### 无序列表

无序列表使用 `*` , `+`, `-` 后面加空格来表示。列表可以嵌套，下一级的列表前面应缩近4个空格或1个制表符。

如：

    * a
    + b
    - c
        + c1
        + c2

结果：

- a
- b

- c

  - c1
  - c2

如果一行太长写不下，可以是多行，如：

    * a
       b c
    + b

结果：

- a b c
- b

在列表中可以嵌套其它的格式，如：

    * a **b** _c_

        ```
        import os
        ```
    * b

        > quote

结果：

- a b c

      import os

- b

  > quote

#### 有序列表

使用数字加英文句号加空格表示。

    1. Item 1
    2. Item 2
    3. Item 3

结果：

1. Item 1
2. Item 2
3. Item 3

### 分隔线

在一行中使用三个或三个以上的 `*`、`-` 或 `_` 可以添加分隔线，其中可以有空白，但是不能有其他字符。

如：

    * * * *
    ------
    __ __ __

结果：

### 定义段(par扩展)

生成如 `<dl><dt><dd>` 的格式。首行应顶格，首字符不能是其它段的开始字符，如 `*`, `+`, `-`, `#` ，最后以 空格+`--`结束。 第二行开始为缩近段。如：

    a --
        This is a definition

结果：

a

  This is a definition

### 表格(par扩展)

每行代表一个表格行，字段之间使用 `||` 分隔，如：

    ||a||b||c||
    ||a1||b1||c1||

结果：

a | b | c
a1 | b1 | c1

### HTML片段

首列以 `<` 开始的将视为HTML片段，如：

    <img src="/uploads/tutorial/10/ed7e964fcf1311e1b58bdd53d280702b.png">

结果：

### 文本段

文本段可以由多行文本组成，以空行作为一个段落的结束。首字符不能是特殊的段落开始符。除首行外，第二行可以前面有空格。如：

    This is a test
    paragraph.

    This is a test
        paragraph.

结果：

This is a test paragraph.

This is a test paragraph.

### Bootstrap 标签页(par扩展)

标签页是par项目做的一个Markdown语法上的扩展，需要在调用相应的解析时传入对应块的处理函数。目前已经在uliwebzone上支持了。定义格式为：

    {% tabs %}
    -- hello --
    ```
    This is a test
    ```
    -- world --
    * this is a list
    * test
    {% endtabs %}

结果：

    This is a test

- this is a list
- test

其中 `{% tabs %}` 和 `{% endtabs %}` 是标签开始和结束，各占一行。

每个Tab页，由标题和内容组成。标题形式为 `-- xxx --` ，前后各两个 `--` ，中间是标题名称。标题前后各有两个空格。

### Bootstrap 提醒(par扩展)

生成Bootstrap alert 的展示效果，格式为：

    {% alert class=success %}
    Success
    {% endalert %}
    {% alert class=error %}
    Error
    {% endalert %}
    {% alert class=info %}
    Info
    {% endalert %}
    {% alert %}
    Message
    {% endalert %}
    {% alert %}
    #### Alert Title
    This is alert message
    {% endalert %}
    {% alert class=info,close %}
    This is an alert. It'll has a close button.
    {% endalert %}

结果：

Success

Error

Info

Message

#### Alert Title

This is alert message

This is an alert. It'll has a close button.

## 行内标记

### 强调

有以下几种强调方式：

    单星号 = *斜体*
    单下划线 = _斜体_
    双星号 = **加粗**
    双下划线 = __加粗__
    三星号 = ***粗斜***
    三下划线 = ___粗斜___
    双波浪线 = ~~中划线~~
    尖号 = ^上标文本^
    双逗号 = ,,下标文本,,
    倒单引号 = `代码`

结果：

单星号/单下划线 | 斜体
双星号/双下划线 | 加粗
三星号/三下划线 | 粗斜
双波浪线 | 中划线
尖号 | 文本^上标文本^
双逗号 | 文本,,下标文本,,
倒单引号 | `代码`

### 代码标记

可以使用 `<code></code>` 或 ``` 来引用行内的代码。如：

    This is <code>test</code> and `test`.

结果：

This is `test` and `test`.

### 行内HTML标记

可以在行内直接使用HTML标记，如：

    这是 <b>行内</b> 标记。

结果：

这里 行内 标记。

### 链接

Markdown支持 行内 和 参考 两种定义方式。Uliwebzone扩展了直接识别链接的处理。

#### 行内形式

如：

    This is [an example](http://example.com/ "Title") inline link.

    [This link](http://example.net/) has no title attribute.

结果为：

This is an example inline link.

This link has no title attribute.

这种定义方式，首先要定义一个方括号，方括号内是链接显示的文本。后面跟着一个括号，是它对应的链接地址。同时还可以在后面跟一个 title 信息。

#### 参考定义

先如下定义：

    This is [an example][id] reference-style link.

然后在文章的任意位置定义：

    [id]: http://example.com/  "Optional Title Here"

结果：

This is an example reference-style link.

这种定义方式与行内方式不同之处在于，方括号后面的括号改为另一个方括号，其中跟着引用的id标识。 在文章的其它定义id标识信息，格式为：

- 方括号，里面输入连结入标识
- 接着一个冒号
- 接着一个以上的空白或 tab
- URL地址
- 可选地 title 內容，可以用单引号、双引号或是括号包围

下面几种形式都是相同的：

    [foo]: http://example.com/  "Optional Title Here"
    [foo]: http://example.com/  'Optional Title Here'
    [foo]: http://example.com/  (Optional Title Here)

### 图片

图片的写法和链接差不多，就是在前面多加一个 `!`

如：

    ![Test](/uploads/tutorial/10/ed7e964fcf1311e1b58bdd53d280702b.png)

结果：

### 直接链接

可以直接写一个链接或使用 `<` 和 `>` 包括链接，如：

    这是 http://google.com 的地址

    这是 <http://google.com> 的地址

结果：

这是 http://google.com 的地址

这是 的地址

## 字符转义

有些特殊符号如果要转义，可以在前面使用 `\` ,如：

    \\   反斜线
    \`   反引号
    \*   星号
    \_   底线
    \{\}  大括号
    \[\]  方括号
    \(\)  括号
    \#   井字号
    \+   加号
    \-   減号
    \.   英文句号
    \!   感叹号

结果：

- \ 反斜线
- ` 反引号
- * 星号
- _ 底线
- {} 大括号
- [] 方括号
- () 括号
- # 井字号
- + 加号
- - 減号
- . 英文句号
- ! 感叹号