markdown学习笔记（个人向） Part.1

1. 推荐插件

markdown ：
- 安装支持markdown的插件；
markdown-preview-github-styles ：
- 可以将VS Code上默认的markdown预览样式修改成github上常用的形式，很大程度上提高文件的可读性；
vscode-wordcount-cjk ：
- 用于统计markdown文档的字数；
markdown-preview-enhanced ：
- 最常用的markdown插件，内置了非常多的其他插件；
- 支持功能众多：
  1. 外部文件导入；
  2. 支持html，pdf，word等格式文档导出；
  3. 可以使用html语言和自定义css；
  4. 可以快速拷贝上传图片；
  5. 可以使用Mermaid，PlantUML，gnuplet等外部图像工具；
markdownlint :
- 对编写markdown文档进行格式检查，并给出相应的提示；
- 对于养成严格的编写习惯有帮助；
markdown-index ：
- 等同于 markdown add index 命令，给段落标题批量添加编号;
auto close tag :
- 编写html时自动填充关闭标签，对于在markdown中调用其他html标签或者设置字段的自定义格式有帮助；
markdown-all-in-one :
- 上述markdown-preview-enhanced的下位替代，提供了很多的功能：
  1. 列表的自动化处理；
  2. 提供数学公式的支持；
  3. 提供键盘快捷键的支持；
Pangu-Markdown ：
- 自动为 Markdown 文件的中英文之间添加空格，中英文符号转换等；
markdown emoji ：
- 快速插入markdown表情；

2. 基本语法

事实上，markdown是一种被包装的html文件，在markdown中可以直接使用html编写你需要的内容，也可以使用markdown语法编写对应的组件简化操作，如：标题 = # 标题；

2.1 预设定

在markdown中，我们可以使用
markdown 复制代码
```
---
  xxx
---
```
的格式来设置一篇markdown文章的各项属性，它一般写在文章的最开头位置；
可以在--- ---之间设置的文章属性有：
1. title：文章的标题;
2. author：文章的作者;
3. date：文章的创建时间;
4. 添加导出配置（在后文中细说）；

2.2 标题

对照html的<h>内容</h>标签，markdown的标题格式为：# 内容；
#号后面可以跟0-5个#号，表示标题的等级：
markdown 复制代码
```
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
```
展示效果是：

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题
与html一致，你可以对每个标题设置特定的id和class，格式为：
markdown 复制代码
```
## 测试标题{#title1 .class1} 
```
在标题中也可以使用强调、高亮、删除线等文字标记方法：
markdown 复制代码
```
##### *测试斜体*
##### **测试粗体**
##### ~~测试删除线~~
##### `测试代码`
##### 测试下划线
##### ==测试高亮==
```
效果为：

测试斜体

测试粗体

测试删除线

测试代码

++测试下划线++

测试高亮

2.3 目录

