0. 什么是 Markdown

Markdown，简称 md，是一种让你专注于内容而非排版的轻量级标记语言。

它用几个简单的符号代替了复杂的菜单和按钮，让你像写纯文本一样完成排版。写完后，它可以一键转换为 HTML、PDF、Word 等格式，被 GitHub、Notion、Obsidian、微信公众号编辑器等主流平台广泛支持。

核心理念：易读、易写、跨平台、不依赖任何特定软件。

0.1 Markdown 文件规范

Markdown 是 纯文本文件，它没有私有的二进制结构，这意味着你可以用任何文本编辑器打开和编辑它。

0.1.1 常见的 Markdown 文件格式

最佳推荐：除非有明确的技术需求（如 MDX），否则一律使用 .md。它是事实标准，能确保最大兼容性和工具链支持。

0.1.2 Markdown 文件编码

• 必须使用 UTF-8：这是 Markdown 生态的绝对标准。
• 避免 BOM：如果你使用的编辑器有 "UTF-8 with BOM" 和 "UTF-8 without BOM" 两个选项，请选不带 BOM 的那个，带 BOM 可能导致文档开头的特殊信息（如博客文章的标题、日期等）无法被正确识别。

0.1.3 Markdown 文件结构

一个标准的 Markdown 通常由这三部分组成：

---
title: 文章标题
date: 2026-08-08
tags: [markdown, tutorial]
---

# 正文标题

这里是正文内容...

1. Markdown 标签基础

Markdown 的语法很少，核心只有 11 个符号。本章只讲解最常用的。

1.1 一级标题

在 Markdown 中使用 # 来渲染一级标题，注意 # 后需要一个空格。

# 这是一级标题，最大的标题

1.2 二级标题

在 Markdown 中使用 ## 来渲染二级标题，注意 ## 后需要一个空格。

## 这是二级标题

1.3 三级标题

在 Markdown 中使用 ### 来渲染三级标题，注意 ### 后需要一个空格。

### 这是三级标题

1.4 四级标题

在 Markdown 中使用 #### 来渲染四级标题，注意 #### 后需要一个空格。

#### 这是四级标题

1.5 五级标题

在 Markdown 中使用 ##### 来渲染五级标题，注意 ##### 后需要一个空格。

##### 这是五级标题

1.6 六级标题

在 Markdown 中使用 ###### 来渲染六级标题，注意 ###### 后需要一个空格。

###### 这是六级标题，最小的标题

1.7 粗体

在 Markdown 中使用 **文本** 来渲染粗体文本，无需空格，部分编辑器也支持 __文本__，注意 __文本__ 前后需要空格。

**这是粗体文本**
__这也是粗体文本__

1.8 斜体

在 Markdown 中使用 *文本* 来渲染斜体文本，无需空格；部分编辑器也支持 _文本_，注意 _文本_ 前后需要空格。

*这是斜体文本*
_这也是斜体文本_

1.7/8 风格建议

建议统一使用 **文本** 渲染粗体，*文本* 渲染斜体，避免混淆。

1.9 粗斜体

在 Markdown 中使用 ***文本*** 来渲染粗斜体文本，无需空格，为统一建议使用 **_文本_**。

***这是粗斜体文本***
**_这也是粗斜体文本_**

1.10 删除线

在 Markdown 中使用 ~~文本~~ 来渲染删除线，无需空格。

~~这是删除线文本~~

1.11 高亮

在 Markdown 中使用 ==文本== 来渲染高亮文本，无需空格。

==这是高亮文本，仅部分编辑器支持==

2. Markdown 标签进阶

2.1 行内代码

在 Markdown 中使用 `文本` 来渲染行内代码，无需空格。

使用`print()`函数输出

2.2 围栏代码块

在 Markdown 中使用三个反引号 ``` 来渲染围栏代码块。

```python
def hello():
    print("Hello,world!")
