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. 标签脚注跳转