Markdown 语法及个人书写风格指南 v2

 

2019-04-14

总算把散在几篇草稿之中的语法和之前的风格指南整理到了一处，连带内容也做了一些更新。

另外如果以后没有大的变动，便只在 README 中更新。

风格

空格

  • 空一格
    • 英文句子之间；
    • 中文、英文和数字之间；
    • 非闭合的 Markdown 标签；
  • 不留空
    • 数字和单位之间；

空行

  • 使用空行分隔内容；
  • 不连续使用两个空行或以上；
  • 文件末尾不留多余空行；

代码

除非是为了展示代码输出效果，否则不要在代码前增加符号。

列表

  • 尽量使用无须列表；
  • 无序列表仅使用 -；
  • 长有序列表仅使用 1. 为序号；
  • 列表层级使用四个空格缩进；
  • 相连的列表之间可使用 <!-- --> 分隔；

标题

  • 标题符号只使用 #；
  • 标题不越级使用；
  • 标题尽量简短；
  • 标题末尾不使用符号；

拼写

  • 使用正确的大小写和缩写；
  • 使用已知流传更广的中译名；

注：拼写、缩写或中译名尽量参考中文维基百科。

文件名

文件名使用小写，并用连字符-代替空格和其它标点符号，后缀则使用 md。

语法

Markdown

标题

# 表示一级标题，## 表示二级标题，以此类推，例：# 一级标题。

标记

  • 斜体
    • 单星号 *， 例：*斜体*；
  • 粗体
    • 双星号 **，例：**粗体**；
  • 删除线
    • 双波浪 ~~，例：~~删除线~~；
  • 高亮
    • 反引号 `，例： `高亮`
  • 引用
    • 大于号 >，例：> 引用；
  • 分隔线
    • 三连字号 ---；

列表

  • 无序列表
    • 连字号 -，例：- 无序列表
  1. 有序列表
    1. 数字和点 1.，例：1. 有序列表
  • 待办事项
    • 未完成，例：- [ ] 未完成
    • 已完成，例：- [x] 已完成

插入

  • 链接
    • [描述](URL)，例：[某。](https://wuze.me)
  • 邮箱
  • 图片
    • ![描述（可空）](URL)，例：![](x.com/x.png)

代码

代码使用三个反引号 ```，并可在反引号后注明语言。

例：

1
```bash
2
echo "Hello Markdown"
3
```

表格

表格使用竖线 | 和连字符 - 组合而成；另，连字符不得少于三个。

例：

1
| 默认   | 右对齐 |   居中   |
2
| ------ | -----: | :------: |
3
| 左对齐 | 右对齐 | 居中对齐 |

HTML

修饰

  • 换行
    • <br>
  • 注释
    • <!--注释内容-->
  • 对齐
    • 居中：<p align="right">center</p>
    • 右对齐：<p align="right">right</p>

折叠

折叠标签
  • 无序列表
    1. 二级有序列表

注：关于折叠的更多信息，参考：利用 blockquote 在 Markdown 中实现折叠嵌套

表格

1
<table>
2
    <tr>
3
        <th rowspan="2">Test</th>
4
        <th>数字</th>
5
    </tr>
6
    <tr>
7
        <td>42</td>
8
    </tr>
9
</table>
Test 数字
42

Bitcron

样式修饰

在行尾增加圆括号()，并在括号内写明关键词（可多个，以空格隔开）：

  • 对齐
    • 居左：left
    • 居中：center
    • 居右：right
  • 缩放
    • 百分号 %，例：(150%)
  • 行高
    • 带小数点 .，例：(1.5)
  • 字体大小
    • 任意整数 x，例：(42)
  • 字体颜色
    • 颜色值，例：blue 或 333
  • 背景颜色
    • @颜色值，例：@blue 或 @333

代码

代码语言类型后跟着 :n 可显示行号。

Terminal window
1
echo "Hello Markdown"

表格

Bitcron 中的表格语法类似代码块，只是以 table 标明，其中数据的语法同 Markdown 相同。

  • 线图：table:line
  • 柱状图：table:bar
  • 饼图：table:pie
1
| 季 | 2012 年 | 2013 年 | 2014 年 | 2015 年 | 2016 年 | 2017 年 | 2018 年 |
2
| 春 | 07     | 29      | 07      | 11      | 18     | 38      | 14     |
3
| 夏 | 28     | 17      | 28      | 3       | 19     | 33      | 10     |
4
| 秋 | 48     | 07      | 10      | 14      | 17     | 15      | 56     |
5
| 冬 | 24     | 00      | 14      | 14      | 34     | 10      | 49     |

线图，线图和柱状图的区别仅在于 line 和 bar；

1
```table:line
2
| 季 | 2017 年 | 2018 年 |
3
| 春 | 38      | 14     |
4
| 夏 | 33      | 10     |
5
| 秋 | 15      | 56     |
6
| 冬 | 10      | 49     |
7
```

柱状图，自动归档；

1
```table:bar
2
| 季            | 2017 年 | 2018 年 |
3
| 春夏上(春夏)   | 38      | 14     |
4
| 春夏下(春夏)   | 33      | 10     |
5
| 秋冬上(秋冬)   | 15      | 56     |
6
| 秋冬下(秋冬)   | 10      | 49     |
7
```

饼图，自动归档语法和柱状图相同；

1
```table:pie
2
| 季 | 2018 年 |
3
| 春 | 14     |
4
| 夏 | 10     |
5
| 秋 | 56     |
6
| 冬 | 49     |
7
```

注：

  • 柱状图和饼图均支持合并归档统计；
  • 柱状图合并归档统计必须有二列以上的数据；
  • 饼图只支持一列数据；
  • 具体效果可参见文末的链接；

脚注

文内使用[^脚注]，文末补充[^脚注]: 脚注可为任意字，但前后必须相同。

信息

参考

更新

  • Update 2019-04-14
    • 增加语法；
    • 修改风格；
    • 文件同步至README；
  • Update 2018-06-29
    • 建立
# Markdown