学术论文写作新武器：Markdown-中篇

liyu_sun 2021-04-24

展开全文

📅 2021 年 5.2-4 日
🔑 主讲：梁平汉(中山大学)；张川川 (浙江大学)；连玉君 (中山大学)

New！ lianxh 命令发布了： GIF 动图介绍
随时搜索 Stata 推文、教程、手册、论坛，安装命令如下：
. ssc install lianxh

作者：初虹 (公众号「虹鹄山庄」创办人)
E-mail：20170237402@mail.sdufe.edu.cn

本文源自 「学术论文写作新武器：Markdown」 系列专栏：

学术论文写作新武器：Markdown-上篇
学术论文写作新武器：Markdown-中篇
学术论文写作新武器：Markdown-下篇

我们在第一期推文中重点推荐了使用 Markdown 进行学术论文的写作，介绍了什么是 Markdown、选择 Markdown 的原因及编辑器、格式转换工具 Pandoc。那写完的 Markdown 文章如何转成其他格式呢？不加「调教」的 Pandoc ，工作完成的不算太满意，那怎样转成符合学术论文的要求呢？这期我们先来说说怎么转 Word 格式，下期我们看看如果转成 PDF 格式。

1. 更改模板 DOCX 文件样式表

1.1 图注、表注
1.2 表格

2. 参考文献的转换

2.1 VScode 插入引文
2.2 导出 `.bib` 引文文件
2.3 下载 `.csl` 参考文献样式文件

3. 编号：交叉引用

3.1 下载安装
3.2 基本语法

4. 参考文献
5. 相关推文

温馨提示： 文中链接在微信中无法生效。请点击底部「阅读原文」。或直接长按/扫描如下二维码，直达原文：

我们在上期看到了 Pandoc 默认转换的样式 : ) 嗯，有待改进。

pandoc test_paper.md -o test_paper.docx

设想一下，第一次开组会，导师发给大家一个 Word 模板，说以后写论文就按照这个格式来。比如，这个模板文件长这样：

主标题：华文新魏、小二、黑色
副标题：黑体、四号、加粗、黑色
作者：楷体、五号
摘要：楷体、五号，Cambria、五号
标题一：黑体、小三、加粗、黑色
标题二：宋体、小四、加粗、黑色
标题三：宋体、五号、加粗、黑色
正文：宋体、五号，Times New Roman、五号，段前缩进 2 字符、行距 17 磅
表格：三线表、上下线宽 1.5 磅、标题行下线宽 0.5 磅
脚注：宋体、小五号，Times New Roman、小五号
图注、表注：楷体、小五号，Cambria、小五号，居中
目录、超链接、参考文献（书目）：宋体、五号，Times New Roman、五号，黑色
数学公式：使用 LaTeX 语法，行内公式以$包裹、行间公式以$$包裹
参考文献列表：宋体、五号，Times New Roman、五号

上面格式参考借鉴于山东财经大学经济研究中心李启航教授开设《 应用计量经济学与 Stata 操作 》课程论文的 Word 模板。

懂点儿 Word 进阶操作的小伙伴们都知道，在 Word 里修改样式表，可以方便后期不断复用。那我们能不能借鉴这个思路，为我们的 Markdown 转 DOCX 加点料儿呢？

1. 更改模板 DOCX 文件样式表

Pandoc 允许通过修改模板 DOCX 文件来自定义 Word 文档显示样式。通过下面的命令可在当前目录打开 Pandoc 默认的生成的 Word 模板custom-reference.docx（文件名称随便），可在此基础上根据个人需求修改。

pandoc --print-default-data-file reference.docx > custom-reference.docx

Pandoc 生成的 DOCX 模板文件的默认样式：custom-reference.docx

我在这个地方遇到了个小 BUG：生成 DOCX 模板时命令行乱码、并且打开时出错。可能是使用 PowerShell 的原因，换成 CMD 能解决问题。

接着说，一般来讲，我们只需要在模板文件custom-reference.docx样式表右键 → 修改，调出样式修改菜单，更改字体、段落等信息就好了。绝大多数样式均可如此完成修改。

但是有几处需要注意的点。

1.1 图注、表注

custom-reference.docx默认模板文件没有图注、表注对应的样式，因此需要新建样式并自定义格式。

图注和表注没有默认样式

默认图注在图片下方，而表注在表格上方。下面的动图以新建表注样式为例进行演示：

1.2 表格

经济学期刊论文的表格多以「三线表」为主，新建表格样式模板demo_a，具体修改如下：

