Markdown学习手册

发表于 更新于 分类于 阅读次数： 本文字数： 4.9k 阅读时长 ≈ 18 分钟

Markdown学习手册

文档核心说明

本文档是面向 Markdown 学习者的标准化学习手册，整合了 Markdown 语法全教程与 MarkItDown 文档转换工具使用指南，覆盖从入门到进阶的全流程内容：

  • 适用人群：Markdown 新手、技术写作者、文档处理从业者、RAG 开发人员

  • 核心模块：Markdown 基础认知、核心语法、进阶语法、平台技巧、编辑工具、常见问题、MarkItDown 文档转换、企业级文档清洗方案

一、Markdown 基础入门

1.1 什么是 Markdown

Markdown 是 2004 年由 John Gruber 创造的轻量级纯文本标记语言，通过极简的符号标记，给普通文本赋予排版格式，最终渲染为富文本。文件后缀为 \.md 或 \.markdown，可被几乎所有文本编辑器打开。

它的核心理念是重内容、轻形式，不用鼠标点选排版按钮，打字的同时就能完成格式设置，学习成本极低，上手即用。

1.2 核心优势

  • 纯文本兼容：文件体积极小，跨平台、跨设备无格式错乱问题，永远可以打开

  • 语法极简：核心语法不超过 10 个，10 分钟即可掌握日常 90% 的使用场景

  • 全平台适配：笔记、博客、技术文档、GitHub 仓库、公众号、论坛等全场景支持

  • 兼容 HTML：原生语法不支持的效果，可直接嵌入 HTML 标签实现

  • 生态丰富：配套编辑器、插件、工具极多，支持公式、流程图、思维导图等扩展能力

1.3 快速上手：第一个 md 文件

  1. 新建一个文本文档，将后缀名从 \.txt 改为 \.md

  2. 用 Markdown 编辑器（推荐 VS Code、Typora、Obsidian）打开文件

  3. 输入以下内容，保存后即可看到渲染效果

1
2
3
4
5
6
7
8
# 我的第一篇Markdown笔记
## 个人介绍
我是一名Markdown学习者，**这是加粗的重点内容**。

## 学习计划
- [x] 掌握基础语法
- [ ] 学习进阶技巧
- [ ] 完成一篇完整的技术文档

二、Markdown 核心基础语法（必学，全平台通用）

这部分是 Markdown 的通用语法，所有支持 Markdown 的平台 100% 兼容，是必须掌握的核心内容。

2.1 标题

用 \# 号标记 1-6 级标题，\# 数量对应标题级别，#后必须加空格，否则部分渲染器无法识别。

语法示例 渲染效果 说明
\# 一级标题 一级标题 最大字号，通常用于文档主标题
\#\# 二级标题 二级标题 用于大章节标题
\#\#\# 三级标题 三级标题 用于子章节标题
\#\#\#\# 四级标题 四级标题 用于小节标题
\#\#\#\#\# 五级标题 五级标题 用于细分内容
\#\#\#\#\#\# 六级标题 六级标题 最小字号，用于备注内容

补充：原生 Markdown 还支持用 = 和 \- 标记一级 / 二级标题，仅作了解，不推荐使用。

2.2 段落与换行

这是新手最容易踩坑的语法，Markdown 对换行有严格的规则：

  1. 段落分隔：两个段落之间必须用一个空白行隔开（连续两次回车），否则会被识别为同一段落

  2. 强制换行：行尾添加2 个空格 + 1 次回车，即可在同一段落内换行，无需空白行

  3. 兼容换行：直接用 HTML 标签 \<br\> 换行，全平台通用，无兼容性问题

示例：

1
2
3
4
5
6
7
8
这是第一个段落
这一行和上面没有空白行，会被渲染为同一段落，中间只有一个空格

这是第二个段落，和上面有空白行，是独立的段落
这一行结尾加了2个空格
这一行会强制换行，和上一行属于同一段落

这是第三段<br>用HTML标签强制换行

2.3 文本格式

用简单符号包裹文本，实现常用的字体样式，符号与文本之间不要加空格。

语法示例 渲染效果 兼容性
\*\*加粗文本\*\* 加粗文本 全平台通用
\*斜体文本\* 斜体文本 全平台通用
\*\*\*加粗斜体\*\*\* 加粗斜体 全平台通用
\~\~删除线文本\~\~ 删除线文本 GFM 通用，原生 Markdown 不支持
\&lt;u\&gt;下划线文本\&lt;/u\&gt; 下划线文本 全平台通用（HTML 兼容，原生无此语法）

