Dice! 论坛发帖语法指南

Hikari Sakurai

Dice! 发帖语法指南

使用《署名—非商业性使用—相同方式共享 4.0 协议国际版》（CC BY-NC-SA 4.0）进行授权
https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.zh-Hans

Dice! 社区由溯洄建立并维护，使用了开源的 Flarum 框架进行构建。

在使用时可能注意到，尽管发帖提供了可视化编辑区，但是设定相应格式后会出现一些标记。尽管简单编辑时并不会造成太大问题，但如果你想发表自己的帖子（尤其是机器人交流区和牌堆发布区），你可能需要进行一定的排版以保证界面的美观以及阅读的便利性。

为让更多人能写出自己想要的排版效果，在此介绍发帖涉及到的语法（即 MarkDown 语法）供发帖参考。

请注意：本帖所述语法并非唯一，你也可以用其他支持语法格式发表你的帖子。

本帖采用 CC BY-SA-NC 4.0 协议进行许可，其详细信息请参见署名—非商业性使用—相同方式共享 4.0 协议国际版

Hikari Sakurai

主要内容

本贴的目录结构如下，如果你不想看这么多东西，你可以直接跳转到”怎么使用“一节

Markdown 是什么？

谁创造了它？

为什么 要使用它？

怎么使用？
4.1 基本语法
4.2 扩展语法

尝试一下

Hikari Sakurai

1. MarkDown 是什么

Markdown 是一种轻量级标记语言，它以纯文本形式 (易读、易写、易更改) 编写文档，并最终以 HTML 格式发布。

Markdown 也可以理解为将以 MARKDOWN 语法编写的语言转换成 HTML 内容的工具。

Hikari Sakurai

2. 谁创造了它？

它由 Aaron Swartz 和 John Gruber 共同设计， Aaron Swartz 就是那位有着开挂一般人生经历的程序员。

维基百科对他的介绍是：软件工程师、作家、政治组织者、互联网活动家、维基百科人。

Hikari Sakurai

3. 为什么要使用它？

MarkDown 具有如下优势：

它是易读（看起来舒服）、易写（语法简单）、易更改的纯文本。处处体现着极简主义的影子；
兼容HTML，可以转换为 HTML 格式发布（不过出于一些原因，论坛并不支持 MarkDown 可用的 HTML 标签）；
跨平台使用；
越来越多的网站支持 Markdown；
更方便清晰地组织你的电子邮件（Markdown-here, Airmail）；
~~摆脱 Word~~。

当然，如果你并非程序员，这种格式对你来说或许最大的用途就是在论坛发表更美观的帖子。当然，一个更为实用的用途是记笔记和总结（至少雨笙的笔记就是使用 MarkDown 进行整理的）。

Hikari Sakurai

4. 怎么使用它？

如果不考虑扩展，Markdown 的语法绝对简单到让你爱不释手。

当然，在论坛发帖，你一般也不需要考虑拓展语法。

