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

 

2021-02-14

Markdown

寻找 Hugo 主题时注意到大部分预览都带有 Markdown 语法说明示例，于是便把原来博客对应的文章略作修改后先搬运过来。

介绍

Markdown 是一种轻量级标记语言，由 John Gruber 和 Aaron Swartz 在 2004 年共同创建，不同于其他标记语言（如 HTML），Markdown 最主要的设计是可读性，即源文件对人类是友好可易读的。目前广泛应用在写作软件、个人博客、README 等。

语法

标题

四级标题

五级标题
六级标题

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

1
# 一级标题（一篇文章建议只设定一个一级标题）
2


3
## 二级标题
4


5
### 三级标题
6


7
#### 四级标题
8


9
##### 五级标题
10


11
###### 六级标题

强调

  • 斜体
    • 一对单星号 *， 例：*斜体*；
  • 粗体
    • 一对双星号 **，例：**粗体**；
  • 删除线
    • 一对双波浪 ~~，例：~~删除线~~；

列表

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

链接

  • 链接
    • [描述](URL)，例：[长风](https://immwind.com)
  • <邮箱>
  • 图片
    • ![描述（可空）](URL)，例：![](x.com/x.png)

代码

行内代码

使用重音符包裹`，一般也用于高亮。

1
`行内代码`

效果：行内代码

代码块

使用三个反引号 ``` 包裹，可在反引号后注明语言。

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

效果：

Terminal window
1
echo "Hello Markdown"

缩进代码

​ echo “Hello Markdown”

引用

引用在内容前添加 >：

1
> 生活是一个叹号和一个问号之间的犹豫。在疑问之后，则是一个句号。

效果：

生活是一个叹号和一个问号之间的犹豫。在疑问之后，则是一个句号。

表格

表格使用竖线|作为分割线，需要在标题下添加一行连字符-，对齐方式使用冒号标示:，连字符不能少于三个。

例：

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

效果如下：

左对齐居中对齐右对齐
默认为左对齐连字符 - 两边添加冒号连字符右边添加冒号

脚注

脚注是成对出现的，由方括号[]包裹着脱字符^组合而成，脱字符后可以跟着数字[^1]1或英文字符[^label]2。

1
数字[^1]
2
英文[^label]
3


4
<!-- 下面这部分将会显示在文末 -->
5


6
[^1]: 数字脚注跳转
7
[^label]: 标签脚注跳转

分隔线

三个连字号 ---，效果如下：

HTML

修饰

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

风格

空格

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

空行

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

代码

除非是展示代码输，否则不在代码前增加符号。

列表

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

标题

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

拼写

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

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

文件名

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

扩展

暂无

信息

参考

更新

  • Update 2021-02-14
    • 增加介绍
    • 重新排版
    • 增加语法示例效果
    • 移除 Bitcron 部分
  • Update 2019-04-14
    • 增加语法
    • 修改风格
    • 文件同步至README
  • Update 2018-06-29
    • 建立

Footnotes

  1. 数字脚注跳转 ↩

  2. 标签脚注跳转 ↩

# Markdown