Markdown 完整详细教程

Markdown 是一种轻量级标记语言，用简单符号标记文本格式，可直接阅读，能一键转为 HTML、PDF、Word。
适用场景：笔记(Obsidian/Notion)、Github/Gitee、文档、README、博客、知乎、语雀等。
⚠️ 注意：不同平台存在少量扩展语法差异（GFM 是最通用版本：GitHub Flavored Markdown，下面以 GFM 为主）

基础语法（必学）
段落、换行、转义
标题
文本样式：粗体、斜体、删除线、下划线、高亮
列表：无序列表、有序列表、任务列表
引用块
代码：行内代码、代码块、语法高亮
链接：普通链接、引用式链接、自动链接
图片
表格
分割线
脚注（扩展语法）
定义列表（扩展语法）
内嵌 HTML（高级）
目录自动生成
常用转义字符清单
Obsidian / Github / 语雀差异说明
完整示例文档
实用工具推荐

1. 标题（6级）

两种写法，推荐# 号写法，兼容性最好

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

等价写法（仅一级、二级可用）

一级标题
=====

二级标题
-----

规范：#后面必须加空格；标题单独占一行；不要混用两种写法。

渲染效果：

一级标题

二级标题

三级标题

2. 段落、换行、空行

段落

段落之间用【空一行】分隔（敲两次回车）

第一段文字。

第二段文字。

换行（软换行）

很多编辑器：行末尾加两个空格，再回车，实现强制换行，不产生新段落。

这是第一行（末尾两个空格）  
这是同一段落的第二行

⚠️ Obsidian 支持直接回车换行；Github 必须末尾两个空格。

转义符号 `\`

当你想原样输出 Markdown 符号（# * > [] ()等），在符号前面加反斜杠`

\# 这不是标题，只是输出 #
\*星号原样显示

3. 文本样式

*斜体文本*
_斜体文本_

**粗体文本**
__粗体文本__

***粗斜体文本***
___粗斜体文本___

~~删除线~~

==高亮文本==  <!-- 扩展语法，Github不支持，Obsidian/语雀支持 -->

<u>下划线文本</u> <!-- 使用内嵌HTML，原生MD无下划线语法 -->

渲染效果：
斜体文本
粗体文本
粗斜体文本
~~删除线~~
==高亮文本==
<u>下划线文本</u>

✅ 推荐优先用 *，兼容性优于 _；不要混用 * 和 _

4. 列表

无序列表

符号支持：*、+、-，符号后必须加空格

- 项目1
- 项目2
  - 子项目（缩进2个空格）
  - 子项目
- 项目3

有序列表

数字 + . + 空格；数字编号不影响渲染顺序，渲染自动按1,2,3排序

1. 第一项
2. 第二项
   1. 二级有序列表
   2. 二级第二项
3. 第三项

技巧：维护文档时，不用重新修改序号，直接增删行，渲染自动排序。

任务列表（复选框，GFM 扩展）

- [ ] 未完成任务
- [x] 已完成任务（x大小写均可）
- [ ] 任务2
  - [x] 子任务

渲染：

未完成任务
已完成任务

5. 引用块 `>`

> 代表引用，可以嵌套，多层引用叠加 >>

> 一级引用
> 可以换行继续写
>
>> 二级嵌套引用
>>> 三级嵌套引用

渲染：

一级引用

二级嵌套引用

引用内可以混合使用粗体、列表：

引用里的任务

加粗文字

6. 代码

行内代码（单行短代码）

使用反引号 \` 包裹

执行命令 `docker ps`；变量 `name`

效果：执行命令 docker ps

代码块（多行代码，推荐三反引号 ```）

```python
# python代码示例
def hello():
    print("Hello Markdown")

> ```后面可以指定语言名称，开启语法高亮：python、js、bash、sql、yaml、html、java等
> 不写语言名：纯文本代码块

可选旧写法：4空格缩进（不推荐，不方便复制，不支持高亮）
    这是缩进代码块

7. 链接

行内链接（最常用）

格式：[链接显示文字](链接地址 "可选悬浮提示文字")

