本文是markdown使用的简单指导，

项目地址

• github: https://github.com/lengjingzju/notes/blob/master/src/md/note_markdown.md
• gitee: https://gitee.com/lengjingzju/notes/blob/master/src/md/note_markdown.md

前言

在信息爆炸的时代，如何高效地组织、表达和分享知识？Markdown——这种轻量级标记语言，正是为此而生。

无论你是程序员、写作者、学生还是知识工作者，Markdown都能让你专注于内容本身，而非繁琐的格式调整。它用简洁的语法取代了复杂的排版操作，让书写变得优雅而高效。从简单的笔记到复杂的技术文档，从博客文章到电子书籍，Markdown正在成为现代数字写作的通用语言。

这本指南汇集了多年使用Markdown的经验总结，不仅涵盖基础语法，更深入扩展功能和实用技巧（包含使用 mdbook 生成书籍）。无论你是初次接触Markdown的新手，还是希望提升效率的资深用户，这里都有你需要的知识。

** 主要内容涵盖：**

• 基础语法详解：标题、段落、列表、链接、图片等核心元素
• 高级格式技巧：表格、脚注、定义列表、任务列表等扩展语法
• 可视化图表：使用Mermaid绘制流程图、时序图、类图、甘特图等
• 数学公式：完整LaTeX数学符号与公式语法参考
• 实用工具指南：VSCode、Typora、mdbook等编辑器和工具的配置与使用
• 实战应用：从单篇文章到整本书籍的Markdown项目管理

特色亮点：

• 多工具兼容：明确标注不同编辑器对语法的支持情况
• 即学即用：每个语法点都配有实例代码和实际效果展示
• 扩展性强：包含HTML混编、自定义CSS等高级技巧
• 工程化思维：介绍如何用Markdown管理大型文档项目

使用的编辑器：

• VSCode + 插件 Markdown Preview Enhanced : 推荐编辑器
• crossnote : 上面插件的命令行工具
• Typora : 所见即所得的编辑器，目前版本收费
• mdbook : markdown书籍工具

不同的编辑器一般可支持基本语法，但是扩展语法不确定。本文所记录的语法一般上面的编辑器都支持，特例会特别说明。

基础概念

• 基本知识

  • 文本内容存储在带有 .md 扩展名的纯文本文件中

  • markdown有自己专有语法，也可以使用 HTML 语法，例如 HTML表格

  • 文档的注释使用 <!-- 单行或多行注释 --> 方式

  • 转义字符

    • 要显示原本用于格式化markdown文档的字符，请在字符前面添加反斜杠 \
    • 可转义的字符有 \ # * + - _ . ` ! | { } [ ] ()
    • markdown允许你直接使用 < & ，不需要使用HTML中的转义字符 < 和 &
      
      

• 使用教程

  • 语法教程：https://markdown.com.cn/
  • 语法教程：https://www.imooc.com/wiki/markdownlesson/
  • mermaid官方文档：https://mermaid.js.org/intro/
  • katex官方文档：https://katex.org/docs/supported.html

