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

发布时间：2021-04-20 阅读 5603
分享到微信 分享到微博 收藏文章

 

Stata连享会   主页 || 视频 || 推文 || 知乎

温馨提示： 定期 清理浏览器缓存，可以获得最佳浏览体验。

New！ lianxh 命令发布了：
随时搜索推文、Stata 资源。安装命令如下：
  . ssc install lianxh
详情参见帮助文件 (有惊喜)：
  . help lianxh

 

✌ 课程详情： https://gitee.com/lianxh/Course

 

⛳ 课程主页： https://gitee.com/lianxh/Course

 

⛳ Stata 系列推文：

 

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

 

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

 

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

 

目录

 

我们在上期看到了 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
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.zotero.org/
图源 Zotero 官网 https://www.zotero.org/

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 出错
未开启 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 文件
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 实现引用标题的效果
pandoc-crossref 实现引用标题的效果

3.2.2 图片

![Caption](file path){#fig:label}
  • file path 可以是本地图片地址或网络图片地址（或图床链接）

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

  • 图片块和 {#fig:label} 之间不能有空格。
pandoc-crossref 实现引用图片的效果
pandoc-crossref 实现引用图片的效果

3.2.3 表格

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

: 表注 Caption {#tbl:label}
  • 表注 Caption 是以 : 开头，位于表体下方或上方，至少与表体有一空行的距离。
  • 表注 Caption 与 {#tbl:label} 之间 至少一个 空格。
pandoc-crossref 实现引用表格的效果
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 实现引用公式的效果
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

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

  • 公式部分未显示完全（正文段落样式为 17 磅导致）
  • 图片大了、小点更好
  • 表格不是「三线表」

稍作调整~~成品看这里

Markdown 转 Word 已实现，Markdown 转 PDF 我们下期见！

下载地址：FavourHong蓝奏云 | https://honghujun.lanzous.com/iiDBLo6mp7e

 

4. 参考文献

 

5. 相关推文

Note：产生如下推文列表的 Stata 命令为：
  lianxh Markdown
安装最新版 lianxh 命令：
  ssc install lianxh, replace