补充：斜体和加粗也可以用 \_ 替代 \*，比如 \_斜体\_、\_\_加粗\_\_，但推荐使用 \*，避免和代码、变量名冲突，兼容性更好。

2.4 列表

分为无序列表、有序列表、嵌套列表，列表符号后必须加空格。

2.4.1 无序列表

用 \- / \* / \+ 加空格标记，推荐使用 \-，可读性和兼容性最佳。

1
2
3
4
5
- 无序列表项1
- 无序列表项2
  - 嵌套列表项1（缩进1个Tab/4个空格）
  - 嵌套列表项2
    - 三级嵌套列表项

2.4.2 有序列表

用 数字\. 空格 标记，数字顺序不影响最终渲染结果，渲染器会自动按顺序编号，懒人可以全写 1\.。

1
2
3
4
5
1. 有序列表项1
2. 有序列表项2
1. 有序列表项3（这里写1也会自动渲染为3）
   1. 嵌套有序列表项1（缩进1个Tab/4个空格）
   2. 嵌套有序列表项2

2.4.3 混合列表

有序列表和无序列表可以互相嵌套，只需控制好缩进即可，列表内还可以嵌套引用、代码块、图片等其他语法。

1
2
3
4
5
6
7
8
1. 前端开发学习
   - HTML基础
   - CSS进阶
   - JavaScript核心
2. 后端开发学习
   1. Java基础
   2. Spring框架
   3. 数据库优化

2.5 引用区块

用 \&gt; 空格 标记引用内容，支持多层嵌套，也可以嵌套其他 Markdown 语法。

基础示例：

1
2
3
4
5
6
7
8
9
> 这是一级引用内容
> 引用可以跨多行，每行开头都加>
> > 这是二级嵌套引用
> > > 这是三级嵌套引用
>
> 引用内也可以使用其他语法：
> - 列表项1
> - 列表项2
> **加粗内容**

2.6 分割线

单独一行，输入3 个及以上的 \- / \* / \_，即可生成分割线，推荐使用 \-\-\-，可读性最佳。

注意：分割线必须单独占一行，前后最好留空白行，避免和二级标题混淆。

示例：

1
2
3
---
***
___

2.7 链接与图片

2.7.1 链接

核心语法：\[链接显示文本\]\(链接地址 \&\#34;可选的链接标题\&\#34;\)，鼠标悬浮在链接上会显示标题内容。

  1. 内联链接（最常用）
1
2
[百度一下](https://www.baidu.com "百度搜索引擎")
[本教程的一级标题](#一Markdown-基础入门)
  1. 引用式链接（适合长链接，方便管理）
1
2
3
4
这是[Markdown官方教程][1]，这是[GitHub官网][2]

[1]: https://daringfireball.net/projects/markdown/ "Markdown官方网站"
[2]: https://github.com "GitHub"
  1. 自动链接
    用 \&lt;\&gt; 包裹网址 / 邮箱，自动转为链接，适合直接展示完整链接。
1
2
<https://www.baidu.com>
<example@mail.com>

2.7.2 图片

核心语法：\\\，和链接语法相比，只是前面多了一个 \!。

图片地址可以是本地文件路径（相对 / 绝对路径），也可以是网络图片链接。

  1. 基础图片插入
1

  1. 图片加链接（点击图片跳转到指定网址）
1
[![Image](tos-cn-i-a9rns2rl98/rc/online_export/81c53ceee1d54e87be32050e705045b4?width=560&height=560)](https://github.com)

避坑提示：本地图片路径错误、网络图片链接失效，都会导致图片无法显示，推荐使用稳定的图床存储图片，避免路径失效。

2.8 代码与代码块

Markdown 对代码有极佳的支持，是技术文档、笔记的核心语法。

2.8.1 行内代码

用单个反引号 ` 包裹代码，适合在段落中插入短代码、变量名、命令等。

1
Python中的打印函数是 `print("hello world")`，终端中查看文件列表用 `ls` 命令。

2.8.2 围栏代码块（推荐）

用 **3 个反引号 \*\* 包裹代码块，开头的 后可以标注编程语言，实现语法高亮，几乎所有平台都支持，是最常用的代码块写法。

示例：

1
2
3
4
5
6
​```python
# Python代码示例
def say_hello():
    print("Hello Markdown!")

say_hello()
Text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
> 补充：支持几乎所有编程语言，只需把 `python` 替换为对应的语言名，比如 `java`、`javascript`、`c++`、`go`、`sql`、`bash` 等。

#### 2.8.3 缩进式代码块
原生Markdown语法，每行代码缩进**4个空格**或**1个Tab**，即可生成代码块，**不支持语法高亮**，不推荐使用，仅作了解。

### 2.9 表格
用 `|` 分隔单元格，表头和内容之间用 `---` 分隔，用 `:` 控制单元格的对齐方式。
> 注意：表格前后最好留空白行，避免渲染错乱；首尾的 `|` 可以省略，但推荐加上，可读性更好。

基础语法：
​```markdown
| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| 内容1 | 内容2 | 内容3 |
| 长文本内容示例 | 居中展示 | 右对齐展示 |

对齐规则：

  • :\-\-\- 冒号在左边，左对齐（默认）

  • :\-\-\-: 冒号在两边，居中对齐

  • \-\-\-: 冒号在右边，右对齐

三、Markdown 进阶语法（提升文档表现力）

这部分语法多为 GFM 扩展或主流编辑器支持，可按需学习，实现更丰富的文档效果。

3.1 任务列表（待办清单）

GFM 通用语法，GitHub、Obsidian、语雀等平台均支持，语法：\- \[ \] 内容 表示未完成，\- \[x\] 内容 表示已完成，括号内必须有空格，x 小写。

1
2
3
4
5
6
### 本周待办
- [x] 完成Markdown教程编写
- [ ] 整理学习笔记
- [ ] 开发项目需求
  - [ ] 完成接口开发
  - [ ] 编写单元测试

3.2 目录自动生成

在文档开头输入 \[TOC\]，编辑器会自动根据文档的标题层级，生成可跳转的目录，Typora、语雀、掘金等平台均支持，原生 Markdown 和 GitHub 不支持此语法。

GitHub 替代方案：可通过 VS Code 插件自动生成目录，或手动用内联链接锚定标题。

3.3 脚注

为文本添加注释说明，注释内容会自动渲染到文档末尾，支持点击跳转，主流编辑器均支持。

1
2
3
4
这是Markdown教程中的一个知识点[^1]，还有一个补充说明[^2]。

[^1]: 这是第一个脚注的详细说明，会自动显示在文档末尾。
[^2]: 这是第二个脚注的详细内容。

3.4 上标与下标

语法示例 渲染效果 说明
x^2^ x² GFM 上标语法，部分编辑器支持
H\~2\~O H₂O GFM 下标语法，部分编辑器支持
\&lt;sup\&gt;上标内容\&lt;/sup\&gt; 上标内容 HTML 语法，全平台通用
\&lt;sub\&gt;下标内容\&lt;/sub\&gt; 下标内容 HTML 语法，全平台通用

3.5 文本高亮

用 == 包裹文本，实现背景高亮效果，GFM 扩展语法，Typora、Obsidian 等编辑器支持，部分平台需手动开启功能。

1
这是==高亮的重点内容==，需要特别注意。

3.6 定义列表

用于术语解释，Pandoc、Typora、MDN 等平台支持，语法如下：

1
2
3
4
5
Markdown
:  一种轻量级纯文本标记语言，用于快速排版文档。

GFM
:  GitHub Flavored Markdown，GitHub推出的Markdown扩展规范，是目前的主流标准。

3.7 LaTeX 数学公式

主流 Markdown 编辑器均支持基于 KaTeX/MathJax 的 LaTeX 公式渲染，是写数学、科研笔记的核心功能。

  1. 行内公式：用 $ 包裹公式，嵌入在段落中
1
质能方程是 $E=mc^2$，一元二次方程的求根公式是 $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$
  1. 块级公式：用 $$ 包裹公式，单独成行，居中展示
1
2
3
4
5
6
7
$$
\sum_{i=1}^n a_i = 0
$$

$$
\int_{0}^{+\infty} e^{-x} dx = 1
$$

3.8 Mermaid 流程图 / 图表

Mermaid 是基于 Markdown 的图表绘制工具，支持流程图、时序图、甘特图、饼图、思维导图等，目前 VS Code、Typora、GitHub、语雀等主流平台均已原生支持。

基础流程图示例：

1
2
3
4
5
6
7
8
​```mermaid
flowchart LR
A[开始] --> B{是否掌握基础语法?}
B -->|是| C[学习进阶语法]
B -->|否| D[反复练习基础语法]
D --> B
C --> E[完成全教程学习]
E --> F[结束]
Text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
### 3.9 HTML 内嵌语法
Markdown完全兼容HTML，所有原生语法不支持的排版效果，都可以用HTML标签实现，全平台通用。

常用示例：
​```markdown
<!-- 字体颜色 -->
<font color="red">红色文字</font>
<font color="#008000">绿色文字</font>

<!-- 内容居中 -->
<center>这段文字会居中显示</center>

<!-- 折叠面板（点击展开/收起） -->
<details>
<summary>点击展开查看详细内容</summary>
这里是折叠起来的内容，支持嵌套Markdown语法：
- 列表项1
- 列表项2
**加粗内容**
</details>

<!-- 调整图片大小 -->
<img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png" width="100" height="100">

3.10 注释

用 HTML 注释语法 \&lt;\!\-\- 注释内容 \-\-\&gt;，注释内容仅在编辑时可见，渲染后不会显示在文档中。

1
2
这是正文内容，会正常显示
<!-- 这是注释内容，渲染后看不到 -->

四、Markdown 平台技巧与排版规范

4.1 GitHub 专属语法

GitHub 是目前最主流的 Markdown 使用场景之一，除了 GFM 标准语法，还支持以下专属功能：

  1. 告警提示块
1
2
3
4
5
6
7
8
9
10
11
12
13
14
> [!NOTE]
> 提示信息，用于补充说明。

> [!TIP]
> 实用技巧，帮助用户更好地使用功能。

> [!IMPORTANT]
> 重要信息，必须用户关注的内容。

> [!WARNING]
> 警告信息，存在潜在风险。

> [!CAUTION]
> 高危提示，必须规避的操作。

  1. 表情符号
    用 :表情名: 插入表情，比如 :smile: 😄、:star: ⭐、:warning: ⚠️，完整表情列表可参考GitHub Emoji Cheat Sheet。

  2. 代码行高亮
    在代码块的语言名后添加 \{行号\}，即可高亮指定代码行：

1
2
3
4
5
​```python {1,3-4}
def say_hello():
    name = "Markdown"
    print(f"Hello {name}!")
    return True
Text
1
2
3
4
5
6
7
8
9
10
11
12
13
14
4. **引用仓库内容**
在GitHub仓库内，可直接引用提交哈希、Issue、PR，会自动转为链接：
- 提交哈希：`#a1b2c3d`
- Issue/PR：`#123`
- 跨仓库引用：`用户名/仓库名#123`

### 4.2 转义字符
当你需要显示Markdown的特殊符号（比如 `#`、`*`、`-`、`\`、`~` 等），而不是触发排版效果时，在符号前加反斜杠 `\` 即可转义。

示例：
​```markdown
\# 这不是标题，会正常显示#号
\* 这不是列表，会正常显示*号
这不是斜体 \*文本\*

4.3 通用排版规范

遵循以下规范，可让你的 Markdown 文档在所有平台都有一致的排版效果，可读性拉满：

  1. 中文与英文、数字之间加一个空格，比如 Markdown 教程、2024 年

  2. 中文标点使用全角，英文、代码、数字使用半角

  3. 标题、代码块、表格、引用、分割线前后，都留一个空白行

  4. 所有 Markdown 标记符号（\#、\-、\*、\&gt; 等）后，必须加一个空格

  5. 列表嵌套统一使用 1 个 Tab 或 4 个空格缩进，避免混用

  6. 尽量使用通用语法，减少平台专属的扩展语法，避免跨平台渲染错乱

4.4 常用快捷键速记

几乎所有 Markdown 编辑器都支持以下快捷键，大幅提升写作效率：

快捷键 功能
Ctrl/Cmd + B 选中文本加粗
Ctrl/Cmd + I 选中文本斜体
Ctrl/Cmd + 数字 1-6 转为对应级别的标题
Ctrl/Cmd + K 插入链接
Ctrl/Cmd + Shift + I 插入图片
Ctrl/Cmd + Shift + ` 行内代码
Ctrl/Cmd + Shift + K 插入代码块
Ctrl/Cmd + Shift + [ 转为无序列表
Ctrl/Cmd + Shift + ] 转为有序列表

五、Markdown 编辑工具推荐

5.1 桌面端（首选）

工具 特点 适用人群 平台
Typora 所见即所得，颜值高，支持几乎所有 Markdown 语法，界面极简 普通用户、写作爱好者、学生 Windows/Mac/Linux
VS Code 免费开源，插件生态拉满，安装 Markdown 相关插件后功能无敌，支持代码、文档一体化 开发者、技术写作者 Windows/Mac/Linux
Obsidian 本地优先，双链笔记核心，插件生态极强，支持知识图谱，适合搭建个人知识库 知识管理爱好者、学生、研究者 Windows/Mac/Linux
Notion 块级编辑，支持 Markdown，团队协作、知识库、项目管理一体化 团队协作、个人知识库 Windows/Mac/Web
语雀 阿里出品，中文支持好，云端同步，团队协作能力强，支持知识库、博客 中文用户、团队协作 Windows/Mac/Web

5.2 在线编辑器

  • MdEditor：国内开源在线 Markdown 编辑器，功能全面，支持导出 PDF / 图片 / HTML

  • Dillinger：经典国外在线 Markdown 编辑器，界面简洁，支持云端同步

  • 马克飞象：支持与印象笔记同步，适合印象笔记用户

  • GitHub Gist：代码片段分享工具，原生支持 Markdown，适合开发者分享文档

5.3 移动端

  • Obsidian 移动端：全平台同步，和桌面端功能一致，支持双链

  • 语雀 APP：云端同步，移动端编辑体验优秀

  • 幕布：大纲笔记工具，支持 Markdown 语法，一键生成思维导图

  • 熊掌记：苹果生态专属，颜值高，Markdown 支持完善，适合苹果用户

5.4 实用插件推荐

  • VS Code：

    • Markdown All in One：一站式 Markdown 插件，快捷键、目录、自动补全全支持

    • Markdown Preview Enhanced：增强预览，支持公式、Mermaid、导出 PDF

    • Paste Image：一键粘贴图片到文档，自动生成相对路径

  • Chrome 浏览器：

    • Markdown Here：一键给邮件、公众号、论坛内容用 Markdown 排版

    • Markdown Viewer：直接在浏览器中预览本地.md 文件

六、Markdown 常见问题与避坑指南

6.1 为什么回车不换行？

原生 Markdown 中，单个回车会被识别为一个空格，不会换行。

  • 解决方案 1：行尾加 2 个空格，再按回车

  • 解决方案 2：连续按两次回车，生成新段落

  • 解决方案 3：用 HTML 标签 \&lt;br\&gt; 强制换行

6.2 为什么语法在 A 编辑器能用，B 编辑器不行？

Markdown 存在多个方言（标准 Markdown、GFM、Pandoc 等），基础语法全平台通用，进阶扩展语法存在兼容性差异。

  • 解决方案：跨平台文档尽量使用通用基础语法，减少扩展语法；提前确认目标平台支持的语法规范。

6.3 图片不显示怎么办？

图片不显示 99% 的原因是路径错误或链接失效：

  • 本地图片：检查相对路径 / 绝对路径是否正确，推荐把图片放在和 md 文件同级的 assets 文件夹，用相对路径引用

  • 网络图片：检查链接是否可以正常访问，是否有防盗链限制，推荐使用稳定的公共图床 / OSS 存储图片

6.4 表格渲染错乱怎么办？

  • 检查表头和分隔行的 \| 数量是否一致，单元格数量是否对应

  • 检查分隔行的 \-\-\- 是否正确，对齐符号 : 是否写在短横线两侧

  • 表格前后留空白行，避免和上文内容连在一起

  • 推荐首尾都加上 \|，减少渲染异常

6.5 代码块语法高亮不生效？

  • 检查 \\\\后填写的语言名是否正确，比如python不能写成py`

  • 部分编辑器需要安装对应语言的语法高亮插件，安装后重启即可

  • 原生缩进式代码块不支持语法高亮，必须使用围栏代码块 \\\`

6.6 特殊符号显示异常 / 触发排版？

  • 解决方案：在特殊符号前加反斜杠 \\ 进行转义，比如 \#、\*、\( 等

  • 常见坑：日期 2024\.05\.01 会被识别为有序列表，需写成 2024\.05\.01 转义