Markdown 语法主要分为如下几大部分：
标题，段落，区块引用，代码区块，强调，列表，分割线，链接，图片，反斜杠 \，符号 ‘`’。

下面将对这些语法进行逐一介绍，准备好了吗？

4.1 基本语法

从这里开始列出了 John Gruber 定义的 Markdown 语法，包括：

段落与换行
标题
引用
列表
代码和语法高亮
分隔线
超链接
图像
强调
字符转义

Hikari Sakurai

4.1.1 段落与换行

段落是正常的在 Word 中操作的方法，使用回车换行即可。

不同格式（语法）段落的前后要有空行，所谓的空行是指没有文字内容。虽然很多时候不换行并不会导致什么问题，但是为了避免可能的排版混乱，请尽量遵守此项。

例如，给定这样的一组代码，你现在可能还不明白其中一些语法的含义，但是没有关系，看完这篇文章相信你会理解它们。

> 使用《署名—非商业性使用—相同方式共享 4.0 协议国际版》（CC BY-NC-SA 4.0）进行授权
> https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.zh-Hans

------

**基本信息：**
- **作者：**Azusa
- **联系方式：**AzusaHikari@outlook.com
- **版本：**v3.0.2
- **更新日期：**2020/6/23
- **简介：**韵律源点 Arcaea 曲目合集，或许可以用作 Arcaea 竞技？
- **关键词：**`arc` `韵律源点` `韵律源点曲目` 以及各个曲包
- **许可协议：**CC BY-NC-SA 4.0

------

你应该看到的是这样的效果：

使用《署名—非商业性使用—相同方式共享 4.0 协议国际版》（CC BY-NC-SA 4.0）进行授权
https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.zh-Hans

基本信息：

作者：Azusa

联系方式：AzusaHikari@outlook.com

版本：v3.0.2

更新日期：2020/6/23

简介：韵律源点 Arcaea 曲目合集，或许可以用作 Arcaea 竞技？

关键词：arc 韵律源点 韵律源点曲目 以及各个曲包

许可协议：CC BY-NC-SA 4.0

（这里的蓝色底纹并不会出现，仅仅是为了表示一个区域，后同）

注意：

段落的前后必须是空行，空行指的是行内什么都没有，或者只有空白符（空格或制表符）。

Markdown 中的多数区块（见后）都需要在两个空行之间。

Hikari Sakurai

4.1.2 标题

（1） atx 格式

使用 # ，可表示1-6级标题。

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

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

（2） Setext 格式

你也可以在编辑器中使用=和-标记一级和二级标题，但是这样的形式不一定被网站所兼容，请复制到网站时手动修改为上面的格式。

一级标题
====

二级标题
----

效果：（由于意料之外的原因，此处展示效果并没有蓝色底纹）

一级标题

二级标题

注意：

= 和 - 的数量是没有限制的。通常的做法是使其和标题文本的长度相同，这样看起来比较舒服。或者可以像我一样，用四个 - 或 =。

Setext 形式只支持 h1 和 h2 两种标题。

Hikari Sakurai

4.1.3 区块引用

在段落的每行或者只在第一行使用符号 > ，还可使用多个嵌套引用，如：

> 区块引用  
>> 嵌套引用

区块引用

嵌套引用

注意：

如果仅在第一行使用 >，后面相邻的行即使省略 >，也会变成引用内容

在引用中可以使用使用其他任何 Markdown 语法

Hikari Sakurai

4.1.4 列表

使用 · 、 + 、或 - 标记无序列表，如：

- 第一项
- 第二项
- 第三项

注意：标记后面最少有一个空格或 制表符 。若不在引用区块中，必须和前方段落之间存在空行。

第一项

第二项

第三项

有序列表的标记方式是将上述的符号换成数字，并辅以 . ，如：

1. 第一项
2. 第二项
3. 第三项

第一项

第二项

第三项

注意：

无序列表和有序列表可以随意相互嵌套

无序列表项的开始是：符号空格；

有序列表项的开始是：数字 . 空格；

空格至少为一个，多个空格将被解析为一个；

如果仅需要在行前显示数字和 . ：
　　01\. 可以使用：数字\. 来取消显示为列表
　　01. 可以使用：数字. 来取消显示为列表

\* 的语法专门用来显示 Markdown 语法中使用的特殊字符，参考后文的 字符转义

Hikari Sakurai

4.1.5 代码和语法高亮

一般来说，为了方便寻找可能出现的问题，代码要求使用等宽字体，即半角字符宽度相等的字体。

尽管一般来说在发帖时并没有使用等宽字体的必要，但是在一些情况下或许使用等宽字体可以带来更美观的排版（但是，请勿滥用这个机制）。

（1）行内代码

可以通过 ``插入行内代码（这个符号是 Tab 键上边、数字 1 键左侧的那个按键）

（2）代码块

代码区块以 ``` 起始，并换行输入你的代码。此外，同样需要换行输入 ``` 表示代码块的终止。如：

``` 
#include <stdio.h>

main() {
  printf("hello world\n");
}
```

#include <stdio.h>

main() {
printf("hello world\n");
}

（3）语法高亮

在上面的代码块的语法基础上，在第一组 ``` 之后添加代码的语言，如 C++，Python，Java 等，可将代码标注为对应的语言：

```C
#include <stdio.h>

main() {
  printf("hello world\n");
}
```

#include <stdio.h>

main() {
printf("hello world\n");
}

注意：

代码块必须和普通段落之间存在空行。

代码块中的文本（包括 Markdown 语法）都会显示为原始内容，而特殊字符会被转换为 HTML 字符实体。

