跳到主要内容

Markdown 转 HTML 完整指南:标题列表代码块怎么映射

写作用 Markdown,发布要 HTML。这篇讲清标题列表代码块链接的对应关系,CommonMark 规范怎么定的,以及公众号博客邮件三种场景下本地转换的实操方法。

发布于 作者 李雷
#Markdown #HTML #转换 #CommonMark #前端

Markdown 转 HTML 完整指南:从语法映射到落地场景

写东西的时候我从不直接敲 HTML。标题敲一个 #,列表敲一个 -,加粗用两个星号包住,手不离开主键区,思路也不被标签打断。可真要发出去的时候,无论是博客系统、公众号后台还是邮件正文,吃的都是 HTML。中间这道转换,就是 Markdown 转 HTML 要解决的事。

这篇把转换里几件容易踩坑的事讲透:每种语法到底映射成什么标签、CommonMark 规范是怎么约定的、三类常见发布场景怎么处理,以及为什么本地转换比在线服务更省心。

标题、列表、链接分别映射成什么

Markdown 的设计就是一套对应关系,记住映射规则,转出来的结构就在意料之中。

  • 标题:一到六个 # 对应 <h1> 到 <h6>,# 后面要留一个空格,不然不生效。
  • 无序列表:行首的 -、*、+ 都转成 <ul><li>,三种符号等价。
  • 有序列表:1. 2. 这种数字加点转成 <ol><li>,序号具体写几其实不重要,转换器按出现顺序重排。
  • 链接:[文字](网址) 转成 <a href="网址">文字</a>。
  • 图片:![描述](图片地址) 转成 <img src="图片地址" alt="描述">,前面多一个叹号是和链接唯一的区别。
  • 加粗斜体:**粗** 是 <strong>,*斜* 是 <em>。

代码块单独说。行内代码用一对反引号包,转成 <code>。多行代码用三个反引号围起来,转成 <pre><code>,而且围栏后面写的语言名会落到 class 上: `ts 转出来是 <pre><code class="language-ts">。注意这只是给标签贴了个语言标记,真正的语法着色得靠 hljs、Prism 或 Shiki 这类库,目标页面没加载对应主题样式,代码就是普通等宽字体。

CommonMark 规范定了哪些边界

Markdown 早年有个麻烦:同一段文本,不同解析器转出来的结果不一样。CommonMark 规范就是来收口的,它把模糊地带逐条钉死,还附带一个上千例的官方测试套件,任何声称兼容的实现都得跑过去。

举个规范明确规定的点:CommonMark 要求把输入里的裸 HTML 原样透传,包括 <script> 和 <iframe>。这是规范的第六节 "Raw HTML" 写明的行为。对转换器来说这是正确选择,转换不该擅自删用户的内容。但它有个安全含义:如果你粘的是陌生人给的 Markdown,转完直接上生产,对方塞进去的 <script> 也会一起上线。所以在有用户会话的页面渲染前,记得先用 DOMPurify 这类工具清一遍。

一段真实的输入输出

光说映射不直观,看一段实际的。输入这样一段 Markdown:

# 安装步骤

先装依赖,再跑构建:

1. `npm install`
2. `npm run build`

文档见 [官方仓库](https://example.com)。

转出来的 HTML 是:

<h1>安装步骤</h1>
<p>先装依赖,再跑构建:</p>
<ol>
<li><code>npm install</code></li>
<li><code>npm run build</code></li>
</ol>
<p>文档见 <a href="https://example.com">官方仓库</a>。</p>

可以看到:标题进了 <h1>,两段普通文字各自包进 <p>,有序列表成了 <ol> 带两个 <li>,行内的命令进了 <code>,链接也规规矩矩。结构干净,没有多余的行内样式,贴到任何带样式表的页面里都能接得上。

公众号、博客、邮件三种场景

转换的用途集中在发布前的最后一步,场景不同处理也不同。

公众号和 Notion、飞书这类富文本编辑器,它们认的是剪贴板里的富文本,不是 HTML 源码。做法是把 Markdown 转好后看预览,全选复制渲染区域,剪贴板带的就是富文本,粘进去加粗列表链接都在。

博客和静态站最直接。GitHub README 写好的内容想挂到落地页,转成 HTML 塞进一个带 .prose 样式的容器就行,代码块的 language-xx class 还在,接 Prism 能正常上色。要把旧的 Hexo 或 Jekyll 站归档成纯静态文件,也是每篇 .md 过一遍转换,套个极简骨架托管成平铺 HTML,不用再守工具链。

邮件最麻烦。多数邮件客户端,包括 Outlook,会剥掉 <style> 块,只认 style="" 行内属性。所以 Markdown 转 HTML 之后还得过一道 inline-CSS 工序,把样式写进每个标签的行内属性里,加粗和链接才能稳稳送达收件箱。

为什么选本地转换

我自己长期用本地转换,理由很简单:Markdown 里常常有还没发布的草稿、内部文档、客户资料。一个纯浏览器本地的工具,文本不离开你的机器,不打埋点,转换由内置解析器在浏览器里完成。这点在处理敏感内容时尤其重要。响应也快,敲完就出结果,不用等网络往返。

工具直接用这个:Markdown 转 HTML,左边写右边实时预览。反方向也有需求的话,从网页或文档抓回 Markdown 用 HTML 转 Markdown;要单独生成表格那段语法,Markdown 表格生成器 比手敲竖线省事得多。三个搭着用,写作到发布这条链路就顺了。

Made by Toolora · Updated 2026-06-13