前言

在平时码代码写文档时用的最多的就是markdown语言了，但有时候一些不常用的功能会忘了书写格式，本文旨在做一个Markdown教程兼语法手册，方便我们学习和平时使用查询，在进入教程前，先要感谢多个网站提供的教程或启发

参考文档:

  • Markdown是一种轻量级标记语言，允许使用者以易读易写的纯文本格式编写文档，易读意味着编写好的markdown即使不经过编辑器渲染依然能很清晰的理解文档格式内容，例如 强调 和 **强调** 给人的感觉是类似的。
  • Markdown编写的文档可导出为多种常用格式的文档，如 HTML、Word、PDF、Epub、思维导图等
  • Markdown的轻量但强大的功能使其被广泛应用在各种技术文档中，很多语言或工具都兼容 Markdown语言并提供相应的插件
  • Markdown语言被Github、简书等作为撰写文档的首选语言
  • Markdown提供书写文档的各种格式，如 标题、链接、代码块、表格、列表、引用图片等
    …

Markdown作为一种工具类语言，因此强烈建议在实践中学习，对照教程一步步实验每个功能能帮助学习者更快更牢固地掌握其使用方法

话不多说，快来看看Markdown到底能帮我们做到些什么！

环境配置与工具准备：

  • Windows操作系统，Linux未测试但不影响学习
  • VSCode编辑器(支持markdown语法的均可，如Typora)
  • 插件：在VSCode中安装 Markdown Preview Enhanced 插件，右键markdown文档选择 Markdown Preview Enhanced：Open Preview to the Side 即可在侧边实时预览书写效果

多级标题

写文档第一步就是写标题了，markdown语法中提供了多级标题的功能，使用方式如下：

1
2
3
4
5
6
# h1 一级标题 
## h2 二级标题
### h3  
#### h4  
##### h5  
###### h6

标题级数越高字体越小，不同级的标题会自动形成标题目录

段落

段落方面要说明的是markdown中在段尾用 两个空格+回车 或 一个空行 来实现分段
如果想要完全分割两部分，可以用下面的方式建立分割线来明确分割： 

1
2
3
4
5
***
* * * 
*****
- - - 
------

这几种标记都能产生分割线，效果相同

字体样式

有时候有文字强调的需求，markdown提供了 斜体、粗体、粗斜体、删除线、下划线 等工具，使用方法如下： 

1
2
3
4
5
6
7
*斜体文本*
_斜体文本_
**粗体文本**
__粗体文本__
***粗斜体文本***
___粗斜体文本___
~~删除线文本~~

效果展示：

斜体文本
斜体文本
粗体文本
粗体文本
粗斜体文本
粗斜体文本
删除线文本

下划线样式是通过使用HTML中的<u></u>标签实现的： 

1
<u>下划线文本</u>

效果： 下划线文本
markdown还支持更多的HTML标签的使用，很方便，教程后面会有相关介绍

转义

文档编写中有时候需要只是显示一个符号，而不是使用符号的功能，那就是转义字符的用武之地了，markdown和大多数编程语言一样，都使用反斜杠 \ 来转义特殊字符，使用方式： 

1
2
_正常斜体_
\_被转义的显示\_

效果：正常斜体 _被转义的显示_

脚注

脚注是对文本的补充说明，当使用脚注标记时，markdown会自动为脚注创建一个超链接，使用者可点击该链接或悬停在上面以查看脚注的内容，语法如下： 

1
2
我管理代码所用的网站是Github[^1]。
[^1]: https://github.com

注意：

  • 脚注的内容可放在文档的任意位置，但是建议放在文档末尾，方便统一管理
  • 脚注效果和论文中的参考文献相同，但注意有的平台不支持脚注显示

列表

markdown支持有序列表和无序列表

无序列表

无序列表用 *, +, - 作为列表标记，使用时需要在标记后添加一个空格再书写内容，列表标记也可混用，使用方法：

1
2
3
4
5
6
7
8
9
10
11
12
* 第一项
* 第二项

+ 第一项
+ 第二项

- 第一项
- 第二项

* 第一项
+ 第二项
- 第三项

