markdown学习笔记(个人向) Part.1
1. 推荐插件
- markdown:
- 安装支持markdown的插件;
- markdown-preview-github-styles:
- 可以将VS Code上默认的
markdown
预览样式修改成github
上常用的形式,很大程度上提高文件的可读性;
- 可以将VS Code上默认的
- vscode-wordcount-cjk:
- 用于统计markdown文档的字数;
- markdown-preview-enhanced:
- 最常用的markdown插件,内置了非常多的其他插件;
- 支持功能众多:
- 外部文件导入;
- 支持html,pdf,word等格式文档导出;
- 可以使用html语言和自定义css;
- 可以快速拷贝上传图片;
- 可以使用Mermaid,PlantUML,gnuplet等外部图像工具;
- markdownlint:
- 对编写markdown文档进行格式检查,并给出相应的提示;
- 对于养成严格的编写习惯有帮助;
- markdown-index:
- 等同于
markdown add index
命令,给段落标题批量添加编号;
- 等同于
- auto close tag:
- 编写html时自动填充关闭标签,对于在markdown中调用其他html标签或者设置字段的自定义格式有帮助;
- markdown-all-in-one:
- 上述
markdown-preview-enhanced
的下位替代,提供了很多的功能:- 列表的自动化处理;
- 提供数学公式的支持;
- 提供键盘快捷键的支持;
- 上述
- Pangu-Markdown:
- 自动为 Markdown 文件的中英文之间添加空格,中英文符号转换等;
- markdown emoji:
- 快速插入markdown表情;
2. 基本语法
事实上,markdown是一种被包装的html文件,在markdown中可以直接使用html编写你需要的内容,也可以使用markdown语法编写对应的组件简化操作,如:
<p>标题</p> = # 标题
;
2.1 预设定
- 在markdown中,我们可以使用
的格式来设置一篇markdown文章的各项属性,它一般写在文章的最开头位置;---xxx ---
- 可以在
--- ---
之间设置的文章属性有:title
:文章的标题;author
:文章的作者;date
: 文章的创建时间;- 添加导出配置(在后文中细说);
2.2 标题
-
对照html的
<h>内容</h>
标签,markdown的标题格式为:# 内容
; -
#
号后面可以跟0-5个#
号,表示标题的等级:# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题
展示效果是:
一级标题
二级标题
三级标题
四级标题
五级标题
六级标题
-
与html一致,你可以对每个标题设置特定的
id
和class
,格式为:## 测试标题{#title1 .class1} <!-- 设置id为title1,class1为标签样式 -->
-
在标题中也可以使用强调、高亮、删除线等文字标记方法:
##### *测试斜体* ##### **测试粗体** ##### ~~测试删除线~~ ##### `测试代码` ##### <u>测试下划线</u> ##### ==测试高亮==
效果为:
测试斜体
测试粗体
测试删除线测试代码
测试下划线
测试高亮
2.3 目录
- 在Markdown Preview Enhanced中创建目录有两种方式:
-
采用列表的形式,每个目录项的格式是
[目录项名称](#目录项名称)
,例如:- [1. 章节1](#章节1)- [1.1. 子章节1](#子章节1)
效果是:
- 1. 章节1
- 1.1. 子章节1
- 1. 章节1
-
直接使用
Markdown Preview Enhanced
支持的[TOC]
,将其填在想要创建目录的位置即可。例如:[TOC] ### 1. 章节1 #### 1.1 子章节1.1
效果是:
值得注意的是:[TOC]是自动识别同一层级的所有标题并统计的,如果想要某个标题不被[TOC]统计,则可以在标题后添加
{ignore=true}
,便可在预览和pdf界面的目录中忽略它;
-
2.4 文字标记
- 对于markdown中的文字,可以使用各种各样的方式进行修饰;
- 以下为一些实例:
其效果为:**粗体** *斜体* ~~删除线~~、{--删除线--} <u>下划线</u>、<ins>下划线</ins>、{++下划线++} ==高亮== `区域标记` <big>变大</big> <small>变小</small> <span style="color:red" >自定义样式</span> 这是^上标^ 这是~下标~
粗体
斜体
删除线
{++下划线++}
高亮
区域标记
变大
变小
自定义样式
这是上标
这是下标
2.5 注释和引用
-
在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)
其结果是:
-
灰体注释:
- 在行首使用
>
并空一格,后边的文字便可以背景灰化降低对比度象征内容的补充; - 例如:
效果是:> 这是灰体注释
这是灰体注释
- 在行首使用
-
markdown内注释:
- 由于markdown与html互相兼容,因此可以在markdown内使用html的注释标签
<!-- -->
,在预览时不会呈现到文档中。VS Code对此的快捷键是ctrl + /
; - 例如:
<!-- 这是HTML注释 --> 这是正文内容
- 由于markdown与html互相兼容,因此可以在markdown内使用html的注释标签
-
-
引用又叫脚注,即我们在论文中常见的内容出处。在markdown上,我们可以使用
[^x]
来引用,例如:Content [^1] --- [^1]: Hi! This is a footnote
实际效果是:
其中,点击
[1]
可以跳转对应的引用,点击返回键
又可以跳转回原有文章的位置;
2.6 缩写
- 在markdown中,我们可以使用
*[缩写词]: 全称
的方式来定义缩写,并且在文章中使用对应的缩写词就可以在光标悬浮在缩写词上时弹出全称浮窗; - 例如:
其显示效果如下:*[HTML]: Hyper Text Markup LanguageHTML is the standard markup language for creating Web pages.
2.7 任务列表
- markdown支持在文档中使用未确认或已确认两种形态的任务列表。
- 其形式如下:
效果如下:- [x] 已确认形式 - [ ] 未确认形式(`记得空格`)
- 已确认形式
- 未确认形式(
记得空格
)
2.8 分割线与空行、空格
-
类似于HTML中的
<hr>
标签或者Element-Plus中的<el-divider>
,markdown支持在文档中使用分割线; -
其形式如下:
<!-- 下边就是 --> ---
效果是:
-
值得注意的是:在一段文字下使用
---
不会在下方生成分割线,而是对文字进行放大,若要添加分割线需要空一行; -
若要让文字之间段间距提高,可以使用
<br/>
标签或者自定义块的上下左右边界,例如:这是第一段 <br/> 这是第二段 <!-- margin-xxx意味着容器相对于其他容器的上下左右距离是多少,距离单位自行查阅html --> <div style="margin-top: 20px;margin-left: 20px;">这是第三段</div>
其展示效果如下:
这是第一段
这是第二段这是第三段
-
在markdown中添加空格有很多种形式,
space
或者tab
均可以实现,但是不管输入多少次都只能添加一个空格,如果要添加多个可以使用html的
,例如:<!-- 一般空格 --> 前半部分 后半部分(`tab添加`) 前半部分 后半部分(`space添加`) <!-- 空格 --> 前半部分 后半部分
其效果为:
前半部分 后半部分
前半部分 后半部分前半部分 后半部分
2.9 列表
-
列表是markdown中的一个核心功能,分为有序列表和无序列表、定义列表三种;
-
无序列表有两种实现方法:
- 列表项前面加一个星号(*)或减号(-),例如:
其效果如下:- 列表1 * 列表2
- 列表1
- 列表2
- 使用html的标签,例如:
效果是一样的;<!-- html中的实现 --> <ul><li>列表1</li><li>列表2</li> </ul>
- 列表项前面加一个星号(*)或减号(-),例如:
-
有序列表也有两种形式:
- 列表项前面加
数字.
,例如:
其效果为:<!-- 一般除了第一个外,markdown会自动填充的 --> 1. 列表项1 2. 列表项2
- 列表项1
- 列表项2
- 使用html的标签,例如:
其结果同上;<!-- 表项的种类上,<ol>是有序列表,<ul>是无序列表,<li>是表项内容 --> <ol><li>列表项1</li><li>列表项2</li><li>列表项3</li> </ol>
- 列表项前面加
-
最后一种,也是写文章中常用的定义列表,常用于定义某种命题或者概念;
- 其实现方法是使用html标签,例如;
其效果为:<!-- <dl>是包含部分,d意为defined --> <dl><!-- dt是名称 --><dt>术语1</dt><!-- dd是定义 --><dd>术语1的解释</dd><dt>术语2</dt><dd>术语2的解释</dd> </dl>
- 术语1
- 术语1的解释 术语2
- 术语2的解释
- 其实现方法是使用html标签,例如;
2.10 表格
- 一般情况下,markdown的表格不允许合并行或列,除非你打开markdown-preview-enhanced的配置项
enableExtendedTableSyntax
,其默认是false
; - 表格通过
|||
进行分列,用换行表示分行,;例如:
其效果是():<!-- 第二行用--注释表格,用:表示对齐--> <!-- 在左边表示左对齐,在右边表示右对齐,两边都有就居中对齐 --> |aaaaa|bbbbb|ccccc| <!-- 列对齐格式说明 --> |:--|:--:|--:| |c|d|e| <!-- 默认左边合并右边空着的表格,格式遵循左边的 --> |a1||a2| <!-- 如果是要右边合并左边的表格,则在左边添加>符号,此时格式也遵循右边 --> |>|b1|b2| |C1|C2|| <!-- 为了保持空表格不被合并,需要使用 符号替代空格 --> |D1| |D2| |E1|E2|E3| <!-- 上下合并需要在下方被合并的表格中添加^符号,且遵循同列的格式 --> |^|F1|F2|
2.11 告诫块
- 即我们常说的
Admonition
,用于在文档中插入带样式的提示、警告、说明等信息; - 其标准格式是:
!!! type 标题/问题内容/回答
- 其中
type
有以下几种:类型 样式效果 使用场景 note/primary/important
淡蓝色-笔 常规提醒 info
天青色-感叹号 补充说明 warning/caution
淡橙色-感叹号 提醒读者注意 tip/hint
淡绿色-火焰 技巧/建议 success
淡绿色-打勾 表示操作成功的提示 danger
红色-闪电 表示危险需要注意 error/failure
红色-打叉 错误提示 question
绿色-问号 用于提问或者思考 abstract
蓝色-段落 用于展示摘要 quote
灰色-引号 用于展示引用 bug
红色-虫子 用于描述bug example
天青色-列表 用于举例子 - 例如:
其效果是:!!! question 中国有几个省级行政单位?23个省、5个自治区、4个直辖市、2个特别行政区、1个地区
3. 特殊功能
3.1 数学、物理公式插入
- 在Markdown Preview Enhanced中默认使用
KaTex
或者MathJax
进行公式渲染; - 插入分为两种:
- 行内插入:
- 使用
$···$
或者\(···\)
的格式进行插入; - 例如:
其结果为:质能方程是$E=mc^2$
质能方程是E=mc2E=mc^2E=mc2
- 使用
- 行外插入:
- 使用
$$···$$
或者\[···\]
的格式进行插入; - 或者直接写代码块
```math E=mc^2
结果是: $$E=mc^2$$
- 使用
- 行内插入:
- 插入的公式采用latex语法进行表述,以下将进行简要介绍:
3.2 图片、超链接插入
- 链接使用
[···](···)
的格式使用,如:
效果是:[百度](https://www.baidu.com)
百度
- 图片使用

的格式使用,如:
效果是:
- 如果使用图片的链接是本地的,则使用

的格式使用,其中:./
:当前目录;../
:上一级目录;folder/
:指定目录;
3.3 Emoji表情
- 使用
:···:
的格式使用,例如:😄:smile:
、👍:+1:
、❤️:heart:
、🚀:rocket:
、👎:-1:
、🚁:helicopter:
;
4. 图像插件
4.1 CriticMarkup
- 目前有四种语法:
- 添加
{++ ++}
,效果是下划线; - 删除
{-- --}
,效果是删除线; - 高亮
{== ==}
,效果是加亮; 注释;{>> >>}
,但是实测无效
- 添加
4.2 Mermaid
- markdown支持非常多的图像渲染,其中
mermaid
是其中非常好用的一种; - 它是是一个基于
JavaScript
的图表绘制工具,能极大简化普通人在文档中使用图表的难度; - 调用方法即使用代码块,代码块中添加
mermaid
标签,然后编写代码:```mermaid <!-- 你想写的主要内容 -->
- Mermaid提供了多种图标可供使用,包括流程图、时序图、类图、状态图、甘特图、饼图等,接下来将逐个介绍: