维基文档风格指南

[suiyueou]

@TureeZhang

---

本文主要是对自己使用 Mrakdown 进行书写的一个笔记记录和总结。

因为碎月是个萌新，故而，如有错误或遗漏之处，还请各位大佬们指出！

---

创建发布时间：2020 年 1 月 24 日 23:42

最后更新时间：2020 年 7 月 6 日 13:37

Markdown 语法快速指南

什么是 Markdown？

Markdown 是一种通过少量简单的标记字符来格式化文本的方法，是一种轻量级的易用的书写语法。您可以用纯文本来书写文档，然后在阅读时呈现一个美观的排版。

其实目前并没有一个标准的 Markdown 语法文档，很多编辑器都会在基本语法上添加自己的扩展语法。所以，为了兼容性下方仅展示被广泛使用的基本语法。

如何上手 Markdown？

如果您是刚接触 Markdown， 那么比较好的一个方法是逐个学习 Markdown 语法。刚开始，懂得标题和强调语法就能够写出基本的文档；然后，您可以在书写的过程中不断学习和接触新的语法并不断练习，加强记忆。

语法指南

下面是被广泛支持的 Markdown 基本语法的一个概览。

标题

# 这是一个<h1>标签
## 这是一个<h2>标签
......
###### 这是一个<h6>标签

注意：

• # 之后需要至少一个空格。
• 一个标题应该独占一整行。

强调

*此文本为斜体*
_此文本为斜体_

**此文本为粗体**
__此文本为粗体__

***此文本为加粗斜体***
___此文本为加粗斜体___

例：

此文本为斜体 此文本为斜体

此文本为粗体 此文本为粗体

此文本为加粗斜体 此文本为加粗斜体

注意：

• 这边推荐使用 *，因为最常用。
• 如果渲染错误，请尝试在第一个 * 之前以及最后一个 * 之后添加一个空格。如果被标记的文本是以全角符号开始或结尾，一般都需要前后添加一个空格。

段落和换行

如果需要您一个新的段落，您应该先在一个段落的后面插入一个空行，然后才输入新的段落的文本。

如：

这是一个段落。

这是另一个段落。

例：

这是一个段落。

这是另一个段落。

注意：

• 您可直接按键盘上的 Enter 键插入空行，进入下一行。

• 一般来说，您应该在一个块元素（例如代码块、列表和块引用）后面插入一个空行来结束该元素。

列表

无序列表

* 项目 1

这是一段在 项目 1 下面的文字。

* 项目 2
    * 项目 2a
    * 项目 2b
* 项目 3

例：

• 项目 1

这是一段在 项目 1 下面的文字。

• 项目 2
  • 项目 2a
  • 项目 2b
• 项目 3

注意：

• # 之后需要至少一个空格。

• 使用一个空行来结束一个列表序列。

有序列表

1. 项目 1
1. 项目 2

注意，列表前面的数字序号其实是无关紧要的，渲染时 Markdown 会自动修改该序号。

3. 项目 3
    1. 项目 3a
    2. 项目 3b
4. 项目 4

例：

1. 项目 1
2. 项目 2

注意，列表前面的数字序号其实是无关紧要的，渲染时 Markdown 会自动修改该序号。

3. 项目 3
   1. 项目 3a
   2. 项目 3b
4. 项目 4

注意：

• 数字 之后需要至少一个空格。

• 使用一个空行来结束一个列表序列。

表格

| 表头 1 | 表头 2 | 表头 3 |
| - | - | - |
| 单元格 1 | 单元格 2 | 单元格 3 |
| 单元格 4 | 单元格 5 | 单元格 6 |

例：

表头 1	表头 2	表头 3
单元格 1	单元格 2	单元格 3
单元格 4	单元格 5	单元格 6

注意：

• Markdown 的表格默认为左对齐，在第二行 | - | 中的 - 右边加上 : 就右对齐，两边都加上就是居中。

  • | - |：左对齐
  • | -: |：居中对齐
  • | :-: |：右对齐

图片和链接

![图像文本,图片失效时显示](/url/to/image.png "可选文本,鼠标在图片上悬停时会显示")

![图像文本,图片失效时显示](https://www.***.com "可选文本,鼠标在图片上悬停时会显示")

[链接文本](/url/of/the/link)

[链接文本](https://www.***.com)

块引用

> 这是一个块引用示范。

例：

这是一个块引用示范。

注意

• > 标记后面至少需要一个空格。
• 多行连续的引用可以只在第一行添加标记。

代码块

~~
这是一个普通的代码块。
~~

~~lang
这是一个有代码高亮的代码块。
~~

``
这是另一个普通的代码块。
``

``lang
这是另一个有代码高亮的代码块。
``

注意：

• 因语法冲突，实际上上方代码块内两种实现代码块的 ~ 和 ` 个数均应为 3 个。
  • 如：~~~，```
• lang 用于指定代码块的代码语言并进行代码高亮，可选；如果不指定，Markdown 引擎不会尝试进行高亮代码。

例：~~~markdown：表示该代码块会使用 Mrakdown 的语法高亮规则对代码块内的文本进行高亮。

行内代码块

`这是一个行内代码块。`

在想包裹的文字两边输入 `，便可形成行内代码块。

例：这是一个行内代码块。

任务列表

- [x] 这是一个已完成的项目。
- [ ] 这是一个未完成的项目。

例：

• [x] 这是一个已完成的项目。
• [ ] 这是一个未完成的项目。

删除线

~~这是一个带删除线的文本。~~

例：

这是一个带删除线的文本。

分隔线

***

---

___

您可以在独立的一行中使用 3 个或以上的 *、 - 或 _ 来建立一个分隔线，行内不能有其他文本字符。

三种使用方法的实现效果是一样的，例：

---

Markdown 编辑器推荐

这里推荐两个好用的 Markdown 编辑器。

• VNote：一款开源且强大的更懂程序员和 Markdown 的笔记管理软件！Github 上的开源项目地址：vnote。
• Typora：简单但功能强大，无缝实时预览，所见即所得的免费编辑器。

参考资料

1. Mastering Markdown

[TureeZhang]

@suiyuebaobao

此文档需等待此前置 Issue 文章管理器#4 的开发结束，方可实现。开发进度请在 issue #4 跟踪。

因为目前所有文档是写死在数据库中的，暂时不支持动态创建文档并自定义文档 url 完成超链接跳转。

[TureeZhang]

维基贡献者指南已发布，关闭此 issue 。