为什么要 Markdown 转 HTML
Markdown 是写作者友好的轻量标记语言，但浏览器只认 HTML。Markdown 写的内容要展示到网页，必须转成 HTML。
常见场景：
- 博客文章发布
- 文档站点渲染
- README 展示
- 富文本编辑器输出 HTML
Markdown 与 HTML 语法对应
标题
Markdown：
# 一级标题
## 二级标题
### 三级标题
HTML：
<h1>一级标题</h1>
<h2>二级标题</h2>
<h3>三级标题</h3>
段落
Markdown：空行分隔的文本段。
HTML：<p>段落</p>
强调
Markdown：
**粗体**
*斜体*
~~删除线~~
HTML：
<strong>粗体</strong>
<em>斜体</em>
<del>删除线</del>
链接
Markdown：
[链接文字](https://example.com)
HTML：
<a href="https://example.com">链接文字</a>
图片
Markdown：
HTML：
<img src="image.png" alt="替代文字">
列表
Markdown 无序列表：
- 项目1
- 项目2
HTML：
<ul>
<li>项目1</li>
<li>项目2</li>
</ul>
Markdown 有序列表：
1. 第一项
2. 第二项
HTML：
<ol>
<li>第一项</li>
<li>第二项</li>
</ol>
代码
Markdown 行内代码：
这是 `code` 行内代码
HTML：这是 <code>code</code> 行内代码
Markdown 代码块：
代码块
HTML：
<pre><code>代码块</code></pre>
带语言高亮：
const x = 1;
转换后含语法高亮标记（需高亮库支持）。
引用
Markdown：
> 这是引用
HTML：
<blockquote>这是引用</blockquote>
分割线
Markdown：
---
HTML：
<hr>
表格
Markdown：
| 姓名 | 年龄 |
| ---- | ---- |
| Tom | 25 |
HTML：
<table>
<thead>
<tr><th>姓名</th><th>年龄</th></tr>
</thead>
<tbody>
<tr><td>Tom</td><td>25</td></tr>
</tbody>
</table>
扩展语法
标准 Markdown（CommonMark）不含以下功能，但多数解析器支持：
任务列表
- [x] 已完成
- [ ] 未完成
HTML：
<ul>
<li><input type="checkbox" checked disabled> 已完成</li>
<li><input type="checkbox" disabled> 未完成</li>
</ul>
脚注
正文[^1]
[^1]: 脚注内容
删除线
~~删除~~
自动链接
定义列表、目录、公式等
部分解析器支持，兼容性不一。
转换注意事项
样式丢失
Markdown 转 HTML 只生成标签，不含样式。展示效果依赖 CSS：
- 标题大小、间距
- 列表缩进、符号
- 代码块背景、字体
- 表格边框
转完后要配 CSS 才好看。
XSS 安全
Markdown 允许嵌入 HTML。用户输入的 Markdown 转 HTML 时，嵌入的 <script> 等标签会保留，导致 XSS。
安全做法：
- 用纯 Markdown（禁用内嵌 HTML）
- 转 HTML 后用 sanitize 库过滤危险标签
- 只允许可信来源的 Markdown
转义字符
Markdown 里的特殊字符（、#、_、）要转义。Markdown 里写 \* 显示星号，转 HTML 后是 ` 不是标签。
图片路径
Markdown 里相对路径图片，转 HTML 后路径不变。换目录展示要调整路径。
锚点链接
Markdown 标题自动生成锚点（id）。不同解析器生成规则不同，链接锚点时注意。
转换工具
在线转换
粘贴 Markdown，工具输出 HTML。适合一次性转换。
- 粘贴 Markdown 内容
- 工具解析转换
- 输出 HTML 代码
- 复制使用
浏览器端转换，内容不上传。
编辑器集成
VS Code、Typora 等编辑器内置 Markdown 转 HTML 预览。
程序转换
JavaScript 用 marked、markdown-it 库。Python 用 markdown、mistune 库。
转换技巧
统一 Markdown 风格
不同 Markdown 方言（CommonMark、GFM、MDX）转换结果可能不同。团队统一用一种方言。
预览校验
转换后在浏览器预览，检查：
- 标题层级是否正确
- 列表嵌套是否正常
- 代码块是否高亮
- 表格是否对齐
- 图片是否显示
- 链接是否可点
配套 CSS
准备一套 Markdown 渲染 CSS，转出的 HTML 套用即可展示美观。
保留原始 Markdown
HTML 是渲染结果，Markdown 是源文件。保留 Markdown 方便后续编辑，HTML 每次重新生成。
常见问题
转换后样式不对
HTML 没配 CSS。加一套 Markdown 渲染样式表。
代码块不高亮
需要语法高亮库（如 highlight.js、Prism）。转换工具是否集成高亮看配置。
表格错位
Markdown 表格语法不严格（列数不匹配）。转换前检查表格格式。
特殊字符显示异常
Markdown 里的 < > & 等字符在 HTML 里有特殊含义。要转义成 < > &。
小结
Markdown 转 HTML 核心是语法对应映射。注意样式配套、XSS 安全、特殊字符转义。DocsAll Markdown 转 HTML 工具 浏览器端运行，内容不外传。