改好之后，使用 Pandoc 命令指定模板 DOCX 文件转换之后，还需要手动应用表格样式。下面看看怎么快速手动调整表格。理论上你可以根据自己的需求新建许多表格样式，在转换完之后手动应用就行。

Pandoc 转换对表格支持不太好，需要微调的地方相对来说最多。如果你的论文里需要多种表格样式，那么恐怕 Pandoc 能实现的效果有限，还是需要后期手动修改。如果你知道怎么做后期改动最少，欢迎留言区或邮件告诉我🤝🤝。

完成样式修改之后，我的自定义模板文件长这样~~

这下你就可以使用指定模板样式文件 ref.docx 来转换了。

pandoc --reference-doc=ref.docx test_paper.md -o test_paper.docx

2. 参考文献的转换

处理参考文献，我们总不能还是手动加文中编号、手动根据期刊要求一条条、一遍遍地修改吧？！一款方便易用的文献管理应用就派上大用场了。这里介绍 Zotero。

Zotero 是一款免费开源的全平台文献管理应用，拥有 macOS、Windows 和 Linux 多系统版本，可以在 Zotero 官网下载 Zotero 主程序及相应浏览器插件 Zotero Connector。（篇幅限制，此不赘述。）

图源 Zotero 官网 https://www./

2.1 VScode 插入引文

为便于文献条目的导出和引文的插入，插件 Better BibTeX for Zotero 必不可少。在这里 | GitHub 下载 .xpi（Zotero 插件的格式）文件，回到 Zotero 主程序，点击工具 → 插件 → 右上角小齿轮 → Install Add-on From File → 选择下载好的 .xpi 文件，即可完成插件的安装。Better BibTeX 可为每一条文献条目生成一个 ID 值 —— CitationKey。使用 CitationKey 就相当于告诉 Zotero 要在这里插入引文了。

引文的插入，需要遵循 Pandoc 语法：[@CitationKey]（句末引用）或 @Citation（句内引用）。一次次复制粘贴 CitationKey 是个办法，不过未免也太不高效了吧。像这样：

VScode 里安装几个扩展，就能使这一流程优雅、高效得多。

Citation Picker for Zotero 安装完成后，可使用快捷键 Alt + Shift + Z 呼出 Zotero 搜索框🔎🔎快速插入引文。

注意：使用 Citation Picker for Zotero 时，应开启 Zotero 主程序，否则会报错👇👇。

未开启 Zotero 主程序时的 VScode 插件 CPZ 出错

若你想实现 Cite While You Write （所写即所引）的效果，那需要试试另一个扩展 —— Pandoc Citer。不过需要在文章开头添加 MetaData，如下所示。其中 [] 为参考文献引文的路径（可以是相对路径）。MetaData 的语法格式为 YAML，以 --- 开头和结尾，对象键值之间使用 : 隔开（注意冒号后面有一个空格），关于 YAML 的具体用法，可见 YAML | 菜鸟教程🐥。

---
bibliography: [./ref.bib]
---

2.2 导出 `.bib` 引文文件

在 Markdown 文件里插入了引文，使用 Pandoc 转换时，我们还得告诉 Pandoc 引文来自哪里。所以就需要将论文中用到的所有文献批量导出 .bib 文件，重命名为 ref.bib，方法如下：

Zotero 导出 Better Bibtex 文件

2.3 下载 `.csl` 参考文献样式文件

不同期刊对于参考文献的样式要求也大不相同。更多样式可在 Zotero Style Repository 下载，本文以国标 GB/T 7714-2015 numeric为例。

到这儿，就能处理参考文献了。下面是参考文献部分的完整命令。

pandoc --citeproc `
--bibliography=ref.bib`
--csl=china-national-standard-gb-t-7714-2015-numeric.csl `
-M reference-section-title='参考文献' -M link-citations=true `
test_paper.md -o test_paper.docx

--citeproc：处理文献引用
--bibliography=ref.bib：指定引文文件为 ref.bib
--csl=china-national-standard-gb-t-7714-2015-numeric.csl：指定参考文献列表的样式为「国标 GB/T 7714-2015 numeric」格式
-M reference-section-title='参考文献'：文末生成参考文献列表的标题「参考文献」
-M link-citations=true：文中引用点击可实现跳转到底部参考文献该条目

我们距成功又近了一大步！

3. 编号：交叉引用

解决了参考文献这一大难题，只剩下图表编号交叉引用这个硬骨头🦴🦴了。这就用得到 pandoc-crossref ，一个 Pandoc 过滤器，用于对数字、图片、表格和参考文献等进行编号。

3.1 下载安装

scoop install pandoc-crossref

