极光社区的所有编辑器(提问、写文章)均支持 Markdown 语法,社区中的 Markdown 对一些写法做了兼容,譬如输入 URL 地址和邮箱后,会自动变成可点击的链接。本文内容根据社区编辑器的实际效果,并参考这篇文章写成。

一、兼容 HTML

不在 Markdown 涵盖范围之内的标签,都可以直接用 HTML 撰写。

  1. 在 HTML 区块元素――比如<div>、<table>、<pre>、<p>等标签间的 Markdown 格式语法将不会被处理。比如,你在 HTML 区块内使用 Markdown 样式的**加粗**会没有效果。如下示例,在 HTML 表格里面用 Markdown 语法的 ** 不会有加粗效果:

    <table>
    <thead><tr><th>标题</th><th>标题</th></tr></thead>
    <tbody>
     <tr>
         <td>**极光**</td><td>社区</td>
     </tr>
     <tbody>
    </table>

    预览效果如下:

    标题标题
    **极光**社区
  2. HTML 的区段(行内)标签如<span>、<cite>、<del>、<a>可以在 Markdown 的段落、列表或是标题里随意使用,且 Markdown 语法在 HTML 区段标签间是有效的,譬如给链接的文字加粗:

    <a href="https://community.jiguang.cn/">**极光社区**</a>

    预览效果如下:
    极光社区

二、标题

Markdown 支持两种标题的语法,类 Setext 和类 atx 形式。

类 Setext 形式是用底线的形式,利用 = (最高阶标题)和 - (第二阶标题),任何数量都有效果:

一阶标题
=

二阶标题
-------------

类 Atx 形式则是在行首插入 1 到 6 个 # ,对应到标题 1 到 6 阶:

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

注:极光社区会自动选取文章中的一阶标题和二阶标题作为目录进行展示,但如果只有二阶标题,没有一阶则不展示目录。

三、区块引用

使用符号 > 进行引用:

  1. 段落引用时,在第一行最前面加上 > 即可

    >开发者可以轻松地通过极光发送各个移动平台的系统通知,还可以在控制台编辑多种富文本展示模板; 极光还提供自定义消息的透传,客户端接到消息内容后根据自己的逻辑自由处理。
  2. 引用可以嵌套(引用内的引用),根据层次加上不同数量的 > 即可

    >极光推送
    >>多种消息类型
    >>>开发者可以轻松地通过极光发送各个移动平台的系统通知,还可以在控制台编辑多种富文本展示模板; 极光还提供自定义消息的透传,客户端接到消息内容后根据自己的逻辑自由处理。
  3. 引用的区块内可以使用其他的 Markdown 语法,包括标题、列表、代码区块等

    ># 标题:极光推送产品功能
    >
    >1. 有序列表1:多种消息类型
    >2. 有序列表2:用户和推送统计
    >
    >推送的代码示例:
    >```
    >{
    >    "platform": "all",
    >    "audience": "all",
    >    "notification": {
    >           "android": {
    >            "alert": "Hi,JPush!",
    >            "title": "Send to Android",
    >        }
    >    }
    >}
    >```

四、列表

有序和无序

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

  1. 无序列表使用星号 *、加号 + 或是减号 - 作为列表标记,三者的效果是等同的,注意在符号后需要空格:

     * 多种消息类型
     * 用户和推送统计
       * 用户统计
       * 推送统计
     * 短信补充
  2. 有序列表则使用数字接着一个英文句点和空格:

     1. 多种消息类型
     2. 用户和推送统计
     3. 短信补充

在列表标记上使用的数字并不会影响输出的 HTML 结果,数字的顺序打乱或使用同样的数字,都会得到完全相同的 HTML 输出

在列表项目中增加段落、引用、代码

  1. 列表项目可以包含多个段落,每个项目下的段落都必须缩进 1 个空格或是 1 个制表符:

     1. 多种消息类型
     开发者可以轻松地通过极光发送各个移动平台的系统通知,还可以在控制台编辑多种富文本展示模板; 极光还提供自定义消息的透传,客户端接到消息内容后根据自己的逻辑自由处理。
     2. 用户和推送统计
  2. 在列表项目内放进引用, > 需要缩进至少 1 个空格:

     1. 多种消息类型
     >开发者可以轻松地通过极光发送各个移动平台的系统通知,还可以在控制台编辑多种富文本展示模板; 极光还提供自定义消息的透传,客户端接到消息内容后根据自己的逻辑自由处理。
     2. 用户和推送统计
  3. 在列表项目内放进代码区块,需要缩进两次(8 个空格或者 2 个制表符):

     1. 推送消息代码
             {
                 "platform": "all",
                 "audience": "all",
                 "notification": {
                         "android": {
                         "alert": "Hi,JPush!",
                         "title": "Send to Android",
                         }
                 }
             }