在Markdown Preview Enhanced中创建目录有两种方式：
1. 采用列表的形式，每个目录项的格式是[目录项名称](#目录项名称)，例如：
  markdown 复制代码
```
- [1. 章节1](#章节1)
    - [1.1. 子章节1](#子章节1)
```
  效果是：
  - [1. 章节1](#1. 章节1)
    - [1.1. 子章节1](#1.1. 子章节1)
2. 直接使用Markdown Preview Enhanced 支持的[TOC]，将其填在想要创建目录的位置即可。例如：
  markdown 复制代码
```
[TOC]
### 1. 章节1
#### 1.1 子章节1.1
```
  效果是：
  
  值得注意的是：[TOC]是自动识别同一层级的所有标题并统计的，如果想要某个标题不被[TOC]统计，则可以在标题后添加 {ignore=true} ，便可在预览和pdf界面的目录中忽略它；

2.4 文字标记

对于markdown中的文字，可以使用各种各样的方式进行修饰；

以下为一些实例：

markdown 复制代码

**粗体**  
*斜体*
~~删除线~~、{--删除线--}
<u>下划线</u>、<ins>下划线</ins>、{++下划线++}
==高亮==
`区域标记`
<big>变大</big>
<small>变小</small>
<span style="color:red" >自定义样式</span>
这是^上标^
这是~下标~

其效果为：
粗体
斜体
删除线
{++下划线++}
高亮
区域标记
变大
变小
自定义样式
这是^上标
这是_下标

2.5 注释和引用

在markdown中，注释和引用都是两种备注形式，一般在大段外部文献说明时使用引用，在案例或者自身理解、注疏时使用注释；
注释一般有三种:
1. 代码块:
 - 一般用于展示代码或者分类说明；
 - 使用方式即：
 markdown 复制代码
```

```lang{cmd=your_cmd opt1=value1 opt2=value2 ...}
 相关代码
```
复制代码
- lang是指代码块中的代码类型(如java,markdown,python)，markdown会根据代码类型自动添加语法高亮；
- 如果你想执行代码块中的代码，则需要在VS Code设置中检索enableScriptExecution并打开为true。但是注意VS Code的脚本执行功能并不会保证代码块内代码执行的安全性，如果你运行了他人的恶意代码，就可能导致系统崩溃，数据被窃取等不良后果。所以这个设置一般是关闭的。打开之后，在{}内输入cmd或者cmd=true、cmd="xxx"调用系统变量处预置的编辑器执行脚本；
- 如果你只想要执行后的结果不想要执行的代码信息，可以在opt处改成hide = true或者hide，以省略代码信息；
- 如果你想设置你的代码效果，可以在opt处填写output xxx，其中xxx可以是html，markdown，text，png（base64图片）或者none(隐藏输出结果) ；
- 如果你想唯一标识一段代码段，可以给它添加id到opt处；
- 如果你想在代码块中看到代码行数，可以在opt处填写.line-numbers；
- 如果你想下一个代码块继续执行上一个代码块的内容，可以在opt处填写continue，这种情况默认是下一个继续上一个的；如果你想继续指定代码块的内容，可以使用continue its_id的形式，执行its_id的代码块内容;
- 如果你想在markdown文件被保存时自动运行代码块，则可以在opt处填写run_on_save = true，其默认是false的；
- 如果你想直接插入代码块运行结果到markdown文件中，则可以在opt处填写modify_source = true，其默认是false的；
- 如果你想高亮对应的代码行数，可以在opt处填写highlight=行数，其默认是false的；
一个简单的例子是：
复制代码
```
```python {cmd .line-numbers id="test1" highlight=2}
for i in range(10):
 a += i
print("The result is: %d" %a)

其结果是： 
```
2. 灰体注释：
 - 在行首使用>并空一格，后边的文字便可以背景灰化降低对比度象征内容的补充；
 - 例如：
 markdown 复制代码
```
> 这是灰体注释
```
 效果是：这是灰体注释
3. markdown内注释：
 - 由于markdown与html互相兼容，因此可以在markdown内使用html的注释标签，在预览时不会呈现到文档中。VS Code对此的快捷键是ctrl + /;
 - 例如：
 markdown 复制代码
```

这是正文内容
```
引用又叫脚注，即我们在论文中常见的内容出处。在markdown上，我们可以使用[^x]来引用，例如：
markdown 复制代码
```
Content [^1]
---
[^1]: Hi! This is a footnote
```
实际效果是：

其中，点击[1]可以跳转对应的引用，点击返回键又可以跳转回原有文章的位置；

2.6 缩写

在markdown中，我们可以使用*[缩写词]: 全称的方式来定义缩写，并且在文章中使用对应的缩写词就可以在光标悬浮在缩写词上时弹出全称浮窗；

例如：

markdown 复制代码

*[HTML]: Hyper Text Markup Language

HTML is the standard markup language for creating Web pages.

其显示效果如下：

2.7 任务列表

markdown支持在文档中使用未确认或已确认两种形态的任务列表。
其形式如下：
markdown 复制代码
```
- [x] 已确认形式
- [ ] 未确认形式（`记得空格`）
```
效果如下：
- 已确认形式
- 未确认形式（记得空格）

2.8 分割线与空行、空格

类似于HTML中的<hr>标签或者Element-Plus中的<el-divider>，markdown支持在文档中使用分割线;
其形式如下：
markdown 复制代码
```

---
```
效果是：
值得注意的是：在一段文字下使用---不会在下方生成分割线，而是对文字进行放大，若要添加分割线需要空一行；

若要让文字之间段间距提高，可以使用 标签或者自定义块的上下左右边界，例如：

markdown 复制代码

这是第一段
<br/>
这是第二段
<!-- margin-xxx意味着容器相对于其他容器的上下左右距离是多少，距离单位自行查阅html -->
<div style="margin-top: 20px;margin-left: 20px;">这是第三段</div>

其展示效果如下：

这是第一段

这是第二段
这是第三段

在markdown中添加空格有很多种形式，space或者tab均可以实现，但是不管输入多少次都只能添加一个空格，如果要添加多个可以使用html的 ，例如：
markdown 复制代码
```

前半部分 后半部分（`tab添加`）
前半部分 后半部分（`space添加`）

前半部分&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;后半部分
```
其效果为：

前半部分后半部分

前半部分后半部分

前半部分后半部分

2.9 列表

列表是markdown中的一个核心功能，分为有序列表和无序列表、定义列表三种；
无序列表有两种实现方法：
1. 列表项前面加一个星号（*）或减号（-）,例如：
 markdown 复制代码
```
- 列表1
* 列表2
```
 其效果如下：
 - 列表1
 - 列表2
2. 使用html的标签，例如：
 markdown 复制代码
```

<ul>
 <li>列表1</li>
 <li>列表2</li>
</ul>
```
 效果是一样的；

有序列表也有两种形式：

列表项前面加数字. ,例如：

markdown 复制代码

<!-- 一般除了第一个外，markdown会自动填充的 -->
1. 列表项1
2. 列表项2

其效果为：

列表项1
列表项2

使用html的标签，例如：

markdown 复制代码

<!-- 表项的种类上，<ol>是有序列表，<ul>是无序列表，<li>是表项内容 -->
<ol>
    <li>列表项1</li>
    <li>列表项2</li>
    <li>列表项3</li>
</ol>

其结果同上；

最后一种，也是写文章中常用的定义列表，常用于定义某种命题或者概念；
- 其实现方法是使用html标签，例如；
 markdown 复制代码
```

<dl>
 
 <dt>术语1</dt>
 
 <dd>术语1的解释</dd>
 <dt>术语2</dt>
 <dd>术语2的解释</dd>
</dl>
```
 其效果为：
 :
 术语1的解释
 :
 术语2的解释

2.10 表格

一般情况下，markdown的表格不允许合并行或列，除非你打开markdown-preview-enhanced的配置项 enableExtendedTableSyntax ，其默认是false；

表格通过|||进行分列，用换行表示分行，；例如：

markdown 复制代码

<!-- 第二行用--注释表格，用:表示对齐-->
<!-- 在左边表示左对齐，在右边表示右对齐，两边都有就居中对齐 -->
|aaaaa|bbbbb|ccccc|
<!-- 列对齐格式说明 -->
|:--|:--:|--:|
|c|d|e|
<!-- 默认左边合并右边空着的表格，格式遵循左边的 -->
|a1||a2|
<!-- 如果是要右边合并左边的表格，则在左边添加>符号，此时格式也遵循右边 -->
|>|b1|b2|
|C1|C2||
<!-- 为了保持空表格不被合并，需要使用&nbsp;符号替代空格 -->
|D1|&nbsp;|D2|
|E1|E2|E3|
<!-- 上下合并需要在下方被合并的表格中添加^符号，且遵循同列的格式 -->
|^|F1|F2|

其效果是（）：

2.11 告诫块

即我们常说的Admonition，用于在文档中插入带样式的提示、警告、说明等信息；
其标准格式是：
markdown 复制代码
```
!!! type 标题/问题
    内容/回答
```

其中type有以下几种：

类型	样式效果	使用场景
`note/primary/important`	淡蓝色-笔	常规提醒
`info`	天青色-感叹号	补充说明
`warning/caution`	淡橙色-感叹号	提醒读者注意
`tip/hint`	淡绿色-火焰	技巧/建议
`success`	淡绿色-打勾	表示操作成功的提示
`danger`	红色-闪电	表示危险需要注意
`error/failure`	红色-打叉	错误提示
`question`	绿色-问号	用于提问或者思考
`abstract`	蓝色-段落	用于展示摘要
`quote`	灰色-引号	用于展示引用
`bug`	红色-虫子	用于描述bug
`example`	天青色-列表	用于举例子

例如：

markdown 复制代码

!!! question 中国有几个省级行政单位？
  23个省、5个自治区、4个直辖市、2个特别行政区、1个地区

其效果是：

3. 特殊功能

3.1 数学、物理公式插入

在Markdown Preview Enhanced中默认使用KaTex或者MathJax进行公式渲染；
插入分为两种：
1. 行内插入：
  - 使用 $···$ 或者$···$的格式进行插入;
  - 例如：
    mathdown 复制代码
```
质能方程是$E=mc^2$
```
    其结果为：
    质能方程是 E = m c 2 E=mc^2 E=mc2
2. 行外插入：
  - 使用 $$···$$ 或者\[···\]的格式进行插入;
  - 或者直接写代码块
    mathdown 复制代码
```
```math
    E=mc^2
```
复制代码
```
    结果是： 
    $$E=mc^2$$  
```
插入的公式采用latex语法进行表述，以下将进行简要介绍：

3.2 图片、超链接插入

链接使用[···](···)的格式使用，如：
markdown 复制代码
```
[百度](https://www.baidu.com)
```
效果是：
百度
图片使用![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=%C2%B7%C2%B7%C2%B7&pos_id=img-CY8HgDeT-1751874807233)的格式使用，如：
markdown 复制代码
```
![图片](https://i-blog.csdnimg.cn/img_convert/a807cbc37c464409643622f20f8eba5b.png)
```
效果是：
如果使用图片的链接是本地的，则使用![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=%E7%9B%B8%E5%AF%B9%E8%B7%AF%E5%BE%84&pos_id=img-ym2qcZbg-1751874807233)的格式使用，其中：
1. ./：当前目录；
2. ../：上一级目录；
3. folder/：指定目录；

3.3 Emoji表情

使用:···:的格式使用，例如：😄:smile:、👍:+1:、❤️:heart:、🚀:rocket:、👎:-1:、🚁:helicopter:;

4. 图像插件

4.1 CriticMarkup

目前有四种语法：
1. 添加 {++ ++}，效果是下划线;
2. 删除 {-- --}，效果是删除线;
3. 高亮 {== ==}，效果是加亮;
4. 注释 {>> >>}，但是实测无效；

4.2 Mermaid

markdown支持非常多的图像渲染，其中mermaid是其中非常好用的一种；
它是是一个基于 JavaScript 的图表绘制工具，能极大简化普通人在文档中使用图表的难度；
调用方法即使用代码块，代码块中添加mermaid标签，然后编写代码：
markdown 复制代码
```
```mermaid

```
复制代码
Mermaid提供了多种图标可供使用，包括流程图 、时序图、类图、状态图、甘特图、饼图等，接下来将逐个介绍：

markdown学习笔记（个人向） Part.1

markdown学习笔记（个人向） Part.1

1. 推荐插件

2. 基本语法

2.1 预设定

2.2 标题

一级标题

二级标题

三级标题

四级标题

五级标题

六级标题

测试斜体

测试粗体

测试删除线

测试代码

++测试下划线++

测试高亮

2.3 目录

2.4 文字标记

2.5 注释和引用

2.6 缩写

2.7 任务列表

2.8 分割线与空行、空格

2.9 列表

2.10 表格

2.11 告诫块

3. 特殊功能

3.1 数学、物理公式插入

3.2 图片、超链接插入

3.3 Emoji表情

4. 图像插件

4.1 CriticMarkup

4.2 Mermaid

`测试代码`