Hikari Sakurai

4.1.6 分割线

可以在一行中使用三个或更多的 *、- 或 _ 来添加分隔线：

***
------
___

效果：

多个字符之间可以有空格（空白符），但不能有其他字符：

* * *
- - -

效果：

Hikari Sakurai

4.1.7 链接

链接可以由两种形式生成：行内式和参考式。我们建议使用结构更简单的行内式进行添加。

（1）行内式：

[link text](URL 'title text')

① 普通链接：

[Dice! 官方站-QQ跑团掷骰机器人](https://kokona.tech/)

Dice! 官方站-QQ跑团掷骰机器人

② 指向本地文件的链接：

[icon.png](./images/icon.png)

icon.png

③ 包含 ‘title’ 的链接（鼠标移动到链接上会显示 “title” ）：

[Dice! 官方站-QQ跑团掷骰机器人](https://kokona.tech/ "Dice! 官方站")

Dice! 官方站-QQ跑团掷骰机器人

（2）参考式：

参考式链接的写法相当于行内式拆分成两部分，并通过一个 识别符 来连接两部分。参考式能尽量保持文章结构的简单，也方便统一管理 URL 。

① 首先：定义链接：

[Dice! 官方站-QQ跑团掷骰机器人][link]

Dice! 官方站-QQ跑团掷骰机器人

第二个方括号内为链接独有的 识别符，可以是字母、数字、空白或标点符号。识别符是 不区分大小写 的；

② 然后定义链接内容：

[link]:https://kokona.tech/ "Dice! 官方站"

其格式为： [识别符]: URL 'title'。

③ 也可以省略 识别符，使用链接文本作为 识别符：

[Dice! 官方站-QQ跑团掷骰机器人][]
[Dice! 官方站-QQ跑团掷骰机器人]:https://kokona.tech/ "Dice! 官方站"

Dice! 官方站-QQ跑团掷骰机器人

注意：

在参考式中，URL可以使用 <> 包括起来，title 可以使用 ""、''、() 包括（考虑到兼容性，建议使用引号），title 部分也可以换行来写。并且，链接内容的定义可以放在同一个文件的 任意位置；

如果你正在使用 VS code 或 Typora 等编辑器，上述的 [link]:https://kokona.tech/ "Dice! 官方站" 不出现在区块中。

Hikari Sakurai

4.1.8 图片

插入图片的语法和插入超链接的语法基本一致，只是在最前面多一个 !。也分为行内式和参考式两种。

行内式：

![Arcahv](https://wiki.arcaea.cn/images/b/b3/Songs_arcahv.jpg "Arcahv")

参考式

![Arcahv][arcahv]
[arcahv]:https://wiki.arcaea.cn/images/b/b3/Songs_arcahv.jpg "Arcahv"

来自溯洄的说明：

论坛有几种图片显示格式，分别为

默认上传: [upl-image-preview url=URL]
提供下载按钮: [upl-image url=URL]
MarkDown格式: ![](URL)
BBCode格式: [img]URL[/img]

从样式上来讲，1,3,4基本等同，2有一个下载按钮，可以根据需求进行选择
如果需要对图片大小进行限制，你只能使用语法4，具体限制方法为 [img height=高度 width=宽度]URL[/img]
请在图片大小过大时进行缩放

Hikari Sakurai

4.1.9 强调

使用 * * 或 _ _ 包括的文本会表现为斜体：

      这是用来 *演示* 的 _文本_

　　　这是用来演示的文本

使用 ** ** 或 __ __ 包括的文本会表现为加粗：

      这是用来 **演示** 的 __文本__

　　　这是用来演示的文本

使用 *** *** 或 ___ ___ 包括的文本会表现为粗斜体：

      这是用来 ***演示*** 的 ___文本___

这是用来演示的文本

用来包括文本的 * 或 _ 内侧不能有空白，否则 * 和 _ 将不会被转换（不同的实现会有不同的表现）：

      这是用来 * 演示* 的 _文本 _

　　　这是用来 * 演示* 的 _文本 _

如果需要在文本中显示成对的 * 或 _ ，可以在符号前加入 \ 即可：

      这是用来 \*演示\* 的 \_文本\_

　　　这是用来 *演示* 的 _文本_

*、**、_ 和 __ 都必须成对使用。

Hikari Sakurai

4.1.10 字符转义

反斜线（ \ ）用于插入在 Markdown 语法中有特殊作用的字符。

这是用来 *演示* 的 _文本_
这是用来 \*演示\* 的 \_文本\_

这是用来演示的文本
这是用来演示的文本

这些字符包括：

\
`
*
_
{}
[]
()
#
+
-
.
!

Hikari Sakurai

4.2 扩展语法

MarkDown 标准本身所包含的功能有限，所以产生了许多第三方的扩展语法，如 GitHub Flavored Markdown。

这里只介绍众多扩展语法中的一部分内容，它们在不同平台或工具的支持程度不同，请参考具体工具的文档和说明来使用。

删除线
表格
公式
Task List

另外，CommonMark 试图将碎片化的 Markdown 实现和扩展进行标准化，提供统一的规范及不同语言的实现。

Hikari Sakurai

4.2.1 删除线

这就是 ~~删除线~~

这就是 ~~删除线~~

Hikari Sakurai

4.2.2 表格

警告：由于论坛框架问题，表格显示效果可能会很差，请避免使用表格。

（1）单元格和表头

使用 | 来分隔不同的单元格，使用 - 来分隔表头和其他行：

name | Authority
---- | ---------
Suhui | Admin
Shiki | Admin

name	Authority
Suhui	Admin
Shiki	Admin

为了美观，可以使用空格对齐不同行的单元格，并在左右两侧都使用 | 来标记单元格边界：

|    name    | Authority |
| ---------- | --------- |
|   Suhui    |   Admin   |
|   Shiki    |   Admin   |

name	Authority
Suhui	Admin
Shiki	Admin

为了使 Markdown 更清晰，| 和 - 两侧需要至少有一个空格（最左侧和最右侧的 | 外就不需要了）。

（2）对齐

在表头下方的分隔线标记中加入 :，即可标记下方单元格内容的对齐方式：

:--- 代表左对齐
:--: 代表居中对齐
---: 代表右对齐

| left | center | right |
| :--- | :----: | ----: |
| aaaa | bbbbbb | ccccc |
| a    | b      | c     |

left	center	right
aaaa	bbbbbb	ccccc
a	b	c

如果不使用对齐标记，单元格中的内容默认左对齐；表头单元格中的内容会一直居中对齐（不同的实现可能会有不同表现）。

（3）插入其他内容

表格中可以插入其他 Markdown 中的行内标记：

|     name     | Authority |                     GitHub                       |
| ------------ | --------- | ------------------------------------------------ |
|   _Suhui_    |   Admin   | [w4123](https://github.com/w4123)                |
|  __Shiki__   |   Admin   | [mystringEmpty](https://github.com/mystringEmpty)|

name	Authority	GitHub
Suhui	Admin	w4123
Shiki	Admin	mystringEmpty

Hikari Sakurai

4.2.3 公式

请注意，在本论坛，公式的定界符与大部分编辑器的语法要求不同，因此本处不介绍编辑器中插入公式的定界符。

另请注意：由于论坛框架限制，直接输入下述定界符会无视代码块格式，因此在下述代码块中与 [] 相邻的字符均添加了空格以避免被转义，

MarkDown 中可以使用 \LaTeX 语法编辑公式，关于 \LaTeX 的数学公式语法，请参见 amsmath 包使用手册。

一个可供使用的在线 \LaTeX 公式编辑器是 LaTeX公式编辑器，提供了可视化输入面板。

（1）行内公式

在论坛中，行内公式的定界符为 [imath] [/imath]，你的公式应该在这两个定界符之间。

这是行内公式：[ imath ] \text{sin} 2 \alpha =2 \text{sin}  \alpha  \text{cos}  \alpha  [ /imath ]

这是行内公式： \text{sin} 2 \alpha =2 \text{sin} \alpha \text{cos} \alpha

（2）行间公式

在论坛中，行内公式的定界符为 [math] [/math]，你的公式应该在这两个定界符之间。

这是行间公式：[ math ] \text{sin} 2 \alpha =2 \text{sin}  \alpha  \text{cos}  \alpha  [ /math ]

这是行间公式： \text{sin} 2 \alpha =2 \text{sin} \alpha \text{cos} \alpha