Skip to content

Latest commit

 

History

History
584 lines (394 loc) · 9.71 KB

markdown.md

File metadata and controls

584 lines (394 loc) · 9.71 KB

OneBot Markdown 风格指南

本指南自 https://stdrc.cc/style-guides/markdown.html 修改而来。

标题

使用 ATX 风格的标题（1～6 个 # 号）

👍：

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

👎：

一级标题
=======

最后一个 # 后空一格，标题前后空一行

👍：

前一个段落的内容……

## 一个标题

下一个段落……

👎：

##一个标题
段落内容……

一篇文章中只应有一个一级标题

👍：

# 一个一级标题

## 第一个二级标题

Blahblah……

## 第二个二级标题

Blahblah……

👎：

# 一个一级标题

## 第一个二级标题

Blahblah……

# 又一个一级标题

Blahblah……

段落

段落开头顶格

👍：

这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。

这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。

This is the third paragraph. This is the third paragraph. This is the third paragraph. This is the third paragraph.

👎：

  这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。这是一个段落。

  这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。

  This is the third paragraph. This is the third paragraph. This is the third paragraph. This is the third paragraph.

段落和其它块级元素间空一行

👍：

## 一个标题

这是一个段落。这是一个段落。这是一个段落。这是一个段落。

- foo
- bar

这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。

> 一块引用内容

👎：

## 一个标题
这是一个段落。这是一个段落。这是一个段落。这是一个段落。
- foo
- bar
这是第二个段落。这是第二个段落。这是第二个段落。这是第二个段落。
> 一块引用内容

强调

使用一个、两个和三个 * 分别表示斜体、粗体和粗斜体

👍：

这是一个*斜体*；这是一个**粗体**；这是一个***粗斜体***。

👎：

这是一个_斜体_；这是一个__粗体__；这是一个___粗斜体___；这是一个**混用**。

链接

使用有意义的链接文本

👍：

