Markdown 语法大全（最全最完整版）

版本：v1.0
日期：2026-05-26
说明：本文档涵盖了 Markdown 的所有标准语法、扩展语法、主流平台（GitHub Flavored Markdown、CommonMark、MultiMarkdown、Marxico、Typora、Obsidian 等）支持的语法，以及 HTML 内嵌用法，力求成为最全面、最广泛的 Markdown 语法参考手册。

目录

• 一、概述与基础概念
• 二、标题（Headings）
• 三、段落与换行
• 四、文本样式（强调）
• 五、列表
• 六、链接
• 七、图片
• 八、引用（Blockquote）
• 九、分隔线（Horizontal Rule）
• 十、代码
• 十一、表格
• 十二、脚注（Footnote）
• 十三、任务列表（Task List）
• 十四、删除线（Strikethrough）
• 十五、表情符号（Emoji）
• 十六、高亮标记（Highlight）
• 十七、下标与上标（Subscript / Superscript）
• 十八、定义列表（Definition List）
• 十九、缩写（Abbreviation）
• 二十、数学公式（Math / LaTeX）
• 二十一、流程图与图表（Mermaid）
• 二十二、HTML 内嵌
• 二十三、转义字符
• 二十四、元数据 / YAML Front Matter
• 二十五、目录（Table of Contents）
• 二十六、嵌入视频与音频
• 二十七、嵌入 iframe
• 二十八、注释 / HTML 注释
• 二十九、锚点与内部跳转
• 三十、Diff 语法
• 三十一、Callout / Admonition（提示框）
• 三十二、属性语法（Attribute）
• 三十三、Obsidian 特殊语法
• 三十四、Docusaurus / MDX 扩展
• 三十五、GitBook 扩展语法
• 三十六、Markdown 编辑器快捷键速查
• 三十七、各平台兼容性速查表
• 三十八、完整示例
• 附录 A：Markdown 特殊字符速查
• 附录 B：Emoji 速查表（常用）
• 附录 C：LaTeX 数学符号速查
• 附录 D：Mermaid 图表类型速查

一、概述与基础概念

1.1 什么是 Markdown

Markdown 是一种轻量级标记语言，由 John Gruber 于 2004 年创建。它的设计理念是：易于阅读、易于书写、易于转换为 HTML 和其他格式。

1.2 Markdown 的标准与变体

1.3 设计哲学

• 纯文本格式，任何文本编辑器均可打开
• 语法简洁直观，即使不渲染也具有可读性
• 可方便地转换为 HTML、PDF、Word 等格式

二、标题（Headings）

Markdown 支持 6 级标题，使用 # 号标记：

2.1 ATX 风格（推荐）

一级标题（H1）

二级标题（H2）

三级标题（H3）

四级标题（H4）

五级标题（H5）

六级标题（H6）

注意：# 与标题文字之间必须至少有 1 个空格。部分编辑器要求更严格，建议保持 1 个空格。

2.2 Setext 风格（仅支持 H1 和 H2）

一级标题

二级标题

= 和 - 的数量至少为 1 个，但建议使用 3 个以上以提高可读性。

2.3 可选的闭合 # 号

一级标题

二级标题

三级标题 ### 闭合的 # 号数量不需要与开头一致

闭合 # 号为可选语法，并非所有解析器都支持，不建议使用。

2.4 标题最佳实践

• 一个文档通常只使用 一个 H1 标题
• 标题层级不要跳级（如 H1 直接到 H3）
• 标题前后建议空一行，保证兼容性

三、段落与换行

3.1 段落

段落之间使用 一个或多个空行 分隔：

这是第一段。

这是第二段。

3.2 换行

第一行（末尾有两个空格）
第二行

第一行
第二行

3.3 空行技巧

在部分编辑器中，多个空行可能会被合并为一个。如需强制插入多个空行，可使用：

第一段

第二段（中间有一个空行间距）

或者使用 HTML 实体：

第一段

第二段

四、文本样式（强调）

4.1 基础样式一览

4.2 加粗（Bold）

加粗文本
加粗文本

加粗可以包含斜体在内

注意：推荐使用 **（星号），因为 _（下划线）在部分解析器中与单词中间的下划线冲突。

4.3 斜体（Italic）

斜体文本
斜体文本

最佳实践：推荐使用 *（星号）。

4.4 加粗 + 斜体组合

加粗且斜体
加粗且斜体
加粗且斜体
加粗且斜体
加粗且斜体
加粗且斜体

4.5 嵌套强调

这是加粗文本，其中包含斜体部分
这是斜体文本，其中包含加粗部分

4.6 行内代码中的强调

行内代码中不支持 Markdown 语法，所有符号原样显示：

这段**不会被加粗**

渲染为：这段**不会被加粗**

五、列表

5.1 无序列表

使用 *、+ 或 - 作为列表标记：

• 项目一
• 项目二
• 项目三

• 项目一
• 项目二
• 项目三

• 项目一
• 项目二
• 项目三

三种写法效果完全相同，推荐统一使用 -。

5.2 有序列表

使用数字加 . 或 ) 标记：

1. 第一项

2. 第二项

3. 第三项

4. 第一项

5. 第二项

6. 第三项

1. 第一项
2. 第二项
3. 第三项

注意：有序列表的数字并不影响渲染结果，但推荐使用正确的顺序以提高可读性。

