SoTap Wiki

# Markdown 教程

Markdown 是一种标记语言，萌生于程序员社区，但与代码没有任何直接联系。

利用 Markdown，你可以在纯文本的情况下表达出多种在富文本下才能有的格式，例如粗体、斜体、下划线、删除线和标题等格式。Markdown 可以用于所有支持 Markdown 的网页（例如本 Wiki 和类似的网站、G 点论坛、GitHub 等）。Markdown 是一种潮流，在将来将会有越来越多的网站支持 Markdown。

Markdown 有许多分支，他们之间最主要的区别是拓展语法不一样。不同的分支之间都有一个共同的基本语法，在这个基本语法上拓展出新语法从而形成了分支。本教程中将会介绍通用的基本语法以及一点点 GitHub Flavored Markdown（GFM，一种由 GitHub 提出的 Markdown 分支）语法。

# 基本格式

基本格式包括粗体、斜体、下划线、超链接和删除线，它们的表示方法如表所示。

Markdown 语法 效果
**粗体** 或 __粗体__ 粗体
*斜体* 或 _斜体_ 斜体
<u>下划线</u> 下划线
[链接文本](链接网址) 链接文本
~~删除线~~ 删除线

实际使用中，将其相关的符号与相应的文字相结合即可。例如，如果想要表达粗体，则可以使用两个星号将粗体文本围住，就像这样

这是**加粗的**、*斜着的*和<u>划上线的</u>。[点我跳转到百度](https://baidu.com)。SoTap 也许是~~同性~~交友社区。

TIP

效果

这是加粗的、斜着的和划上线的。点我跳转到百度 (opens new window)。SoTap 也许是同性交友社区。

对于链接，「链接文本」指的是表面上显示出来的文本，而「链接指向」指的是点击以后要跳转到的网站地址。

# 标题

在 Markdown 中，标题分为 6 级，最常用的有 3 级，在这里我们仅介绍前三级。级数越低表示标题的等级越高，字号越大。它们的写法是

# 一级标题

## 二级标题

### 三级标题

依此类推，最多可到六级

需要注意的是在表达级数的 # 号之间不可空格，在标题的内容与 # 号之间必须空格。下面两种表达都是不正确的。

#一级标题

# # # 三级标题

有些网站支持这种错误的表达，但为了能够让自己写的 Markdown 文本在所有网站上都能使用，请尽量避免这样的错误表达。

# 列表

列表分为有序列表和无序列表两种。有序列表的每一项前面都标有数字，且依次递增，称之有序；无序列表每一项前面没有数字。写法为

1. 我是有序列表的第一项
2. 我是有序列表的第二项
3. 我是有序列表的第三项

-   我是无序列表的第一项
-   我是无序列表的第二项
-   我是无序列表的第三项

TIP

效果

  1. 我是有序列表的第一项
  2. 我是有序列表的第二项
  3. 我是有序列表的第三项
  • 我是无序列表的第一项
  • 我是无序列表的第二项
  • 我是无序列表的第三项

注意事项：

  1. 有序列表和无序列表每一项前面的标记与文本之间必须空格。1.我是有序列表的第一项 或者 -我是无序列表的第一项 均无效。
  2. 有些网站允许有序列表的数字打乱，例如第一项前面可以写成 9. 而不是 1.，这并不影响最终的效果。
  3. 无序列表前面的标记除了 - 外也可以使用 + 或者 *，但不推荐混用。

# 代码

Markdown 中的代码分为两类，一类是类似于 这样 的代码块，使用 ` 将内容包围起来即可（这个符号在键盘左上角 Esc 的下面）。

另一类是用于放置较多代码内容的代码区域：

#include <iostream>
using namespace std;

int main() {
    cout << "Hello World!" << endl;
    return 0;
}

它的写法是这样的：

```cpp
#include <iostream>
using namespace std;

int main() {
    cout << "Hello World!" << endl;
    return 0;
}
```

用大于或等于三个 ` 开头，且在开头的 ` 后面加上编程语言的名称，再用相同数目的 ` 结尾。

注意事项：

  1. 语言名称处填写的代码块内包含的语言的英文全写或缩写。
    对于 Java、Python、PHP 等英文名称的语言，可以直接小写以后作为语言名称，写作 java、python、php。而对于 C++、C# 等名称中带有符号的语言，应使用英文代替。例如 C++ 写作 cpp（pp 代表 plus plus，++ 的意思）、C# 写作 csharp（sharp 代表井号 #）。
  2. 如果不写语言名称或者语言名称写错，显示上不会有问题，但是没有语法高亮。

WARNING

在文段前空四个空格也可以表示相同的含义，但不推荐这种用法。这一用法会导致希望在段落前面空格的人的文本格式错乱。

请使用 &emsp; 来表示空一格。空 格则写作 个 &emsp;。不要省略末尾的半角分号 ;。

例如：

&emsp;&emsp;这行文字前空了两格&emsp;这里又空了一格

TIP

效果

  这行文字前空了两格 这里又空了一格

# 引用块

引用块用来表达一段文字或者一句话是引用而来的：

引用内容

在引用内容中，可以使用所有的样式，比如这样：

在这里，可以使用粗体、斜体等格式。

写法：

> 引用内容
> ...

引用内容只需要一个 > 号作为开头，与它紧挨着的几行均会被认为是引用，直到遇到另一个段落：

> 我是引用内容
我也是引用内容
我也是引用内容

> 如果不嫌麻烦
> 你也可以每一行
> 都加上 > 号

我是下一段的正文

在某些情况下，你或许需要到嵌套的引用内容，就像这样：

我是一个一级嵌套内容

我是一个二级嵌套内容

嵌套的引用内容写法：

> 我是一个一级嵌套内容
>
> > 我是一个二级嵌套内容

# 图片

表达图片的方式和超链接类似，只需要在 [] 前面加上一个英文感叹号 ! 即可。

![图片名称(选填)](图片地址)

例如：

![](https://mcsunrise.oss-cn-qingdao.aliyuncs.com/sunrise.png)

TIP

效果

一个图片中也可以包含一个超链接，就像这样一张图片，点击之后将跳转到 SoTap 官网。

写法上，将超链接的文本内容 [] 内换成图片即可：

[![](https://mcsunrise.oss-cn-qingdao.aliyuncs.com/sunrise.png)](https://sotap.org)

注意事项：

  1. 图片的地址是通过将图片上传到图床（用来存放图片的地方）得到的，点击这里查看上传的相关内容。
  2. 「图片名称」（也就是 ![图片名称](xxx) 的 [] 里的内容）最终并不会显示在文档里，而是会在鼠标放置到图片上后显示出来。如果需要为图片添加位于正下方的注解，请参考下文的图片注解。

# 图片注解

WARNING

图片注解是我们通过额外的 CSS 实现的，在其它地方并不通用！

若要为一个图片添加注解，在图片的表达后插入斜体样式即可。例如

![](https://mcsunrise.oss-cn-qingdao.aliyuncs.com/sunrise.png) _我是注解的内容_

TIP

效果

我是注解的内容

# 表格

一个表格分为表头和表体两个部分，Markdown 中的表格指定这两个部分即可创建。一个最简单的表格（）长这样：

这里是表头
这里是表体

表格的表达大概是这样的：

|       表头 1       |       表头 2       | ... |
| :----------------: | :----------------: | :-: |
| 第一列第一行的内容 | 第二列第一行的内容 | ... |
| 第一列第二行的内容 | 第二列第二行的内容 | ... |

Markdown 中使用 |（这个符号在 enter 键的上方，与 \ 同键位）来分隔表格的列。

  • 第一行定义了表头，它确定了这个表格的列数。有多少个表头就有多少列。
  • 第二行用于规定此表格的对齐方式，可以是左对齐、居中和右对齐三种。对齐方式需要在每一个表头下面写一遍，比如表头有两个：| 我是第一个 | 我是第二个 |，那么第二行中就必须写成 | :-: | :-: | 这样的两个对齐方式。每一列的对齐方式可以不同。
对齐方式 写法
左对齐 | :- |
右对齐 | -: |
居中 | :-: |
  • 从第三行开始是此表格的表体。第三行是此表格的表体的第一行，以此类推。

上面的例子的效果如下：

TIP

效果

表头 1 表头 2 ...
第一列第一行的内容 第二列第一行的内容 ...
第一列第二行的内容 第二列第二行的内容 ...

注意事项：对齐方式中间只需要有大于或等于一个 - 就行。 |:------:| 等价于 |:-:|。

# 拓展用法

拓展用法中的格式可能不适用于所有支持 Markdown 的网页。下文编写的内容均可以在本 Wiki 上使用。

# 色块

色块有助于将一部分信息独立出来或者加以强调。在这里共有三种颜色的色块，其重要程度排序为：红色 黄色 绿色。

TIP

我是绿色色块

WARNING

我是黄色色块

WARNING

我是红色色块

其写法与代码区域类似

:::tip
我是绿色色块
:::

:::warning
我是黄色色块
:::

:::danger
我是红色色块
:::

每一对三冒号之间的区域就是该色块的范围。在该区域内可以使用任意 Markdown 语法，其最终都会被包含在该色块下。

# 上标和下标

上标和下标是使用 <sup> 和 <sub> HTML 标签实现的，在一般的 Markdown 中写作 <sup>我是上标</sup> 和 <sub>我是下标</sub>。

在本 Wiki 上你可以使用 ^我是上标^ 和 ~我是下标~ 这两种用法。

H~2~O KMnO~4~ E=mc^2^

TIP

效果

H~2~O KMnO~4~ E=mc^2^

# LaTeX 公式

LaTeX 可以让你写出优美的公式，在这里我们提供了简单的支持。使用方法是将公式内容用 $ 包围。

$\forall a \in \mathbb{N}_+, \mathrm{H_2O}, pV=nRT, E=mc^2, \int^a_bf(x)\mathrm{d}x, \alpha\beta\gamma\theta\delta\epsilon$

$\gt \lt \geq \leq = \simeq \sim + - \times \div$

TIP

效果

# 脚注

你可以为文章添加脚注。先将脚注标注在文章的某一特定位置，然后再挑选一个任意位置添加其内容。最终解释的内容会被放在文末。具体格式为

我是需要被注释的话[^1]

[^1]: 我是解释的内容

TIP

效果

我是需要被注释的话[1]

点击注释角标可以跳转到文末的相应解释处，相应解释处也可以点击 ↩︎ 符号返回到注释角标处。

# 常用 HTML 标签

一些高级的格式不能使用 Markdown 实现，但可以用 HTML 来实现。下面列出了一些常用的 HTML 标签实现的高级格式及其基本写法。

# 缩写

  • 解释 — 缩写文本的下方会有虚线的下划线，将鼠标放置在上方会显示全称。例如：WHO
  • 写法 — <abbr title="解释内容">文本</abbr>

# 注音

  • 解释 — 注音会出现在文本的上方。例如：SoTap 是一个对 LGBT 友好的圈子同性交友群
  • 写法 — <ruby>正文<rt>注音</rt></ruby>

# 黑幕

WARNING

此用法为本 Wiki 自定义，不是标准的 HTML 写法，请注意区分。

  • 解释 — 黑幕会在文本上显示一层黑色，需要用户手动操作才能看见其内容。例如 这叫刮刮乐，酷不酷 和 我 100% 确定你现在把鼠标放了上来
  • 写法 — 分为两种
    • A 类：必须用鼠标选中文本才会显示。写法为 <b a>内容</b>
    • B 类：必须将鼠标放在黑幕上才会显示。写法为 <b b>内容</b>

更多高级用法待补。

# 杂项

# 嵌套列表

两种列表都支持嵌套，效果如下：

  • 无序列表项
    • 无序列表嵌套项
    • 无序列表嵌套项
      • 无序列表嵌套项
    • 无需列表嵌套项
  • 无序列表项
  • 无序列表项
  1. 有序列表嵌套项
  2. 有序列表嵌套项
    1. 有序列表嵌套项
      1. 有序列表嵌套项
      2. 有序列表嵌套项
      3. 有序列表嵌套项
    2. 有序列表嵌套项
  3. 有序列表项嵌套项

写法也很简单，每一个标记前空两格或四格即可：

-   无序列表项
    -   无序列表嵌套项
    -   无序列表嵌套项 - ...
        -   无序列表嵌套项
    -   无序列表嵌套项
-   无序列表项
-   无序列表项

1. 有序列表项
    1. 有序列表嵌套项
        1. 有序列表嵌套项
        2. 有序列表嵌套项
        3. ...
    2. 有序列表嵌套项
2. 有序列表项
3. 有序列表项

理论上支持无限的嵌套，但是为了排版美观，我们一般只用到三层。

# 转义

既然 **粗体** 代表粗体，那么该如何显示它原本的面目「**粗体**」而不被加粗呢？这就需要用到转义字符。Markdown 中的转义字符为 \，其紧跟着的任何符号都会被视为与 Markdown 语法无关。因此，我们可以这样写

这里的\*\*粗体\*\*不是**粗体**

TIP

效果

这里的**粗体**不是粗体

注意事项：

  1. 转义字符可以转义它本身。可以理解为，\\ 代表正文中的一个 \。
  2. 一个转义符只能转义一个特殊字符。例如 \** 中就有一个 * 没有被转义。
  3. 代码块自带转义功能，一些特殊字符放进去以后不会被显示出来。例如 `**粗体**` 不需要用到 \ 就能显示出原始的字符。

使用例：

  1. MC 中的一些带有下划线 _ 的名字，比如 Majesty_W、123__jk 中的 _ 会有干扰，因此显示出来时需要用到 \_ 来转义，或者直接放到代码块里面。
  2. 一些颜文字，比如 ^_^，也会受到干扰，正确的写法应该是 \^\_\^。

# 换行

Markdown 不存在换行的概念，取而代之的是段落的概念。比如下面这种写法是没办法换行的：

我是第一行
我是第二行

TIP

效果

我是第一行 我是第二行

你会发现这两行连在了一起。如果你要将两行内容分离开来，中间再空一样，就像这样：

我是第一段

我是第二段

# HTML 支持

Markdown 内可以直接嵌入 HTML 代码，但这一功能由于拓展性过强且具有安全性问题，在许多网站上被禁止。不过在本 Wiki 项目内，你仍然可以无限制地使用 HTML 代码。

  1. 我是解释的内容 ↩︎

← ID 皮肤制作指南 →