Excel 转 Markdown 表格,粘贴转换和检查

Markdown 写作约 7 分钟

在 Excel、Numbers 或 Google Sheets 里复制单元格,剪贴板里是用制表符隔开的纯文本,一行对应一行数据,所以直接粘进 Markdown 文件得到的是一串制表符,不是表格。要得到竖线表格就得转换一次,临时用一下,在线生成器 tablesgenerator.com 最快,经常要转文件用 Pandoc(pandoc -f csv -t gfm)更顺手,刚复制的一小块数据用一段 awk 就够了。转完之后检查三件事,合并单元格、单元格里的换行,以及数据里有没有 |。

为什么粘贴出来不是表格

电子表格是一张网格,纯文本剪贴板里没有网格,复制一个区域只会得到单元格之间一个制表符、行与行之间一个换行的文本,和 .tsv 文件的格式一样。Markdown 表格需要单元格之间有竖线,表头下面还要有一行连字符的分隔行,所以制表符只会作为看不见的空白留在文件里,预览里数字就挤成一段话。

有些应用在纯文本之外还会往剪贴板里放一份 HTML 版本,部分编辑器会去读它,妙言就是其中之一,后面会讲。最直接的判断办法是粘一次看看,出现竖线说明 HTML 那条路走通了,出现制表符就需要转换工具。

方法一,在线生成器

tablesgenerator.com 的 Markdown 表格页面写明,可以从 Excel、Google Sheets 或 LibreOffice Calc 复制单元格,点中它网格左上角的单元格按 Ctrl+V,网格会自动长到合适大小。它也能通过 File / Import CSV or Excel file 导入文件,支持 .csv 和 .xlsx,Excel 工作簿可以选工作表。Markdown 代码显示在编辑器下方,点 Copy to clipboard 复制。

同一页面上几项会改变结果的选项如下。

  • 对齐按列设置,在 Column 菜单的 Text align 子菜单里选,输出时每一列取第一行单元格的对齐方式,变成分隔行里的冒号。
  • 单元格里的换行默认变成空格,勾选 Line breaks as <br> 就改写成 <br>。
  • Markdown 不能合并单元格,页面导入 HTML 或 Markdown 时会把合并的单元格拆开,要保留合并就用它的 HTML 表格生成器。
  • Compact mode 会省掉用来对齐各列的空格。

表格内容比较敏感时,本地工具更稳妥。

方法二,Pandoc

Pandoc 的输入格式里有 csv 和 tsv,输出格式里有 gfm,下面的输出来自 Pandoc 3.13。

pandoc -f csv -t gfm data.csv
pandoc -f tsv -t gfm data.tsv

一份带表头、两行数据的 TSV 输出如下。

| Name  | Qty |
|-------|-----|
| Apple | 3   |
| Pear  | 12  |

表格从电子表格导出 CSV 时选 UTF-8,中文和带音标的字母才不会乱码。想转换剪贴板里的内容而不是文件,Mac 上可以用 pbpaste | pandoc -f tsv -t gfm | pbcopy,pbpaste 和 pbcopy 分别负责读写剪贴板。

转换时有三个现象要注意。

竖线会被转义。 内容是 a|b 的单元格输出成 a\|b,表格结构不会散。转义规则本身见 Markdown 转义字符。

单元格里有换行时,Pandoc 不再写竖线表格。 只要有一个单元格带换行,gfm 输出的就是完整的 HTML <table>,换行写成 <br />。这和 Pandoc 手册里说的竖线表格单元格不能包含块级元素、不能跨多行是吻合的。想要竖线表格,转换前先把单元格里的换行去掉。

中日韩文字按显示宽度补空格。 Pandoc 把一个汉字算作两列宽,所以内容是 中文 的单元格比内容是 ab 的少补两个空格,等宽字体下各列是对齐的,这只影响原始文件。

Pandoc 把第一行当表头,写出的分隔行没有对齐用的冒号,需要居中或右对齐的数字列,自己补上 :---: 或 ---:。

方法三,命令行小过滤器

数据不多而且已经是制表符分隔,比如刚复制的一块区域,下面这段 awk 就够,它会转义竖线、拼出每一行,并在第一行后面加上分隔行。

pbpaste | awk -F'\t' '{
  gsub(/\|/, "\\|")
  out = "|"
  for (i = 1; i <= NF; i++) out = out " " $i " |"
  print out
  if (NR == 1) { s = "|"; for (i = 1; i <= NF; i++) s = s " --- |"; print s }
}' | pbcopy

在一个两行的样例上,带 A|x 的数据行输出 | A\|x | 3 |,分隔行输出 | --- | --- |。它不认识带引号的 CSV,只用于制表符分隔的文本,也不补齐列宽,不过渲染器本来就不看这些空格。

几种麻烦的单元格

情况 结果
合并单元格 被拆开或丢失,因为竖线表格没有跨行跨列
单元格里换行 变成空格、<br> 或 HTML 表格,看工具
单元格里有竖线 Pandoc、上面的 awk 和妙言都会转义成 \|
对齐 通常丢失,tablesgenerator.com 除外
表头 一律是第一行

这些限制来自 GFM 规范,表头行和分隔行的单元格数量必须一样,否则整块不会被识别成表格,数据行单元格比表头少会补空单元格,多出来的被忽略,单元格里也不能放块级元素。

表格依赖合并单元格或单元格内的列表时,写成带 colspan 或 rowspan 的 HTML <table>,或者拆成两张更简单的表。

在妙言里粘贴表格

妙言没有 CSV 或 TSV 导入,粘贴制表符分隔的文本时也不会自动变成竖线,它转换的是 HTML。剪贴板里带有包含 <table>、标题、列表、引用或代码块的 HTML 版本时,编辑器会插入 Markdown 而不是纯文本。表格这部分,V4.9.0 的源码是这样处理的。

  • 第一行一律成为表头,不管有没有 th。
  • 单元格里的竖线转义成 \|。
  • 单元格里的换行变成空格。
  • 比最宽那一行短的行,右边补空单元格,代码不读 colspan,所以合并的单元格变成一个单元格,空缺出现在行尾,不在合并的位置。
  • 分隔行是普通的 ---,不保留对齐。

这个功能针对的是从浏览器复制的富文本,电子表格粘贴能不能走这条路,取决于那个应用有没有往剪贴板里放 HTML。粘出来是制表符的话,用 Pandoc 或生成器转一遍再粘贴结果。Markdown 转 HTML 讲了表格在别的工具里为什么有时显示成原始竖线。

检查结果

要看渲染后的表格,别只看源码。表格渲染成一段竖线,几乎都是分隔行和表头单元格数量不一致,某一列错位通常是数据里有没转义的竖线,单元格里原样显示 <br>,说明查看器把 HTML 转义了。表格很长时,看最后一行和最宽的一行,多余的制表符和缺掉的单元格大多出现在那里。

常见问题

为什么从 Excel 粘贴出来是制表符?

电子表格应用把复制的区域当成用制表符分隔的纯文本,Markdown 表格用的是竖线,所以要先转换。

Markdown 表格能合并单元格吗?

不能,竖线表格就是一张普通网格,要合并就用带 colspan 或 rowspan 的 HTML 表格,或者把数据拆开。

CSV 文件怎么转成 Markdown 表格?

运行 pandoc -f csv -t gfm file.csv,或者把文件导入 tablesgenerator.com 这类生成器,想让 Pandoc 写竖线表格,先去掉单元格里的换行。