pandoc-crossref必须与 Pandoc 版本相同，如果不一致，则会报错：

WARNING: pandoc-crossref was compiled with pandoc 2.12 but is being run through 2.13. This is not supported. Strange things may (and likely will) happen silently.

3.2 基本语法

pandoc-crossref 官网介绍的交叉引用，主要包含五个方面：标题、图片、表格、公式和列表。由于学术论文引用列表不常见，所以本文将此略去。

下面涉及的 label 指的是标签名称，可任意自定义，用来唯一标识某个标题、图片或公式等。如果没有明确的标签，将无法正确引用该 block。

在待引用的地方使用{#block_name:label}告诉 Pandoc 需要进行编号以及将要被引用；在使用的地方就可[@block_name:label]或@block_name:label来引用了。

3.2.1 标题

Section {#sec:label}

Pandoc-crossref 支持通过标题模板进行高级定制。模板被指定为 YAML 元数据变量，具体参见可见自定义编号方案一节。

pandoc-crossref 实现引用标题的效果

3.2.2 图片

![Caption](file path){#fig:label}

file path 可以是本地图片地址或网络图片地址（或图床链接）

如果不了解什么是图床，详情请见这里 | 少数派或这里 | 虹鹄山庄。当然，如果使用了图链，应在有网络的条件下进行转换，否则会报 PandocHttpError 的错误。

图片块和 {#fig:label} 之间不能有空格。

pandoc-crossref 实现引用图片的效果

3.2.3 表格

a   b   c
--- --- ---
1   2   3
4   5   6

: 表注 Caption {#tbl:label}

表注 Caption 是以 : 开头，位于表体下方或上方，至少与表体有一空行的距离。
表注 Caption 与 {#tbl:label} 之间至少一个空格。

pandoc-crossref 实现引用表格的效果

3.2.4 公式

数学公式支持使用 LaTeX 语法。行内公式使用 $ 包裹、行间公式 $$ 包裹。

这是行内公式：$\int_{0}^{1} x dx = \left[ \frac{1}{2}x^2 \right]_{0}^{1} = \frac{1}{2}$

这是行间公式：$$e^x = \sum_{n=0}^\infty \frac{x^n}{n!} = \lim_{n\rightarrow\infty} (1+x/n)^n$$

pandoc-crossref 语法对公式的应用如下：

$$ math $$ {#eq:label}

公式块与标签 {#eq:label} 之间的空格可有可无。

pandoc-crossref 实现引用公式的效果

3.2.5 MetaData 元数据

除此之外，要想实现高级定制的显示效果，Pandoc 和 pandoc-crossref均提供了 MetaData 的形式进阶操作。引用阮一峰的介绍：Metadata（元数据），描述数据的数据（Data that describes other data），最大的好处是，可使信息的描述和分类可以实现格式化，从而为机器处理创造了可能。

在 Pandoc 和 pandoc-crossref 中，Metadata 以 YAML 的形式存储，可以放在文章的开头；或存储于 .yaml 文件中，使用 Pandoc 命令时加上 ref.yaml 即可，二者实现效果的相同。我一般将作者、标题等 Pandoc Metadata 放于文章开头，其余的 Metadata 信息放在 ref.yaml 文件中。

这一块可以说是整套流程中最磨人的地方了，有不少细节值得注意。不过，仅实现常见的效果、也花费不了太多功夫。剩下的手动改改有时候也比自动化来的容易。具体内容可参见这里 | Pandoc-Metadata 或这里 | pandoc-crossref-Metadata

注意：由于 pandoc-crossref 使用与 citeproc 相同的引用语法，因此必须在后者之前运行前者。例如：

pandoc -F pandoc-crossref --citeproc file.md -o file.html

文末提供的下载链接里test_pandoc_crossref.md文件就是关于 Pandoc 处理交叉引用的部分，如果对此感兴趣，可以单独下载、运行试试：

pandoc -F pandoc-crossref `
--reference-doc=ref.docx `
crossref.yaml `
test_pandoc_crossref.md -o test_pandoc_crossref.docx

关于本文使用到的 Metadata，我也在 ref.yaml 里添加了注释，或许有助于你的理解🧐🧐

好了，Markdown 转 Word 就结束了。看看效果如何？还是文章开头的完整命令：

pandoc -F pandoc-crossref --citeproc `
--bibliography=ref.bib `
--csl=china-national-standard-gb-t-7714-2015-numeric.csl `
--reference-doc=ref.docx `
-M reference-section-title='参考文献' -M link-citations=true `
ref.yaml `
test_paper.md -o test_paper.docx

当然，还是有几处需要手动修改的地方。