```

def hello():
    print("Hello,world!")

2.3 链接

在 Markdown 中使用 [显示文本](URL链接) 来渲染链接。

链接：[示例链接](https://baidu.com)
纯文本：https://example.com
自动链接：<https://example.com>
带标题的链接：[带标题的链接](https://example.com "鼠标悬停提示")

2.4 引用链接

在 Markdown 中使用 [显示文本][id] 和 [id]: URL 来渲染引用链接。

参见[安装指南][install]，完成后回到[快速开始][install]继续。

[install]: https://docs.example.com/getting-started

使用场景：

1. 需要统一管理链接。
2. 复用链接，不需要单独写。
3. 提升正文可读性。

2.5 图片

在 Markdown 中使用 ![替代文本](image.png) 来渲染图片。如需悬停显示，则需要 ![带标题的图片](image.png "悬停显示，即图片标题")。

![替代文本](image.png)
![带标题的图片](https://www.lanwane.top/media/logo/icon.png "悬停显示，即图片标题")

2.6 列表

Markdown 有以下几种常见的列表。

2.6.1 无序列表

使用 -、+、* 来标记，推荐使用 -。

- 苹果
- 香蕉
  - 红香蕉
  - 黄香蕉
- 橙子

嵌套规则：子列表需缩进 2~4 个空格（推荐 2 空格），且与父列表内容对齐。不同渲染器对缩进要求可能略有差异。

2.6.2 有序列表

使用数字 + . 作为标记。只有第一个数字影响起始序号，后续数字会被自动忽略。

1. 第一步
1. 第二步（写1也会渲染为2）
3. 第三步（写3仍渲染为3，但建议按顺序书写以方便维护）
   1. 子步骤A
   2. 子步骤B

虽然 Markdown 允许乱序编号，但始终按自然数递增书写，便于源码阅读和版本对比。

2.6.3 任务列表

在无序列表基础上加 [ ] 或 [x]，用于待办事项追踪。

- [x] 已完成的任务
- [ ] 未完成的任务
- [ ] 另一个待办
  - [x] 子任务已完成

2.6.4 定义列表

使用 : 定义术语解释，属于 PHP Markdown Extra / Pandoc 扩展语法。注意：绝大多数平台不支持该语法，会渲染为纯文本。

术语一
:   术语一的定义内容

术语二
:   术语二的定义内容
:   可以有多个定义

2.6.5 表格

| 列1标题 | 列2标题 | 列3标题 |
| :--- | :---: | ---: |
| 左对齐内容 | 居中对齐内容 | 右对齐内容 |
| 第二行数据 | 数据B | 数据C |

对齐方式：

单元格样式：

表格单元格内可以使用大部分行内元素：

| 功能 | 示例 |
| :--- | :--- |
| 加粗/斜体 | **粗体**、*斜体*、***粗斜体*** |
| 链接 | [点击跳转](https://example.com) |
| 代码 | `inline code` |
| 图片 | ![alt](img.png) |
| 换行 | 第一行<br>第二行 |

不支持的内容：块级元素（如标题 #、代码块 ```、列表 -、引用 >）不能在表格单元格内使用。需要换行时用 HTML <br> 标签。

2.7 引用块

使用 > 标记，支持多层嵌套和块内行内格式。注意需避免滥用嵌套。

> 一级引用内容
>
> > 二级嵌套引用
>
> 回到一级，支持 **加粗**、*斜体*、[链接](url) 等行内格式

注意事项

• 段落之间需保留一个空行（仍带 >），否则会被渲染为同一段落内的换行。
• 嵌套层级理论上无限，但超过 3 层可读性急剧下降，建议改用列表或缩进。
• 引用块内不支持块级元素（如标题、代码块、表格），仅支持行内元素。

2.8 分割线

使用三个或以上 -、* 或 _（单独一行），用于分隔文档的逻辑章节。

---

***

___

注意事项

• 符号之间可以有空格，但不能有其他字符，否则会被解析为列表或普通文本。
• 推荐使用 ---，与 YAML Front Matter 保持一致，减少记忆负担。
• 分割线前后建议各留一个空行，避免与上下文粘连导致渲染异常。

2.9 脚注

使用 [^id] 标记引用位置，[^id]: 内容 定义脚注文本，属于 GFM / Pandoc 扩展语法。

这是一段包含脚注的文本[^1]，还可以有多个[^note]。

[^1]: 第一条脚注内容，会自动渲染在文档底部。
[^note]: 标识符可以是数字或字母，不区分大小写。
    支持多行内容，第二行起需缩进 4 个空格或 1 个制表符。

3. 结语

从「会写语法」到「写好文档」

掌握 Markdown 的全部语法只是起点，真正决定文档质量的是结构意识与读者视角。以下三条原则比任何语法规则都更重要：

1. 内容优先于格式
   不要为了用语法而用语法。如果一段文字用纯文本就能清晰表达，就不必强行加粗、引用或列表。最好的排版是让读者忘记排版的存在。

2. 为未来的自己而写
   文档是写给三个月后已经忘记上下文的自己看的。保持源码整洁、链接集中管理、标题层级语义化，这些习惯会在长期维护中节省数倍时间。

3. 了解你的渲染器
   同一份 Markdown 在 GitHub、Obsidian、微信公众号、邮件客户端中的表现可能截然不同。发布前务必在目标平台预览，对不支持的语法提前准备降级方案。

建议：把这份速查当作工具而非教条。当语法规则与表达清晰度冲突时，永远选择后者。Markdown 的本质是让写作回归内容本身，而不是成为另一种需要精通的排版语言。

祝写作愉快！

by 澜湾
by LanWan