把 HTML 表格转成 Markdown 表格:从网页复制到写进 README 的完整做法

写文档的人迟早会碰到这件事:看到一张排得很整齐的网页表格,想原样搬进自己的 README 或 wiki,可那是 HTML,目标是 Markdown。手动一行行抄,列一多就容易抄错,链接和加粗标签还会黏在文字里。这篇说清楚转换的几个关键点,以及哪些地方最容易出问题。

HTML 表格和 Markdown 表格差在哪

HTML 表格是一棵结构树:<table> 里有 <tr>,<tr> 里有 <th> 或 <td>,单元格里还能再塞 <a>、<b>、<div> 甚至另一张表。Markdown 表格则是几行纯文本,靠竖线分列,第二行那条 | --- | --- | 用来声明表头和对齐方式。

差距就在这里:Markdown 单元格只认内联文本,装不下块级结构。所以转换不是简单替换符号,而是要把每个单元格压平成一段可读文字,再按列拼成文本行。

th 怎么变表头,分隔行怎么来

Markdown 表格必须有一行表头,后面紧跟一条分隔行,这是格式硬要求。转换时的判断顺序是:有 <thead> 或 <th> 就用它当表头;两样都没有,就把第一个 <tr> 顶上去当表头。

表头定下来,分隔行 | --- | --- | 按列数自动补齐,你不用自己数有几列。如果原表带了对齐信息,比如 <th align="right">,打开「读取对齐」后会映射成 ---:(右对齐)、:---:(居中)或 :---(左对齐),数字列就能保持右对齐。没带对齐信号的列保持普通的 ---。

单元格清理:去标签、还原实体、转义竖线

这一步是质量分水岭。三件事必须做对:

嵌套标签去掉只留文本。<td><b>4K</b> 显示器</td> 应该得到 4K 显示器,<a href="/x">链接</a> 应该得到 链接。script 和 style 整块删掉,不会执行任何东西。
HTML 实体还原。&、'、  这些要变回真正的字符,否则文档里满屏都是转义码。
竖线转义。单元格里的裸竖线 | 会提前结束 Markdown 列,把后面所有列错位。所以 数据线 A | B 要输出成 数据线 A \| B,渲染出来还是字面的 数据线 A | B,列数也对得上。

单元格内部的换行默认压成一个空格;如果某格确实要两行,可以保留成字面的 <br>,大多数 Markdown 引擎都认。

一个真实例子

输入这段 HTML:

<table>
  <tr><th>套餐</th><th align="right">月费</th></tr>
  <tr><td><b>基础版</b></td><td>9 元</td></tr>
  <tr><td>团队版 A | B</td><td>&amp;99 元</td></tr>
</table>

打开「读取对齐」后,输出是:

| 套餐 | 月费 |
| --- | ---: |
| 基础版 | 9 元 |
| 团队版 A \| B | &99 元 |

注意三个细节:<b> 去掉了只留「基础版」,align="right" 让月费列的分隔行变成 ---:,单元格里的竖线转义成了 \|,& 还原成了 &。这正是手动抄最容易漏的几处。

文档迁移时我的几个习惯

我自己从 CMS 往工程文档搬规格表时,养成了几个习惯。先只粘我真正要的那个 <table>...</table> 块,而不是整页源码,因为默认取的是源码里的第一张表,不一定是屏幕上最先看到的那张。再就是数字列一定打开对齐,否则 Markdown 默认全部左对齐,数字看着别扭。最后从导出的报表里转表格时,我会留意外层那堆 <div> 和 <span> 包裹,它们会被剥掉只留值,行列不齐的地方也会补齐,贴进 Confluence 或 GitHub wiki 基本不用再改。

顺手的相邻工具

如果你手上的源数据不是 HTML 而是别的格式,流程其实差不多。表格转换可以直接用 HTML 表格转 Markdown;要是数据已经是 CSV,想拼成 Markdown 表格,用 CSV 转 Markdown 表格更顺手,省去先转 HTML 这一步。

整个过程都在浏览器本地完成,粘进去的 HTML 用纯字符串匹配解析,不走 DOM,源码里藏的脚本或追踪像素都跑不起来,表格内容也不上传。写文档本来就够琐碎了,转换这一环至少可以不费心。

Made by Toolora · Updated 2026-06-13