语法详解 {#语法详解}

标题语法

• 标题(Heading)
  • 使用 # 开头，有几个 # 就是几级标题
  • 请用一个空格将 # 和标题隔开
  • 标题上下最好留出空行
  • 可选语法
    • 文本下方添加任意数量的 === 来标识一级标题
    • 文本下方添加任意数量的 --- 来标识二级标题

---

语法

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

---

• 生成目录(扩展语法)
  • 任意位置放置 [TOC] 会根据标题显示目录
  • 任意位置放置下面指令保存时会根据标题插入目录文本(mdbook不支持)

    <!-- @import "[TOC]" {cmd="toc" depthFrom=2 depthTo=3 orderedList=false} -->
    

段落语法

• 段落(Paragraph)
  • 要创建段落，请使用空白行将一行或多行文本进行分隔(mdbook需要两行空行)
  • 不要用空格符或制表符缩进段落，缩进是无效的

换行语法

• 换行(Line Break)
  • 使用HTML的 <br> 创建换行

分割线语法

• 分隔线(Horizontal Rule)
  • 单独一行上使用至少3个星号 ***、连接号 --- 或下划线 ___ ，并且上下要留出空行

强调语法

• 强调
  • 要用斜体显示文本，请在单词或短语的前后各添加1个星号 *
  • 要加粗显示文本，请在单词或短语的前后各添加2个星号 **
  • 要同时用粗体和斜体突出显示文本，请在单词或短语的前后各添加3个星号 ***
  • 注：也可以使用下划线 - 代替星号 *，但不建议使用，因为不同渲染器有不同处理
• 删除线(扩展语法)
  • 要在文本上显示删除线，请在单词或短语的前后各添加2个波浪号 ~~
• 高亮(扩展语法)(mdbook不支持)
  • 要高亮显示文本，请在单词或短语的前后各添加2个等号 ==

---

语法

*我是斜体* **我是粗体** ***我是粗斜体*** ~~我被删除了~~ ==我高亮了==

效果

我是斜体 我是粗体 我是粗斜体 我被删除了 我高亮了

---

引用语法

• 引用
  • 引用使用大于号 > 开头
  • 块引用可以包含多个段落，段落之间的空白行需要添加一个 > 符号
    • 如果是同一个段落，嵌套元素的效果会延续
  • 块引用可以嵌套，在要嵌套的段落前添加 >> 符号
  • 块引用可以嵌套其他的元素，但并非所有元素都可以使用

---

语法

> 我是引用段落1
> * 列表
> 没有向右箭头我还在这里
>
> 我是引用段落2
>> 我是段落2嵌套引用
>
> 我是引用段落3

效果

我是引用段落1

• 列表
  没有向右箭头我还在这里

我是引用段落2

我是段落2嵌套引用

我是引用段落3

---

链接语法

• 图片链接

  • 语法：![图片alt](图片路径 "可选的图片title")
  • 可选的链接title是当鼠标悬停在链接上时会出现的文字，它放在圆括号中链接地址后面，跟链接地址之间以空格分隔
  • 直接显示图片标题要单独书写，可以使用html语法，例如 <center><b><font size="5">加粗加大标题</font></b></center>

• 引用图片链接

  • 引用图片链接分为两部分：与文本保持内联的部分以及存储在文件中其他位置的部分
  • 第1部分语法：![图片alt][图片的标签]
  • 第2部分语法：[图片的标签]: 图片路径 "可选的图片title"
    
    

• 超链接

  • 语法：[超链接显示名](超链接地址 "可选的超链接title")
  • 链接文本放在中括号内，链接地址放在后面的小括号中，链接title可选
  • 链接文本也可以是上面的图片路径
  • 可选的链接title是当鼠标悬停在链接上时会出现的文字，它放在圆括号中链接地址后面，跟链接地址之间以空格分隔
  • 注：可以使用尖括号 <> 将URL或者email地址变成可点击的链接

---

语法

[必应搜索](https://www.bing.com "可以替代百度")

效果

必应搜索

---

• 引用超链接
  • 引用超链接(参考样式链接)分为两部分：与文本保持内联的部分以及存储在文件中其他位置的部分
  • 第1部分语法：[链接的文本][链接的标签]，标签不区分大小写，可以包含字母，数字，空格或标点符号
  • 第2部分语法：[链接的标签]: 链接的URL "链接的可选标题"
    • 链接的URL，可以选择将其括在尖括号中
    • 链接的可选标题，可以将其括在双引号，单引号或小括号中

---

语法

[必应搜索][bing]

[bing]: https://www.bing.com "可以替代百度"

效果

必应搜索

---

• 脚注(扩展语法)
  • 创建脚注时，带有脚注的上标数字会出现在您添加脚注参考的位置，可以单击链接以跳至页面底部的脚注内容
    • 脚注语法：[^标签] , 标签可以是数字或单词，但不能包含空格或制表符
    • 脚注内容语法，[^标签]: 内容文本
  • 注意编号有顺序

---

语法

markdown[^1]

[^1]: Markdown是一种轻量级标记语言，排版语法简洁，让人们更多地关注内容本身而非排版。它使用易读易写的纯文本格式编写文档，可与HTML混编，可导出 HTML、PDF 以及本身的 .md 格式的文件。

效果

markdown¹

---

• 标签跳转(扩展语法)
  • 定义跳转ID的语法
    • 可以直接使用标题名作为跳转ID
    • 标题背后可以自定义ID，语法： # 标题名字 {#跳转id}
  • 跳转到本文件的指定ID的语法：[名称](#跳转id)
    • 跳转到指定ID的ID中含有的一些字符需要替换
      • 替换成小写：大写字母替换成相应的小写字母
      • 替换成横线 -：空格，TAB
      • 删除该字符：所有英文标点和特殊字符
    • 可使用html语法<a href="#跳转id">名称</a>
  • 跳转到指定文件的指定ID的语法：[名称](文件路径#跳转id)

---

语法

## 语法详解 {#语法详解}
[点击](#语法详解)跳转到语法详解标题

效果

点击跳转到语法详解标题

---

代码语法

• 代码
  • 要将单词或短语表示为代码，请将其包裹在单反引号(TAB键上面)中
  • 要表示为代码的单词或短语中包含一个或多个反引号，则可以将单词或短语包裹在双反引号中
  • 要使用多行代码块，请将代码块增加一个层次的缩进
  • 多行代码块也可以不用缩进，用三反引号包围，并且可以加上代码类型(例如 c / json / html 等)以显示高亮(扩展语法)

---

语法

```json
{
    "firstName": "Leng",
    "lastName": "Jing",
    "age": 34
}
```

```c
#include <stdio.h>
int main (void)
{
    printf("Hello World!");
    return 0;
}
```

效果

{
    "firstName": "Leng",
    "lastName": "Jing",
    "age": 34
}

#include <stdio.h>
int main (void)
{
    printf("Hello World!");
    return 0;
}

---

列表语法

• 有序列表(Ordered List)
  • 使用 n. 开头，例如 1. 2. …
  • 请用一个空格将 n. 和内容隔开
  • 次级列表至少使用4个空格缩进，次级列表也可以是无序列表

---

语法

1. First item
    1. First item sub1
2. Second item
3. Third item

效果

1. First item
   1. First item sub1
2. Second item
3. Third item

---

• 无序列表(Unordered List)
  • 使用 * 或 - 或 + 开头，注意不用混用
  • 请用一个空格将 * 或 - 或 + 和内容隔开
  • 次级列表至少使用2个空格缩进

---

语法

* First item
    * First item sub1
* Second item
* Third item

效果

• First item
  • First item sub1
• Second item
• Third item

---

• 在列表中嵌套其他元素
  • 要在保留列表连续性的同时在列表中添加另一种元素(例如 段落、图片、引用、代码、次级列表)，可以将该元素缩进2(或4)个空格或一个制表符

---

语法

* First item
  附加段落
* Second item
  > 附加引用
* Third item
  | 符号 | 代码 | 描述 |
  |----|----|----|
  | $ ( x ) $ | `$ ( x ) $` | 小括号 |
  | $ [ x ] $ | `$ [ x ] $` | 中括号 |
  | $ \{ x \} $ | `$ \{ x \} $` | 大括号 |

效果

• First item
  附加段落
• Second item

  附加引用

• Third item

  符号	代码	描述
  $ ( x ) $	$ ( x ) $	小括号
  $ [ x ] $	$ [ x ] $	中括号
  $ { x } $	$ \{ x \} $	大括号

---

• 定义列表(扩展语法)(mdbook不支持)
  • 要创建定义列表，请在第一行上键入术语，在下一行键入一个冒号后跟一个空格和定义 : 定义

---

语法

功能A
  : 定义
  : 作用
  : 适用场景
  : 其他说明

效果

功能A

定义

作用

适用场景

其他说明

---

• 任务列表(扩展语法)
  • 已完成语法： - [x] 任务信息
  • 未完成语法： - [ ] 任务信息

---

语法

- [x] 已完成任务
- [ ] 未完成任务

效果

• 已完成任务
• 未完成任务

---

表格语法

• 表格(扩展语法)
  • 第一行是标题(表头)，第二行是格式说明(分割线)，第三行及之后都是表格内容(数据)
  • 格式说明: (任意个)连接符 - 代表这是一列，使用管道符 | 分隔每列
  • 连接符的 左侧/右侧或两侧 添加冒号 : ，表示列中的文本对齐到 左侧/右侧/中心，默认左对齐
  • 可以使用表格的HTML字符代码 | 在表中显示竖线 | 字符
  • 如果需要定义复杂的表格效果，请使用 html 的 <Table> 标签实现
  • 可以使用 标题名称<div style="width:100px;"> 指定该标题的列宽度

---

语法

| Title1 | Title2 | Title3 |
| --- | --- | --- |
| aa | bb | cc |

| 左对齐 | 右对齐 | 居中对齐<div style="width:100px;"> |
| :-- | --: | :-: |
| aa | bb | cc |
| aaaa | bbbb | cccc |
| aaaaaa | bbbbbb | cccccc |

效果

Title1	Title2	Title3
aa	bb	cc

左对齐	右对齐	居中对齐
aa	bb	cc
aaaa	bbbb	cccc
aaaaaa	bbbbbb	cccccc

HTML表格语法

Markdown也可以使用 HTML表格

• 必要元素
  • HTML 表格由 <table> 标签来定义，可用 border="1" 设置外框线的宽度
  • 每个表格均有若干行由 <tr> 标签定义，tr 是 table row 的缩写，表示表格的一行
  • 表格可以包含标题行由 <td> 标签定义，th 是 table header的缩写，表示表格的表头单元格
  • 表格的含内容行由 <td> 标签定义，td 是 table data 的缩写，表示表格的数据单元格
• 其它元素
  • <thead> 表格的页眉
  • <tbody> 表格的主体
  • <tfoot> 表格的页脚
• 修饰表格
  • 表格可以跨行跨列
    • colspan="2" 表示跨两列
    • rowspan="2"表示跨两行
  • 可指定对齐方式
    • align="center" 水平对齐方式(参数有left、center、right)
    • valign="middle" 垂直对齐方式(参数有top、middle、bottom)
  • 可指定宽高度
    • width="500" 单元格的宽度，设置后对当前一列的单元格都有影响
    • height="100" 单元格的高度，设置后对当前一行的单元格都有影响
  • 可指定颜色
    • bgcolor="#ffff00" 背景色

---

语法

<table>
<thead>
<tr>
  <th>列标题1</th>
  <th>列标题2</th>
  <th>列标题3</th>
</tr>
</thead>
<tbody>
<tr>
  <td>行1，列1</td>
  <td>行1，列2</td>
  <td>行1，列3</td>
</tr>
<tr>
  <td>行2，列1</td>
  <td colspan="2" align="center">行2，列2、3</td>
</tr>
<tr>
  <td rowspan="2">行3、4，列1</td>
  <td>行3，列2</td>
  <td>行3，列3</td>
</tr>
<tr>
  <td>行4，列2</td>
  <td>行4，列3</td>
</tr>
<tr>
  <td>行5，列1</td>
  <td>行5，列2</td>
  <td><ul><li>A</li><li>B</li><li>C</li></ul>
</tr>
</tbody>
</table>

效果

列标题1	列标题2	列标题3
行1，列1	行1，列2	行1，列3
行2，列1	行2，列2、3
行3、4，列1	行3，列2	行3，列3
	行4，列2	行4，列3
行5，列1	行5，列2	A B C

---

图形语法mermaid

CSDN篇幅限制，请参考原始项目地址。

符号公式语法LaTeX

CSDN无法显示符号公式，请参考原始项目地址。

mdbook使用

CSDN篇幅限制，请参考原始项目地址。

---

1. Markdown是一种轻量级标记语言，排版语法简洁，让人们更多地关注内容本身而非排版。它使用易读易写的纯文本格式编写文档，可与HTML混编，可导出 HTML、PDF 以及本身的 .md 格式的文件。 ↩︎