[百度](https://www.baidu.com "百度首页")

自动链接（直接尖括号包裹网址/邮箱）

<[https://www.baidu.com](https://www.baidu.com)>
<test@example.com>

效果：<https://www.baidu.com>

引用式链接（长文档推荐，便于统一管理链接）

[文档][ref1]
[Github][ref2]

[ref1]: [https://xxx.com](https://xxx.com) "可选标题"
[ref2]: [https://github.com](https://github.com)

好处：链接地址统一放文末，正文干净，修改一次全局生效。

8. 图片

语法和链接很像，前面多一个 !
格式：![图片替代文字](图片地址 "悬浮标题")

![图片描述](https://xxx/test.png "图片标题")

替代文字：图片加载失败时显示
图片地址：网络URL / 本地相对路径（Obsidian常用）

本地图片示例（Obsidian）：![](./assets/photo.jpg)

❗ Markdown原生不能设置图片大小，需要内嵌HTML：

<img src="test.png" width="400" alt="图片">

9. 表格（GFM扩展）

| 姓名 | 年龄 | 城市 |
| ---- | ---- | ---- |
| 张三 | 20 | 温州 |
| 李四 | 22 | 杭州 |

控制对齐方式：

---：默认左对齐
:---：左对齐
---:：右对齐
:---:：居中对齐

| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| aaa | bbb | ccc |

渲染：

左对齐	居中对齐	右对齐
aaa	bbb	ccc

简写：首尾竖线可以省略，但建议保留，可读性更好。

10. 分割线

三个及以上 * - _，单独一行

***
---
___

渲染：

11. 脚注（扩展语法，Obsidian/Gitbook支持，Github部分支持）

这里有一句话[^note1]

[^note1]: 脚注内容，可以写很长。

鼠标悬浮可查看注释，文末自动生成脚注列表。

12. 内嵌 HTML

Markdown 支持直接嵌入 HTML，用来实现原生MD做不到的效果：

<p align="center">居中文字</p>
<u>下划线</u>
<br> <!-- 换行 -->

注意：部分平台（Github）会过滤危险HTML标签。

13. 目录

原生 Markdown 没有目录语法

Github：自动识别标题生成目录；
Obsidian：插件 [[_TOC_]]；
GitBook：{% include toc %}

14. 转义字符清单

下面这些符号，前面加 \ 就可以原样输出：

\ 反斜杠
` 反引号
* 星号
_ 下划线
# 井号
+ 加号
- 减号
. 点
! 感叹号
[](){}<> 括号
| 竖线（表格）

示例：

\* 星号，不是斜体
\# 井号，不是标题
\| 竖线，不是表格分隔

15. 平台语法差异（重点避坑）

功能	GitHub GFM	Obsidian	语雀	简书
==高亮==	❌	✅	✅	❌
脚注	✅	✅	✅	❌
任务列表	✅	✅	✅	✅
表格	✅	✅	✅	✅
内嵌HTML	部分支持	✅	✅	✅
Mermaid流程图	✅	✅（插件）	✅	❌

Obsidian额外支持：内部链接 [[笔记名]]、块引用 ^blockid、callout 提示框。

Obsidian Callout（提示框扩展语法）

> [!note] 提示
> 普通提示信息

> [!warning] 警告
> 注意风险！

> [!tip] 小技巧
> 好用的方法

16. Mermaid 流程图（扩展，Github/Obsidian支持）

很多现代markdown编辑器支持Mermaid，直接在代码块写图表，不用图片

```mermaid
graph LR
A[开始] --> B{判断}
B -->|是| C[执行]
B -->|否| D[结束]

支持：流程图、时序图、甘特图、饼图等。

---

# 17. 完整 Markdown 示例文档（直接复制测试）
```markdown
# Markdown 测试文档
## 二级标题
### 三级标题

这是一段普通段落。

这是**粗体**，这是*斜体*，这是***粗斜体***，~~删除线~~。

> 引用块示例
> - [x] 已完成任务
> - [ ] 待办任务

无序列表：
- 项目A
- 项目B
  - 子项目B1

有序列表：
1. 第一项
2. 第二项

行内代码：`print("hello")`

代码块：
```bash
ls -l
pwd

链接：百度

表格：

产品	价格	数量
A	100	2
B	200	5

图片：


---

# 18. 推荐工具
## Markdown编辑器
1. Obsidian：本地笔记，双链，扩展语法强（推荐）
2. Typora：所见即所得编辑器（收费）
3. VS Code + Markdown All in One 插件：电脑端写文档
4. Logseq：大纲笔记
5. 在线：Markdown Live Preview、Dillinger.io（实时预览）

## 预览网站
[https://dillinger.io/](https://dillinger.io/) 粘贴直接看渲染效果

---

# 19. 编写规范（团队文档推荐遵守）
1. `#` 标题后必须空格；
2. 段落之间空一行；
3. 列表符号 `-` `*` 后面加空格；
4. 代码块统一用 ```，不要用4空格缩进；
5. 表格尽量对齐竖线，可读性更高；
6. 长链接优先使用引用式链接；
7. 尽量少用HTML，保证跨平台兼容。

如果你需要，我可以额外输出：
1. **Markdown 速查表（精简版，适合复制到Obsidian）**
2. **Mermaid全套语法教程**
3. **Obsidian专属Markdown扩展语法完整手册**
4. 导出为 `.md` 文件纯文本内容，直接下载使用。