5.3 嵌套列表（子列表）

子列表需要 缩进 2~4 个空格或 1 个制表符：

• 项目一
  • 子项目 1.1
    • 子子项目 1.1.1
  • 子项目 1.2
• 项目二
  1. 子项目 2.1（有序）
  2. 子项目 2.2（有序）

5.4 列表中包含段落

列表项之间插入空行，即可包含多个段落，后续段落需缩进：

1. 第一段内容。

   这是同列表项中的第二段内容。（需要缩进 4 个空格或 1 个制表符）

2. 第二项。

5.5 列表中包含引用

• 项目一

  这是一条引用
  列表中的引用需要缩进

• 项目二

5.6 列表中包含代码块

• 项目一

  ```python
  print("Hello, World!")

• 项目二

  | 复制

列表中的代码块需要 额外缩进（通常再缩进 4 个空格）。

5.7 列表中包含图片

1. 项目一

   

2. 项目二

5.8 有序与无序混合嵌套

1. 第一项
   • 无序子项
   • 无序子项
2. 第二项
   1. 有序子项
   2. 有序子项

5.9 定义列表（MultiMarkdown / PHP Markdown Extra）

术语 A

定义 A 的说明

术语 B

定义 B 的说明

5.10 列表最佳实践

• 无序列表统一使用 -
• 子列表缩进使用 2 个或 4 个空格（保持一致）
• 列表前后建议空一行
• 列表项之间需要空行来分隔多段内容

六、链接

6.1 行内链接（Inline Link）

链接文本
链接文本

示例：

百度

6.2 引用式链接（Reference Link）

链接文本

或者：

链接文本

或者：

链接文本

隐式链接名

百度

6.3 自动链接（URL / 邮箱）

GFM 扩展语法，直接写 URL 会自动转换为链接：

https://example.com

user@example.com

标准 Markdown 中需要使用尖括号：

https://example.com
user@example.com

6.4 带格式的链接

加粗链接
斜体链接
代码链接

6.5 链接到标题（锚点）

跳转到二级标题

标题的锚点规则：

• 字母转小写
• 空格转为 -
• 特殊字符被移除
• 中文通常保持原样或被移除（取决于解析器）

6.6 链接在新标签页打开

Markdown 本身不支持此功能，需使用 HTML：

新窗口打开链接

七、图片

7.1 基本语法

示例：

7.2 引用式图片

7.3 带链接的图片

7.4 设置图片大小

标准 Markdown 不支持设置图片大小，需使用 HTML：

7.5 图片居中

或者：

7.6 带标题的图片（figure）

7.7 图片画廊（部分编辑器支持）

7.8 Base64 内嵌图片

八、引用（Blockquote）

8.1 基本语法

这是一段引用文本。
可以有多行。

8.2 省略中间的 >

这是一段引用。
虽然这行没有 > 符号，但仍然属于引用。
这行又回到了引用。

8.3 嵌套引用

第一层引用

第二层引用

第三层引用

8.4 引用中包含其他元素

引用中的列表

• 列表项 1
• 列表项 2
  • 子列表项

引用中的代码块

Python | 复制

print("引用中的代码块")

引用中的标题

引用中的标题

引用中的段落内容。

引用中的表格

列 1	列 2
A	B

8.5 引用最佳实践

• 空行也建议加 > 以提高可读性
• 引用块前后建议空一行

九、分隔线（Horizontal Rule）

使用三个或更多的 *、- 或 _：

注意：使用 --- 时需确保上一行不是文本，否则会被解析为 Setext 风格的二级标题。

十、代码

10.1 行内代码（Inline Code）

使用反引号包裹：

使用 console.log() 来输出调试信息。

10.2 行内代码中包含反引号

使用双反引号包裹：

这是一个包含 ` 反引号的代码

10.3 代码块（Code Block）— 缩进式

缩进 4 个空格或 1 个制表符：

第一行代码
第二行代码
第三行代码

10.4 代码块（Fenced Code Block）— 围栏式（推荐）