OneBot 项目地址是 [howmanybots/onebot](https://github.com/howmanybots/onebot)。

👎：

点击 [这里](https://github.com/howmanybots/onebot) 查看 OneBot 项目。

使用 <> 快速创建链接

👍：

## 参考资料

- <https://google.github.io/styleguide/docguide/style.html>

👎：

## 参考资料

- [https://google.github.io/styleguide/docguide/style.html](https://google.github.io/styleguide/docguide/style.html)

链接两边加空格，标点符号除外

👍：

## 标题里的 [某某链接](https://stdrc.cc)

这是一个段落。这是一个段落。中间有个 [某某链接](https://stdrc.cc)。这是一个段落。这是一个段落。

👎：

## 标题里的[某某链接](https://stdrc.cc)

这是一个段落。这是一个段落。中间有个[某某链接](https://stdrc.cc)。这是一个段落。这是一个段落。

图片

不应在文字段落中插入大图

👍：

这是一个段落。这是一个段落。一个超大的图片如下：

![超大的图片](http://example.com/abc.jpg)

这是另一个段落。这是另一个段落。

👎：

这是一个段落。这是一个段落。中间有个 ![超大的图片](http://example.com/abc.jpg)。这是一个段落。这是一个段落。

可使用 HTML 实现图片居中

<p align="center">
  <img width="600" height="200" src="http://example.com/abc.jpg">
</p>

行内代码

行内代码两边加空格，标点符号除外

👍：

## 标题里的 `inline` 代码

这是一个段落。这是一个段落。中间有个 `inline code`。这是一个段落。这是一个段落。

👎：

## 标题里的`inline`代码

这是一个段落。这是一个段落。中间有个`inline code`。这是一个段落。这是一个段落。

为文件名、命令、程序代码等应以等宽字体显示的内容使用行内代码样式

👍：

编辑文件 `main.c`，然后运行命令 `gcc main.c`。

👎：

编辑文件 main.c，然后运行命令 gcc main.c。

链接文本中的代码也应使用行内代码样式

👍：

更多文档请参考 [`mmap`](https://man7.org/linux/man-pages/man2/mmap.2.html)。

👎：

更多文档请参考 [mmap](https://man7.org/linux/man-pages/man2/mmap.2.html)。

使用两个 ` 转义 ` 本身

使用两个 `` ` `` 转义 `` ` `` 本身，例如 ``Foo`Bar``。如果代码中只有 `` ` `` 这一个字符，需在两侧加空格。

代码块

使用 ``` 表示代码块

👍：

下面是一个代码块：

```python
def foo():
    pass
```

这是另一个段落。

👎：

下面是一个代码块：

    def foo():
        pass

这是另一个段落。

尽量为代码块标注编程语言

👍：

```python
def foo():
    pass
```

👎：

```
def foo():
    pass
```

同一个编程语言的代码块应在全文保持语言名称一致

👍：

第一段代码：

```python
def foo():
    pass
```

第二段代码：

```python
def foo():
    pass
```

👎：

第一段代码：

```python
def foo():
    pass
```

第二段代码：

```py
def foo():
    pass
```

使用更多 ` 转义多个 ` 本身

````md
下面是一个代码块：

```python
def foo():
    pass
```

这是另一个段落。
````

引用块

引用块中有内容的段落开头 > 右边应加空格，空行不用

👍：

> 第一个段落。第一个段落。第一个段落。第一个段落。
>
> 第二个段落。第二个段落。第二个段落。第二个段落。

👎：

>第一个段落。第一个段落。第一个段落。第一个段落。
>
>第二个段落。第二个段落。第二个段落。第二个段落。

👎：

> 第一个段落。第一个段落。第一个段落。第一个段落。
> <- 这里有个空格
> 第二个段落。第二个段落。第二个段落。第二个段落。

嵌套引用块应在两层的 > 间加空格

👍：

> 第一个段落。第一个段落。第一个段落。下面是个嵌套引用：
>
> > 嵌套引用段落。嵌套引用段落。嵌套引用段落。嵌套引用段落。
> >
> > 嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。

👎：

> 第一个段落。第一个段落。第一个段落。下面是个嵌套引用：
>
>> 嵌套引用段落。嵌套引用段落。嵌套引用段落。嵌套引用段落。
>>
>> 嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。嵌套引用第二个段落。

无序列表

使用 - 表示无序列表

👍：

- foo
- bar
    - bar1
    - bar2
- baz

👎：

- foo
- bar
    * bar1
    * bar2
- baz

另一个列表：

* aaa
* bbb

多级列表使用四个空格缩进

👍：

- foo
- bar
    - bar1
    - bar2
- baz

👎：

- foo
- bar
  - bar1
  - bar2
- baz

列表项有多行内容时应缩进到与第一行相同的位置

👍：

- foo
- 这是一个较复杂的列表项，有代码：

  ```python
  def foo():
      pass
  ```

  和另一段内容。
- baz

👎：

- foo
- 这是一个较复杂的列表项，有代码：

```python
def foo():
    pass
```

和另一段内容。
- baz

有序列表

按正确顺序为列表项标号（通常由 VS Code 扩展自动完成）

1. foo
2. bar
    1. bar1
    2. bar2
3. baz

表格

行的两侧不加 |，标题行下面只使用三个 -

👍：

姓名 | 学号 | 兴趣爱好
--- | --- | ---
张三 | 101 | 打篮球
李四 | 102 | 唱歌

👎：

| 姓名 | 学号 | 兴趣爱好 |
| --- | --- | ------- |
| 张三 | 101 | 打篮球 |
| 李四 | 102 | 唱歌 |

表格内容两侧加空格

👍：

姓名 | 学号 | 兴趣爱好
--- | --- | ---
张三 | 101 | 打篮球
李四 | 102 | 唱歌

👎：

姓名|学号|兴趣爱好
---|---|---
张三|101|打篮球
李四|102|唱歌

删除线

使用 <del> 或 ~~ 表示删除线样式

<del>哈哈哈哈！</del>被删除了！

其它

称之为“Markdown”或“markdown”，而不是“MarkDown”

使用 .md 作为文件扩展名，而不是 .markdown 或 .mdown

编写内容时遵循 OneBot 中文写作和排版指南

参考资料