有序列表

有序列表使用 数字.作为列表标记，同样也要敲一个空格后书写内容，使用方法： 

1
2
3
1. 第一项
2. 第二项
3. 第三项

嵌套列表

列表嵌套只须在子列表的选项前添加三个或三个以上空格即可，列表标记也可以使用字体样式，如倾斜加粗等，无序有序列表都能嵌套可混用，具体用法： 

1
2
3
4
5
6
* 无序有序混用嵌套:
    1. 第一步
    2. 第二步
_1._ 列表标记可用字体样式：
    1. 第一步
    2. 第二步

任务列表

markdown中也可实现任务清单列表的撰写，格式同一般列表类似，使用[]标记未完成，[x]标记完成，列表的内容也可用字体样式，如：

1
2
* [x] ~~学习markdown~~
* [ ] 写博客

具体效果：

  • 学习markdown
  • 写博客

区块

使用多个标记 > 来创建一个区块，常用来在文档中书写引用内容或者表示强调，注意：标记 > 后要紧跟一个空格再书写内容
区块也支持嵌套
区块和列表也可以嵌套

1
2
3
4
5
6
7
8
9
10
11
12
13
> 区块第一行
> 区块第二行

> 区块最外层
> > 第一层嵌套

> 1. 区块中
> 2. 用列表

1. 第一项
    > 列表中
    > 用区块
2. 第二项

效果展示：

区块第一行
区块第二行

区块最外层

第一层嵌套

  1. 区块中
  2. 用列表
  1. 第一项

    列表中
    用区块

  2. 第二项

代码段与代码块

对文档中的代码或方法名等要与普通文本区分开就可以使用此功能，有两种方式：

  1. 单行代码片段：
    用两个 ` 符号将代码包裹，如：`System.out.println();`
  2. 多行代码区块：
    用三个 ` 来包裹代码段，如：
    ```java
    int a = 1;
    int b = 1;
    System.out.println(a+b);
    ```

效果展示：

  1. 单行代码片段： print();
  2. 多行代码区块： 
    1
    2
    3
    int a = 1;
    int b = 1;
    System.out.println(a+b);

链接

内联链接