使用三个或更多反引号 ``或波浪号~~~`：

代码内容

代码内容

10.5 代码块指定语言（语法高亮）

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

支持的常用语言标识

语言标识不区分大小写。

10.6 代码块中的行号高亮（部分编辑器支持）

function example() {
  const a = 1;      // 高亮
  const b = 2;
  const c = 3;      // 高亮
  const d = 4;      // 高亮
  const e = 5;      // 高亮
  return a + b;
}

10.7 代码块标题（部分编辑器/插件支持）

console.log("Hello");

或：

console.log("Hello");

10.8 代码块 Diff 显示

+ 新增的行
- 删除的行
  未修改的行

十一、表格

11.1 基本语法

11.2 对齐方式

• :--- 或 ---：左对齐（默认）
• :---:：居中对齐
• ---:：右对齐

11.3 简化写法

列两侧的 | 可以省略，分隔线的 - 至少需要一个：

11.4 表格中包含其他元素

包含链接

包含行内代码

包含加粗/斜体

11.5 表格中使用 | 字符

使用 HTML 实体 | 表示管道符：

11.6 多行表格（部分扩展支持）

MultiMarkdown 扯展：

十二、脚注（Footnote）

支持：MultiMarkdown、Obsidian、Typora、Marxico 等

12.1 基本语法

这是一段带有脚注的文本¹。

这是另一段文本²。

12.2 命名脚注

这是脚注³。

12.3 行内脚注（部分解析器支持）

这是行内脚注^[行内脚注的内容]。

十三、任务列表（Task List）

GFM 扩展语法

13.1 基本语法

• 已完成的任务
• 未完成的任务
• 另一个未完成任务

13.2 嵌套任务列表

• 任务组 A
  • 子任务 A.1
  • 子任务 A.2
• 任务组 B
  • 子任务 B.1
  • 子任务 B.2

13.3 有序任务列表

1. 第一步
2. 第二步
3. 第三步

注意：[x] 和 [ ] 中的 x 不区分大小写，[ 和 ] 与内容之间无空格。

十四、删除线（Strikethrough）

GFM 扩展语法

这段文本会被加上删除线

渲染效果：这段文本会被加上删除线

十五、表情符号（Emoji）

15.1 使用 Emoji 代码

:smile: :heart: :thumbsup: :rocket: :fire:

15.2 直接使用 Unicode Emoji

😀 ❤️ 👍 🚀 🔥 ✅ ❌ ⭐ 📌 📝 🎉 💡 ⚠️ 🔗 💻 📱 🌍 🎯 📊 📅

15.3 常用 Emoji 代码表

十六、高亮标记（Highlight）

支持：Marxico、Obsidian、Typora 等

高亮文本

渲染效果：高亮文本（带黄色背景）

HTML 方式（更通用）：

高亮文本

十七、下标与上标（Subscript / Superscript）

MultiMarkdown、Obsidian 等支持

17.1 下标

H~2~O 是水的化学式

渲染效果：H₂O

17.2 上标

X² 是 X 的平方

渲染效果：X²

17.3 HTML 方式

H₂O
X²

十八、定义列表（Definition List）

MultiMarkdown / PHP Markdown Extra 支持

术语 1

定义 1

术语 2

定义 2a

定义 2b

HTML 方式（更通用）：

术语 1

定义 1

术语 2

定义 2a

定义 2b

十九、缩写（Abbreviation）

MultiMarkdown / PHP Markdown Extra 支持

HTML 和 CSS 是前端开发的基础。

文档中所有出现的 HTML 和 CSS 会自动添加 <abbr> 标签，鼠标悬停时显示全称。

二十、数学公式（Math / LaTeX）

支持：Typora、Obsidian、Marxico、GitLab、Notion、Jupyter 等

20.1 行内公式

这是一个行内公式：\(E = mc^2\)

20.2 块级公式

20.3 常用数学公式示例

分数

根号

求和

积分

矩阵

方程组

多行公式对齐

条件函数

希腊字母

集合运算

箭头

\[\leftarrow, \rightarrow, \leftrightarrow, \Leftarrow, \Rightarrow, \Leftrightarrow, \mapsto\]

二十一、流程图与图表（Mermaid）

支持：GitHub、GitLab、Obsidian、Typora、Notion、Docusaurus 等

21.1 基本用法

21.2 流程图（Flowchart）

节点形状

箭头类型

方向

21.3 时序图（Sequence Diagram）

消息类型

21.4 甘特图（Gantt Chart）

21.5 类图（Class Diagram）

21.6 状态图（State Diagram）

21.7 饼图（Pie Chart）

21.8 ER 图（Entity Relationship）

21.9 用户旅程图（User Journey）

21.10 Git 图（Git Graph）

21.11 思维导图（Mindmap）

二十二、HTML 内嵌

Markdown 天然支持 HTML 标签，可以在 Markdown 文档中直接使用 HTML。

22.1 文本样式

加粗
加粗（语义化）
斜体
斜体（语义化）
下划线
删除线
删除线（语义化）
高亮
_下标
^上标
插入的文本
键盘文本
小号文本

22.2 键盘按键样式

按 Ctrl + C 复制

22.3 缩写

HTML 是一种标记语言。

22.4 引用与出处

这是一段引用。

22.5 上下标

H₂O
X²

22.6 文本对齐

或：

居中文本

22.7 字体颜色与大小

红色文本
红色文本
红色文本
大号文本
黄色背景文本

22.8 折叠内容（Details / Summary）

22.9 表格（HTML 方式）

22.10 iframe 嵌入

22.11 视频嵌入

22.12 音频嵌入

22.13 有序/无序列表（HTML 方式）

1. 有序列表项 1
2. 有序列表项 2

• 无序列表项 1
• 无序列表项 2

5. 从 5 开始编号
6. 编号为 6

1. 项目 1
   • 子项目 1a
   • 子项目 1b

二十三、转义字符

23.1 使用反斜杠转义

以下字符前加 \ 可以转义，使其显示为原文字符：

\ 反斜杠
` 反引号

• 星号
  _ 下划线
  {} 花括号
  [] 方括号
  () 小括号

  井号

• 加号

• 减号（连字符）
  . 点号
  ! 感叹号
  | 管道符

示例：

*这不是斜体*
#这不是标题
[这不是链接]

23.2 HTML 实体

二十四、元数据 / YAML Front Matter

支持：Jekyll、Hugo、Hexo、Gatsby、Docusaurus、Obsidian 等

24.1 基本语法

在文件开头使用 --- 包围的 YAML 块：