避免形成列表的方法

当在行首出现数字-英文句点-空格,但不需要形成列表样式时,可以在句点前面加上反斜杠:

2018\. 极光上市
2019\. 极光社区新版上线
2020\. 新年快乐

五、代码与代码区块

如何标记

  1. 如果要标记一小段行内代码,可以用反引号把它包起来(`),例如:

    使用`"platform": "all",`表示推送给所有平台(Android、iOS、winphone)
  2. 如果要标记一大段换行的代码段,可以用三个反引号把它们包起来(```),例如:

     ```
     {  
         "platform": "all",
         "audience": "all",
         "notification": {
                 "android": {
                 "alert": "Hi,JPush!",
                 "title": "Send to Android",
                 }
         }
     }
     ```
  3. 缩进 4 个空格或是 1 个制表符可以建立代码区块,一个代码区块会一直持续到没有缩进的那一行(或是文件结尾)

使用技巧

  1. 在代码区块里面, & 、 < 和 > 会自动转成 HTML 实体,你可以复制粘贴上用作范例的 HTML 原始码,再加上缩进就可以了,例如:

     <a href="https://community.jiguang.cn/">极光社区</a>

    代码区块中,一般的 Markdown 语法不会被转换,譬如 * 就只是星号,我们可以很方便地以 Markdown 语法撰写 Markdown 语法相关的文件,就像本文对 Markdown 语法的示例一样。

  2. 如果要在代码区段内插入反引号(让反引号显示出来),你可以用多个反引号来开启和结束代码区段;在代码区段的起始端后面和结束端前面放一个空格,这样可以在区段的一开始就插入反引号:

    ``在这里(`)插入一个反引号``
    `` `"platform": "all",` ``

六、分隔线

在一行中用三个以上的星号、减号、底线来建立一个分隔线,行内除了空格外不能有其他东西。下面每种写法都可以建立分隔线:

***
* * *
------
_ _ _ _

七、链接

Markdown 支持两种形式的链接语法: 行内式和参考式。它们的链接文字都是用 [方括号] 来标记。

  1. 要建立一个行内式的链接,只要在方块括号后面紧接着圆括号并插入网址链接即可。

    [极光社区](https://community.jiguang.cn/)
  2. 参考式的链接是在链接文字的括号后面再接上另一个方括号,而在第二个方括号里面要填入用以辨识链接的标记,然后在文件的任意处(一般在段落后,或者文件末尾),把这个标记的链接内容定义出来:

     [极光社区][id]
    
     [id]: https://community.jiguang.cn/

链接辨别标记 id 可以有字母、数字、空白和标点符号,对字母不区分大小写

八、强调(斜体、加粗、删除、下划线)

  1. 使用 1 个星号(*)和底线(_)将文字包起来,会形成斜体:

     *极光社区*
     _极光社区_
  2. 使用 2 个星号(*)和底线(_)将文字包起来,会形成加粗:

     **极光社区**
     __极光社区__
  3. 使用 2 个波浪号(~)将文字包起来,会形成删除线:

     ~~极光社区~~
  4. 使用<u></u>标签可以形成下划线:

     <u>极光社区</u>

九、图片

图片和链接一样,支持行内式和参考式两种语法

  1. 行内式:

    ![推送统计截图](https://img.jiguang.cn/jiguang/20180929/assets/img/funcion-img-2.png)
  2. 参考式:

     ![推送统计截图][id]
    
     [id]<img class="emoji" src="https://community.jiguang.cn/images/emoji/twitter/https.png" />//img.jiguang.cn/jiguang/20180929/assets/img/funcion-img-2.png

十、表格

在 Markdown 中,使用 | - 可以形成表格,列之间使用 |,首行与第二行之间用 - 分隔开来,如下所示

| 极光 | 极光官网 | 极光社区 |
| -------- | -------- | -------- |
| jiguang  | jiguang.cn | community.jiguang.cn |
| 品牌 | 网站首页 | 社区首页 |

效果如下:

极光 极光官网 极光社区
jiguang jiguang.cn community.jiguang.cn
品牌 网站首页 社区首页

十一、插入符号

可以利用反斜杠来插入一些在语法中有其它意义的符号,例如:如果你希望显示出的是星号而不是将文字变成斜体/粗体,可以通过在星号的前面加上反斜杠来实现

\*\*极光社区\*\*
\*极光社区\*

效果如下:

**极光社区**
*极光社区*

支持在以下这些符号前面加上反斜杠来帮助插入普通的符号:

\   反斜线
`   反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号