创建一个链接，实现点击文字跳转链接，格式： [链接名称](链接地址) ，例如：
[GitHub](https://github.com) 效果： GitHub

自动链接

直接用 < 和 > 将地址包裹，地址内容就是链接名字，点击链接跳转链接所示的地址，如 <https://github.com/> 效果： https://github.com

脚注链接

将链接地址与链接文本分离，链接地址统一放在文档末尾，方便维护和管理，格式：

1
2
[Github][github_link]
[github_link]:https://github.com

锚点链接

在文档内通过锚点链接在不同标题部分跳转，格式: [跳转](#要跳转的标题)，例如： 详情请看[后续介绍](#高级技巧)，效果展示：
详情请看后续介绍

邮件链接

文档阅读者点击链接直接发送邮件，格式：[邮件联系](mailto:example@example.com)，效果：
邮件联系

图片

markdown文档中也支持插入图片，支持png、jpg、jpeg、svg、gif等格式图片，插入格式：![图片显示内容](图片地址)，注意：

  • 图片显示内容可为空
  • 图片显示内容部分是图片无法显示的时候替代图片显示的内容
  • []中间也可以是图片，实现点击图片跳转链接的功能
  • 图片地址用绝对地址或相对地址均可
    使用方法：
    1
    2
    ![logo图标](https://.../logo.jpg)
    ![logo图标](/img/logo.jpg)
    实际效果：直接显示图片，大小位置不可调，鼠标放在图片上显示[]中的图片名称
    如果想调整图片大小位置显示方式，可以用HTML标签来插入图片，如：
    1
    <img src="https://.../logo.jpg" width="200" height="100">

表格

在markdown中可制作简易表格，用|来分隔不同单元格，用-来分割表头和其他行，在分割行可以用:---、---:、:---:来设置列的对齐方式，表格里的字体也可设置字体样式，如： 

1
2
3
4
| 标签   |      可选值    | 内容 |
| :----- | ------------: | :---:|
|**img_top** | _true/false_    |false|
|**index_bg**| _true/false/url_|true|

效果：

标签 可选值 内容
img_top true/false false
index_bg true/false/url true

高级技巧

上面的部分是常用的markdown语法，还有一些技巧在面对特定的任务时有更灵活多变的效果，下面也做简单介绍

HTML支持

要在markdown文档中实现一些超出markdown基本语法的功能就需要借助HTML的标签了
HTML在markdown中主要应用在哪些地方：

  • 插入复杂的元素：如创建样式复杂的表格
  • 更加灵活的布局：如设置图片的显示大小、位置
  • 更加美观的样式：如自定义字体的样式、颜色
  • 提供交互的功能：如插入按钮、提交表单等交互元素
    注意：
  • 大多数的Markdown解析器支持原生的HTML，可直接在markdown中书写使用，插入标签，无需额外的语法
  • Markdown不一定在HTML中起作用，因此HTML中尽可能用HTML的tags代替markdown，尽量避免在HTML标签中使用markdown的语法样式，如设置字体加粗等

HTML基本用法

  1. 不在markdown涵盖范围内的标签都可直接在文档内用HTML撰写，常用的有 <kbd>,<b>,<i>,<em>,<sup>,<sub>,<br> 等，使用方法举例：
    1
    使用快捷键<kbd>Ctrl</kbd>+<kbd>C</kbd>复制
    效果： 使用快捷键Ctrl+C复制
  2. markdown中也直接支持原生的HTML，&，<，>符号会自动转成HTML实体，这种支持方便在markdown中使用HTML原始码来操作，例如在markdown中直接写入下面HTML内容：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    <table>
        <tr>
            <th>周一</th>
            <th>周二</th>
            <th>周三</th>
        </tr>
        <tr>
            <th>晴</th>
            <th>雨</th>
            <th>多云</th>
        </tr>
    </table>
    效果如下：
    周一 周二 周三
    晴 雨 多云

更多样的样式

借助HTML内联CSS定制样式，如 <style></style> 标签或 style 属性定制CSS样式，如<p style="color: orange;">这段文字将显示为橘色！</p>，效果：

这段文字将显示为橘色！

更灵活的布局

HTML标签允许自定义布局，例如对图片的宽度、高度、对齐方式等markdown没办法直接实现，但是可以插入HTML标签来间接实现，例如：

1
<img src="https://example.com/logo.jpg" width="50" height="60" align="right">

公式书写

文档中有时会有插入公式的需求，Markdown支持直接书写并渲染公式
Markdown Preview Enhanced 使用KaTeX或者MathJax来渲染数学表达式
KaTeX性能更快,MathJax特性更多，markdown公式有两种显示方式：

  1. 行显示： $f(x)$ 或 \(f(x)\)
  2. 块显示： $$f(x)$$ 或 \[f(x)\] 或用代码块的方式
    注意块显示一行只能有一个公式，使用实例：
    1
    2
    3
    4
    5
    6
    <!-- 行显示： -->
    $f(x)=sin(x)$
    \(g(x)=cos(x)\)
    <!-- 块显示 -->
    $$\sum_{n=1}^{10}f(x)+g(x)$$ 
    \[\sum_{n=1}^{5}f(x)+g(x)\]
    数学代码块显示格式：
    ```math
    f(x) = sin(x)+cos(x)
    ```
    本博客中未配置渲染公式，所以暂不展示公式效果，经过笔者在VSCode中测试，显示正常

笔者的话

  • 不同的Markdown编辑器和解释环境可能会有不同的渲染效果。因此，在不同平台发布之前，预览你的Markdown文档是很重要的，例如笔者在使用markdown过程中就发现某些网站字体加粗显示只能用 ***加粗** ，而 __加粗__ 这种方式并不能实现加粗
  • 使用markdown书写文档时一定要以读者的角度审视文档，要方便读者理解文档内容，如：插入图片格式中[]中的内容可以为空，但是还是建议填上对图片的描述，这样当由于网络原因图片无法显示时，[]中的内容会填充图片部分，读者也就能理解此处图片的含义了