title: 文章标题
date: 2024-01-01
author: 作者名
tags:

• 标签1
• 标签2
  categories:

• 分类1
  description: 文章描述
  draft: false

正文开始

这里是文章内容。

24.2 常用 Front Matter 字段

24.3 多作者示例

---
title: 协作文章
authors:
  - name: 张三
    url: https://example.com/zhangsan
  - name: 李四
    url: https://example.com/lisi
---

二十五、目录（Table of Contents）

25.1 自动目录（各平台）

25.2 手动目录

手动创建目录链接到各标题的锚点：

目录

• 一、概述
• 二、基础语法
  • 2.1 标题
  • 2.2 段落

二十六、嵌入视频与音频

26.1 YouTube 嵌入

26.2 Bilibili 嵌入

26.3 本地视频

26.4 本地音频

26.5 视频链接卡片（部分平台）

二十七、嵌入 iframe

27.1 基本用法

27.2 嵌入 Google 地图

27.3 嵌入 CodePen

二十八、注释 / HTML 注释

28.1 HTML 注释

28.2 用于占位或编辑说明

二十九、锚点与内部跳转

29.1 自动锚点

Markdown 标题会自动生成锚点：

这是标题

跳转到标题

锚点生成规则

注意：不同平台的锚点生成规则可能不同。

29.2 手动锚点（HTML）

跳转到自定义锚点

或：

自定义锚点标题

29.3 属性方式锚点（部分解析器）

标题

三十、Diff 语法

30.1 使用 diff 语言标识

+ 新增的行（绿色）
+ 另一个新增行
- 删除的行（红色）
- 另一个删除行
  未修改的行

30.2 在代码中标注

def greet(name):
-   print("Hello")        # 旧代码
+   print(f"Hello, {name}!")  # 新代码

三十一、Callout / Admonition（提示框）

31.1 Obsidian Callout

[!NOTE]
这是一个提示信息。

[!WARNING]
这是一个警告信息。

[!IMPORTANT]
这是一个重要信息。

[!TIP]
这是一个小贴士。

[!CAUTION]
这是一个注意/小心信息。

[!INFO]
这是一个信息说明。

[!QUOTE]
这是一段引用。

[!EXAMPLE]
这是一个示例。

[!ABSTRACT]
这是一个摘要。

[!SUCCESS]
这是一个成功信息。

[!QUESTION]
这是一个问题。

[!FAILURE]
这是一个失败信息。

[!DANGER]
这是一个危险警告。

[!BUG]
这是一个 Bug 说明。

31.2 可折叠的 Callout

[!NOTE]+ 点击展开
这是可折叠的内容，默认展开。

[!NOTE]- 点击展开
这是可折叠的内容，默认收起。

31.3 嵌套 Callout

[!NOTE]
外层提示

[!WARNING]
内层警告

31.4 自定义标题

[!NOTE] 自定义标题
带有自定义标题的提示框。

31.5 GitHub Admonition（Beta）

[!NOTE]
GitHub 也在逐步支持 Callout 语法。

[!WARNING]
警告信息。

[!TIP]
提示信息。

[!IMPORTANT]
重要信息。

[!CAUTION]
注意信息。

31.6 Docusaurus Admonition

三十二、属性语法（Attribute）

支持：Marxico、Obsidian、部分 Markdown 扩展

32.1 给元素添加 ID 和类

标题

{width=300 .custom-class}

链接{target=_blank}

32.2 给链接添加属性

链接{:target="_blank" rel="noopener"}

32.3 给图片添加属性

{: width="300" height="200" .border}

三十三、Obsidian 特殊语法

33.1 双向链接（Wikilink）

[[笔记名称]]
[[笔记名称|显示文本]]
[[笔记名称#标题]]
[[笔记名称#标题|显示文本]]
[[笔记名称#^块ID]]

33.2 标签（Tag）

标签名

多级/标签

标签-连字符

标签中不能包含空格。

33.3 嵌入（Embed）

![[笔记名称]]
![[图片名.png]]
![[图片名.png|300]]
![[笔记名称#标题]]

33.4 块引用

^块ID

33.5 查询（Dataview 插件）

TABLE file.ctime AS 创建时间
FROM "日记"
SORT file.ctime DESC
LIMIT 10

33.6 内联查询

$= dv.pages("#标签").length 篇笔记

三十四、Docusaurus / MDX 扩展

34.1 提示框（Admonition）

34.2 选项卡

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

34.3 代码块标题

function Hello() {
  return <div>Hello, World!</div>;
}

34.4 代码块交互

function MyComponent() {
  return <button onClick={() => alert('Hello!')}>Click Me</button>;
}

34.5 可导入的代码

import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock title="src/components/myComponent.jsx" showLineNumbers>
  {MyComponentSource}
</CodeBlock>

三十五、GitBook 扩展语法

35.1 提示框

{% hint style="info" %}
信息提示
{% endhint %}

{% hint style="warning" %}
警告提示
{% endhint %}

{% hint style="danger" %}
危险提示
{% endhint %}

{% hint style="success" %}
成功提示
{% endhint %}

35.2 可折叠内容

{% collapsible title="点击展开" %}
折叠的内容
{% endcollapsible %}

35.3 页面嵌入

{% content-ref url="./other-page.md" %}
other-page.md
{% endcontent-ref %}

35.4 API 定义

{% swagger method="get" path="/api/users" baseUrl="https://api.example.com" summary="获取用户列表" %}
{% swagger-parameter type="query" name="page" %}
页码
{% endswagger-parameter %}

{% swagger-response status="200" description="成功响应" %}

{
  "users": []
}
{% endswagger-response %}
{% endswagger %}

三十六、Markdown 编辑器快捷键速查

36.1 通用快捷键

36.2 VS Code（Markdown All in One 插件）

36.3 Typora 快捷键

三十七、各平台兼容性速查表

✅ 原生支持 | ⚠️ 需插件/扩展 | ❌ 不支持

三十八、完整示例

以下是一个综合运用各种 Markdown 语法的完整示例：

title: Markdown 完整示例
date: 2024-01-01
author: 作者
tags: [Markdown, 教程]
description: 一个展示所有 Markdown 语法的完整示例

Markdown 完整示例

[!NOTE] 关于本文
本文档展示了 Markdown 的各种语法特性。

目录

• 1. 文本样式
• 2. 列表
• 3. 代码
• 4. 表格
• 5. 数学公式

1. 文本样式

这是一段普通文本，包含 加粗、斜体、加粗斜体、删除线 和 行内代码。

还可以组合使用 高亮文本（部分编辑器支持）。

化学式 H~2~O 和数学公式 X²（部分编辑器支持）。

1.1 链接

行内链接
引用链接

1.2 图片

2. 列表

2.1 无序列表

• 项目 A
  • 子项目 A.1
  • 子项目 A.2
• 项目 B
• 项目 C

2.2 有序列表

1. 第一步
2. 第二步
   1. 子步骤 2.1
   2. 子步骤 2.2
3. 第三步

2.3 任务列表

• 已完成
• 未完成
• 另一个未完成

3. 代码

行内代码：const x = 10;

代码块：

// JavaScript 示例
function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

console.log(fibonacci(10)); // 55

Diff：

- const old = "旧代码";
+ const new = "新代码";

4. 表格

5. 数学公式

行内公式：\(E = mc^2\)

块级公式：

\[\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}\]

6. 引用

这是一段引用。

嵌套引用。

引用中可以包含 加粗 和 代码。

7. Mermaid 图表

8. 脚注

这是一段带有脚注的文本¹，还有另一个脚注⁴。

9. HTML 扩展

10. 注释

最后更新：2024-01-01

回到顶部

附录 A：Markdown 特殊字符速查

A.1 必须转义的字符

A.2 特殊排版符号

附录 B：Emoji 速查表（常用）

B.1 表情与手势

B.2 物品与符号

B.3 自然与天气

附录 C：LaTeX 数学符号速查

C.1 希腊字母

C.2 运算符

C.3 关系符

C.4 箭头

C.5 求和/积分/极限

C.6 函数

C.7 其他符号

C.8 格式化

附录 D：Mermaid 图表类型速查

D.1 支持的图表类型

D.2 甘特图状态关键字

D.3 流程图方向关键字

D.4 时序图激活/停用

简写方式：

D.5 时序图循环/条件/并行

变更日志

提示：本文档力求最全面，但 Markdown 语法在不同平台和编辑器中可能存在差异。如需特定平台的支持细节，请查阅对应平台的官方文档。

EnhancedMarkdown：为 Typecho 打造的增强版 Markdown 解析器

用一篇文章，解锁 Typecho 博客的 Markdown 全部潜力。

这篇文章本身就是用 EnhancedMarkdown 的全部语法写成的——你看到的每一种排版效果，都是插件的实时渲染。

为什么需要这个插件？

Typecho 默认使用 HyperDown 作为 Markdown 解析器，在日常写作中够用，但当你需要更丰富的排版能力时，它的局限性就显现出来了：

• 不支持脚注、定义列表、缩写词等 Markdown Extra 语法 → 现在支持了
• GFM 表格对齐等能力缺失 → 完整 GFM 支持
• 正则后处理导致占位符冲突和渲染异常 → 彻底消除

插件概览

演进历程

插件的开发经历了几次关键迭代，每一次都在解决真实的使用问题：

v2.0 — 起步阶段（基于 HyperDown 扩展）

最初的实现方式是在 HyperDown 解析结果上做正则后处理——用 str_replace 替换占位符来扩展语法。这种方式简单直接，但随着扩展语法增多，占位符冲突导致的显示故障越来越频繁。

v3.0 — 重大重构（切换 Parsedown 引擎）

这是最关键的一次变更。将整个解析引擎从 HyperDown 切换为 Parsedown + ParsedownExtra，扩展方式也从正则后处理改为 Parsedown 原生的 InlineTypes / BlockTypes 注册机制：

• 彻底消除占位符冲突：不再有字符串替换带来的副作用
• 原生语法扩展：通过注册自定义解析器实现新语法，与标准语法和平共处
• 获得 Markdown Extra 支持：脚注、定义列表、缩写词开箱即用

v3.2 — 细节完善

修正了代码语言标识的兼容性问题——将 language-php 风格的 class 名转换为 Typecho 约定的 lang-php 前缀，确保 Prism.js、Highlight.js 等语法高亮插件正常工作。

v3.3 — 公式与图表

新增两大重量级功能：

• 数学公式（KaTeX 渲染）：支持 \(...\) 行内公式和 $\(...\)$ 块级公式
• Mermaid 图表：支持流程图、时序图、甘特图等，用 ```mermaid 代码块书写

v3.4 — 性能优化 + 修复

v3.4.2 — 容器语法关键修复

修复了两个影响 :::type 容器语法的 Bug：

• Bug #1：容器内容为空 — blockContainer() 初始化时设置了空 text 属性，Parsedown 渲染时 isset(\(Element['text'])` 优先于 `rawHtml`，导致容器内容永远不显示。修复：`unset(\)Block['element']['text'])
• Bug #2：容器被定义列表拦截 — ParsedownExtra 的 DefinitionList 注册在 : 字符上，当 :::info 前紧挨段落时会错误拦截。修复：使用 array_unshift 将 Container 注册为 : 字符的最高优先级处理器

v3.5.0 — 解析增强

本次更新带来了 3 项解析增强：

• HTML 块内 Markdown 解析：新增 blockMarkupComplete() 方法，对白名单标签（<center>、<details>、<div> 等）自动解析内部 Markdown。使用白名单机制确保 <script>/<style>/<pre> 等标签不受影响
• 代码块标题支持：新增 blockFencedCode() 方法提取 title="..." 参数，支持 ```javascript title="示例" 语法显示代码块标题栏
• 容器方括号语法：扩展 blockContainer() 正则，支持 :::note[自定义标题] Docusaurus Admonition 风格语法，向后兼容 :::note 标题 空格语法

v3.5.1 — 纯 HTML 内容误编码修正

v3.5.0 的 blockMarkupComplete() 引入了一个回归问题：当 <div> 等白名单标签内部为纯 HTML（不含 Markdown 语法）时，text() 的递归解析会将 HTML 标签转义为实体编码并错误包裹在 <pre><code> 中。

修复方案：新增 containsMarkdownSyntax() 启发式检测方法——使用 strip_tags() 去除 HTML 标签后，通过正则检测纯文本中是否包含 Markdown 语法标记（**、`、[、$ 等）。纯 HTML 内容跳过 text() 调用，直接保留原始输出。

v3.5.2 — 主题兼容性修复

本次更新聚焦于与主题的兼容性，修复了两个问题：

• 标题 ID 改用 Slug 格式：旧版使用 toc-0、toc-1 等数字 ID，依赖解析顺序且不可预测，主题 JS 无法构建有效锚点链接。v3.5.2 新增 generateSlug() 方法，将标题文本转为可读的 slug 格式 ID（如 hello-world、为什么需要这个插件），重复标题自动追加 -2、-3 后缀。同时新增配置项，可选择 Slug 格式或保留旧版数字格式
• 脚注样式补全：ParsedownExtra 生成 .footnotes、.footnote-ref、.footnote-backref 等元素但无样式，脚注内容显示混乱。新增完整的脚注 CSS：分割线、字号缩小、有序列表间距、上标定位、回链样式，确保在任何主题下都有良好的视觉呈现

v3.5.3 — PHP 8.2+ 兼容性修复

修复了一个属性大小写错误导致的 PHP 8.2+ 兼容性问题：

• BreaksEnabled 大小写不一致：Parser 构造函数中使用 \(this->BreaksEnabled = true`（大写 B），而父类 Parsedown 声明的属性为 `\)breaksEnabled（小写 b）。PHP 属性名大小写敏感，导致在 PHP 8.2+ 上触发 Deprecated: Creation of dynamic property 弃用警告，且 GFM 自动换行功能实际未生效（赋值到了错误的动态属性）
• 修复方式：改用 Parsedown 提供的公共 setter 方法 $this->setBreaksEnabled(true)，所有 PHP 版本均兼容

v3.6.0 — 代码语法高亮（Prism.js）

新增内置代码语法高亮功能，基于 Prism.js 前端渲染引擎：

• Prism.js 集成：自动为 ```language 围栏代码块添加语法着色，下载版已包含 200+ 编程语言支持
• 按需加载：沿用 KaTeX/Mermaid 的按需加载模式——仅当代码块存在时才加载 Prism.js CSS/JS 资源，无代码块的页面零开销
• 配置开关：插件设置新增「代码语法高亮（Prism.js）」选项，默认启用

v3.7.0 — 代码块暗色主题重构

对代码块的视觉呈现进行了全面重构，从浅色主题切换为暗色主题，并统一了所有代码块的 HTML 结构：

• 暗色主题：代码块背景从 #f6f8fa 浅灰切换为 #1e1e1e 深色，文字颜色为 #d4d4d4，顶栏为 #2d2d2d，整体视觉更专业
• 统一包裹结构：所有非 Mermaid 代码块（无论有无标题）统一包裹为 <div class="code-block-wrapper"> 容器，内含顶栏（code-top-bar）和代码区（actual-code-content）
• 复制按钮：顶栏右侧新增「语言名 | 复制」按钮，点击复制代码内容到剪贴板，显示"已复制"反馈 2 秒后恢复
• Prism.js 适配：prism.css 全面适配暗色主题——移除 pre 的 border/box-shadow/margin（由 wrapper 控制），背景设为 transparent，隐藏 Prism.js Toolbar 插件

v3.8.0 — CDN 资源来源选择

增强了 KaTeX 和 Mermaid 的资源加载灵活性，支持在本地文件和 CDN 之间自由切换：

• 资源来源选择：插件设置新增「KaTeX 资源来源」和「Mermaid 资源来源」配置项，可选「插件本地文件」或「CDN 网址」
• CDN 基础路径：选择 CDN 模式后，可自定义 CDN 目录路径（如 https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/），插件自动拼接具体文件名
• 安全回退：CDN 基础路径为空时自动回退到本地文件，避免生成无效 URL
• 新增 getResourceUrl() 方法：统一处理本地/CDN 路径逻辑，减少代码重复

v3.8.1 — Prism .token.tag 主题样式污染修复

修复了博客主题的 .tag CSS 类污染 Prism.js 代码高亮的问题：

• 问题：博客主题为标签云定义了 .tag 类样式（padding/background-color/border-radius），Prism.js 在 PHP/markup 类语言中为 HTML 标签 token 生成 <span class="token tag">，CSS 选择器 .tag 命中了 token 元素，导致代码块内出现白色背景块
• 修复：在 prism.css 中新增 .token.tag 覆盖规则，使用 !important 重置布局属性（background/border/padding/margin/box-shadow/border-radius/display/font-size/line-height），保留 Prism 主题定义的 token 颜色

v3.8.2 — 代码语法高亮全部语言修复

修复了代码语法高亮仅少数语言生效的问题：

• 问题：prism.js 中同时打包了全部语言语法定义（300+种）和 Autoloader 插件。Autoloader 的设计目的是从外部服务器动态加载语言文件，但本地不存在外部语言文件。Autoloader 会拦截高亮流程，对部分语言尝试 AJAX 加载外部文件 → 加载失败 → 高亮失败。仅少数核心语言（如 markup、css、javascript）因注册优先级高能绕过 Autoloader 正常工作
• 修复：从 prism.js 中移除 Autoloader 插件，保留全部 300+ 种语言语法定义。所有语言高亮由内联语法定义直接处理，无需外部文件加载
• 影响范围：仅替换 prism/prism.js，不修改其他文件，向后完全兼容

v3.9.1 — 图片尺寸语法修复

修复了图片尺寸语法 ![alt](url =WxH) 在 URL 与 =WxH 之间存在空格时无法解析的问题：

• 问题：![alt](url =300x200) 因空格导致父类 Parsedown 的 URL 正则匹配失败，整张图片不被渲染。仅 ![alt](url=300x200) 无空格格式可正常工作
• 修复：重写 inlineImage() 方法为预处理模式——在调用父类解析前先从文本中剥离 =WxH 参数，使父类能正常匹配标准 Markdown 图片语法，再在返回结果中注入 width/height 属性
• 影响范围：仅修改 Parser::inlineImage() 方法，不影响无尺寸参数的普通图片

v3.9.0 — Mermaid 图表框内缩放交互

为 Mermaid 图表新增了框内缩放、平移、还原交互功能：

• 鼠标滚轮缩放：在图表框内滚动鼠标滚轮即可自由缩放（范围 0.05x~20x），缩放中心跟随鼠标光标位置，想看哪里就滚到哪里
• 鼠标拖拽平移：按住鼠标左键拖拽即可平移图表内容，1:1 跟随鼠标移动，手感自然流畅
• 移动端支持：单指拖拽平移 + 双指捏合缩放，移动端也能自由查看大型图表细节
• 还原按钮：右上角常驻显示循环箭头图标按钮，点击后平滑过渡回初始视角——防止缩放/平移后"找不到图"
• 零视觉影响：不改变图表的渲染大小和外观，仅在框内提供交互能力，wrapper 完全透明无边框

功能全览

标准 Markdown 增强

完整的 GFM（GitHub Flavored Markdown）支持：

删除线

这段文字已经被删除了，但你仍然可以看到它。

GFM 表格

支持左对齐、居中、右对齐：

任务列表

• 安装 Typecho
• 启用 EnhancedMarkdown 插件
• 写一篇使用增强语法的文章
• 分享给朋友

Markdown Extra 语法

这些是标准 Markdown 不支持、但对技术写作非常有用的语法。

脚注⁵

这是一段包含脚注引用的文字⁶，脚注会自动显示在文章末尾，点击可以跳转。

定义列表

Typecho

一个轻量级的博客引擎，以简洁高效著称

Markdown

一种轻量级标记语言，让你用纯文本格式编写文档

EnhancedMarkdown

Typecho 的增强版 Markdown 解析器插件

缩写词

在技术文章中，HTML、CSS 和 API 这些缩写词很常见。鼠标悬停即可看到完整含义。

自定义扩展语法

以下是插件独创的语法扩展，标准 Markdown 不支持。

TOC 自动目录

你已经在文章开头看到了——本篇文章顶部的目录就是用 [toc] 标记自动生成的。它会自动扫描所有标题，生成带锚点链接的嵌套目录树。

容器/提示块

用 :::type 语法创建彩色提示框。下面展示所有 8 种类型：

上标 / 下标 / 高亮

物理学中最著名的方程：E = mc²，其中 c 代表光速。

水的化学式是 H~2~O，硫酸是 H~2~SO~4~。

在学习过程中，标记重点内容 是提高效率的好方法。

等等，你注意到了吗？上面这行文字中，² 被渲染成了上标，~2~ 被渲染成了下标，标记重点内容 被高亮显示了。

图片尺寸

![图片描述](image.png =300x200)   → 宽 300px，高 200px
![图片描述](image.png =300x)      → 宽 300px，高度自适应
![图片描述](image.png =x200)      → 高度 200px，宽度自适应

数学公式（KaTeX）

支持 LaTeX 语法，使用 KaTeX 前端渲染，速度远优于 MathJax。

行内公式

质能方程 \(E = mc^2\) 是物理学最著名的公式之一。勾股定理 \(a^2 + b^2 = c^2\) 是几何学的基础。欧拉公式 \(e^{i\pi} + 1 = 0\) 被誉为数学中最美的等式。

块级公式

Mermaid 图表

用文本描述图表，前端自动渲染。文章中的图表不再是截图，而是可维护的文本代码。

交互提示：以下图表均可使用鼠标滚轮缩放、拖拽平移查看细节，右上角 🔄 按钮可一键还原。

流程图

时序图

甘特图

性能优化

插件在设计上追求零代价——不用的时候不产生任何开销。

按需加载机制

不是简单地判断"功能是否开启"，而是扫描页面实际内容：

1. 解析 Markdown 时检测输出 HTML 中是否包含 .math-block / .math-inline / .mermaid 元素
2. 设置静态标志 \(hasMath` / `\)hasMermaid
3. CSS 注入（<head>）和 JS 注入（</body> 前）根据标志决定是否加载

Hook 注册

插件通过 4 个 Hook 点接入 Typecho：

// ① 替换文章 Markdown 解析器
\Typecho\Plugin::factory('Widget\Base\Contents')->markdown = [__CLASS__, 'parse'];

// ② 替换评论 Markdown 解析器
\Typecho\Plugin::factory('Widget\Base\Comments')->markdown = [__CLASS__, 'parse'];

// ③ 注入 CSS 到 <head>
\Typecho\Plugin::factory('Widget\Archive')->header = [__CLASS__, 'injectStyles'];

// ④ 注入 JS 到 </body> 前
\Typecho\Plugin::factory('Widget\Archive')->footer = [__CLASS__, 'injectScripts'];

自定义语法扩展

基于 Parsedown 的扩展机制，注册自定义的行内元素和块级元素：

// 注册容器块语法（:::type 触发）
$this->BlockTypes[':'][] = 'Container';

// 注册上标语法（^ 触发）
$this->InlineTypes['^'] = ['Superscript'];

// 注册高亮语法（= 触发）
$this->InlineTypes['='] = ['Highlight'];

// 扩展扫描字符列表（Parsedown 只扫描此列表中的字符）
$this->inlineMarkerList .= '^=';

数学公式保护机制

数学公式中的 _、*、\ 等字符会被 Parsedown 误解析。解决方案是预处理-后处理两阶段：

1. 预处理：在 Parsedown 解析前，用 \x00 占位符替换公式内容
2. Parsedown 解析：占位符不包含特殊字符，不会被误解析
3. 后处理：将占位符替换为带有 KaTeX 定界符的 HTML 标签

// 块级公式占位符 → HTML（使用 \[...\] 定界符）
\(replacement = '<div class="math-block">\[' . \)escapedFormula . '\]</div>';

// 行内公式占位符 → HTML（使用 \(...\) 定界符）
\(replacement = '<span class="math-inline">\(' . \)escapedFormula . '\)</span>';

容器嵌套的脚注保护

// ① 保存当前定义数据（脚注、引用、缩写）
\(savedDefinitionData = \)this->DefinitionData;

// ② 递归解析容器内容（会触发 DefinitionData 重置）
\(contentHtml = \)this->text($Block['content']);

// ③ 合并子解析产生的定义回主数据
\(this->DefinitionData = \)savedDefinitionData;

安装与配置

安装步骤

• 步骤一：将 EnhancedMarkdown 文件夹上传至 usr/plugins/ 目录
• 步骤二：登录 Typecho 后台 → 插件管理 → 启用 EnhancedMarkdown
• 步骤三：在插件设置中按需开关各项功能

配置项一览

所有 15 项配置均可独立设置，语法功能默认全部启用：

文件结构

EnhancedMarkdown/
├── Plugin.php          # 插件主入口（Hook 注册、配置面板、CSS/JS 注入）
├── Parser.php          # 增强解析器（基于 Parsedown 扩展）
├── Parsedown.php       # Parsedown 核心引擎
├── ParsedownExtra.php  # Parsedown Extra 扩展
├── katex/              # KaTeX 数学公式渲染库
│   ├── katex.min.js
│   ├── katex.min.css
│   ├── auto-render.min.js
│   └── fonts/          # WOFF2 字体（仅 300KB）
├── mermaid.min.js      # Mermaid 图表渲染库
├── prism/              # Prism.js 代码语法高亮库
│   ├── prism.js        # 核心 + 全部语言支持
│   └── prism.css       # 主题样式
└── README.md

总结

通过完全替换解析引擎而非打补丁的方式，从根本上保证了语法的正确性和扩展的可靠性。回到这篇文章本身——你所看到的目录、提示框、高亮、上下标、数学公式、流程图、甘特图、脚注、任务列表、定义列表……全部来自插件的实际渲染。

如果你在 Typecho 博客中需要用到这些丰富排版能力，不妨试试这个插件。