Pandoc 3.9.0.2
- 我强烈建议安装完全一致的版本，因为我曾看过一些Pandoc Filter需要与Pandoc版本完全一致才能使用，比如pandoc-crossref，而我不太清楚我现在用的Pandoc Filter是否有相似的要求，除非你完全确信你选择的版本可以运行（多试试也没坏处，如果你不是急着要转换文档的话）。
- 安装完成后需要确保Pandoc在你的环境变量中。使用pandoc --version指令检查Pandoc版本并测试是否能成功找到Pandoc。
Python 3.11和Astral UV
- Python和UV的版本实际上限制不是那么大，没必要完全一致，确定能用即可。
- Astral UV安装完后在本目录下运行uv sync来初始化环境。

用法

在本目录下执行以下指令进行文档转换：

uv run pandoc <thesis.tex> \
    -s \
    -f latex -t docx \
    --citeproc \
    --metadata-file=meta.yaml \
    -F pandoc-tex-numbering \
    --resource-path <path-to-tex-dir> \
    --reference-doc=my-thesis.docx \
    -o <thesis.docx>

参数解释：

uv run pandoc要求在UV的虚拟环境中执行Pandoc命令，让Pandoc能够找到在虚拟环境中安装的使用Python编写的Pandoc Filter。
<thesis.tex>在执行的时候替换为指向你待转换的LaTeX文档的路径。
-s表示Standalone模式，用于表示生成一个独立的文档，而不仅仅是文档片段。
-f latex -t docx用于显式指定输入输出格式。
--citeproc用于启用引用解析功能，不启用就没有引用标识。
--metadata-file=meta.yaml指定了元数据，包括：引用文献样式和pandoc-tex-numbering过滤器等相关配置。
-F pandoc-tex-numbering显式指定使用pandoc-tex-numbering过滤器。
--resource-path <path-to-tex-dir>用于设置LaTeX资源文件夹。Pandoc会在你指定的<path-to-tex-dir>文件夹中查找文档中引用的图片和子文档等内容。一般来说，需要设置为你待转换的LaTeX文件所在的文件夹的路径。
--reference-doc=my-thesis.docx设置了转换到DOCX格式时使用的模板。你也可以把my-thesis.docx换成你想要的模板，至于如何编辑属于你的模板，请参考后文。
-o <thesis.docx>：在执行的时候将<thesis.docx>替换为指向你存储转换后的DOCX文档的路径。

过滤器补丁

本项目采用了名为pandoc-tex-numbering的过滤器，这是一个很棒的项目，但它能够做到我期望的样子的新版本并没有及时在PyPI上发布，因此我不得不使用一种比较“脏”的手段来使其达到我想要的效果。我采用Git Diff的方式给下载下来的最新版pandoc-tex-numbering的源码打补丁，使其符合我的需求。等新版本发布在PyPI上后，这一步就不再需要了。下面将介绍如何打这个补丁。

应用补丁

Warning

应用补丁前，请确保已经使用uv sync指令配置好虚拟环境，否则以下指令无效。

在该目录下执行以下命令以应用补丁：

git apply --directory pandoc/.venv/Lib/site-packages/pandoc_tex_numbering numbering-caption-delimiter.diff

其中--directory选项用于在diff文件的路径前附加指定路径，使其成为一个完整的，相对于git根目录的路径。

撤销补丁

Warning

如果不执行撤销补丁的指令，由于Astral UV的硬链接原因，所有使用该版本pandoc-tex-numbering包的项目都会受到该补丁影响。因此我强烈建议在使用完本环境后将补丁撤销。

当你使用完本环境后，执行以下命令以撤销补丁：

git apply -R --directory pandoc/.venv/Lib/site-packages/pandoc_tex_numbering numbering-caption-delimiter.diff

其中-R选项表示反向应用补丁。

DOCX模板

该目录下的my-thesis.docx文件是我已经编辑好的模板。该模板可以满足我的大部分的需求，输出也足够的美观。

创建模板

通常而言你无需重新创建该模板，但如果你更换了Pandoc的版本，或者你的格式需求与我不一致，你就需要重新创建属于你自己的DOCX模板。以下内容将讲述如何创建属于你自己的DOCX模板，这也是我创建我自己模板时的步骤。

导出默认模板

使用pandoc -o <custom-reference.docx> --print-default-data-file reference.docx来导出模板。其中：

<custom-reference.docx>是导出的DOCX模板的存放路径。
--print-default-data-file用于指示Pandoc导出内部模板。
reference.docx是固定文本，不得改变。

修改模板

使用Word，而非WPS，LibreOffice，macOS Word等软件，来修改此模板。打开模板后，你会发现其中包含一系列文本。这些文本是方便你预览效果用的，我们需要修改的是样式，修改样式后这些文本也会变化。

在Ribbon栏的“开始”选项卡下，找到“样式”部分，点击右下角的小箭头，展开“样式”对话框。可选的，你可以点击最下方的“选项...”按钮，将列表的排序方式选择为“按类型”以获得更好的浏览体验。

找到“正文”样式，它是几乎所有样式的基础，我们要在这里修改全局的字体设置。点击其右边的小箭头，选择“修改”，打开对话框。
- 字体的中文改为宋体，西文改为Times New Roman，字号设置为小四。
- 段落的间距改为段后0.5行。
找到“正文文本”样式，它是所有正文文字的样式。其段落为首行缩进2字符。
找到“标题1”至“标题9”样式，依次修改。将颜色设置为自动。中文改为黑体，西文保持Times New Roman。字号依次为：三号，四号，小四（后面全是小四）。并删除所有倾斜和加粗。
找到“标题”样式，它是除了正文标题以外的其它标题的基础格式。将字体中文改为黑体，西文改为Times New Roman。
找到“题注”样式，它是“Image Caption”和“Table Caption”这两个样式的基础。对其进行修改。
- 字体设置为黑体，字号为五号，并删除斜体样式。
- 段落设置为居中。
找到“Figure”样式，它决定了插入的图的样式。将其段落设置为居中，以让插入的图居中。
找到“超链接”样式
- 字体的中文改为宋体，字号设置为小四。如果不改的话，它会试图继承“题注”的样式，会导致正文里样式不一致。
- 删除其颜色。
找到“书目”样式，它是参考文献列表所用的样式。
- 字体设置为宋体，字号为五号。
- 段落设置为悬挂缩进2字符。
找到“脚注文本”样式。它是脚注文本的样式。
- 字体的字号改为五号。
点击文档中的表格，转到Ribbon栏的“表设计”选项卡下，点击表格样式右边的下拉箭头，选择“修改表格样式”。打开对话框。
- 进入“边框和底纹”对话框，把上下框线加上，这样就实现了三线表。
- 进入“表格属性”对话框设置
  - 把“表格”选项卡里的“对齐方式”设置为“居中”，让表格在段落中居中。
  - 把“行”选项卡里的“允许跨页断行选项”关掉，以保证表格美观。

缺点

目前该环境存在以下缺点：

不能够按照原生Word编写的方式，使用交叉引用来进行文献和图表的引用。我不打算在这个环境中通过Pandoc Filter来解决这个问题，我打算直接通过编写专门的转换器来解决（详见XThesis分支）。
不能够将LaTeX的\clearpage或\newpage换页指令翻译成换页符。我写了一个Lua Filter来完成这个工作，现存的也有官方的过滤器可以完成这一工作，但它必须启用latex+raw_tex扩展后才能正常使用。但是这个raw_tex扩展带来的副作用远大于启用其的好处。首先是我各种图片的大小设置全部失效了，另外，面对不认识的环境名，它也不输出环境中的内容了。
不能够处理不认识的命令。我的LaTeX文档中用了一些自定义的命令，这些命令它不识别就算了，它连其参数都不愿意以字面量输出出来。比如\my_style{Keywords}，它直接什么都不输出，但我期望他能够至少把Keywords输出出来，即使在不认识\my_style的情况下。

README.md Unescape Escape

Pandoc Thesis Environment

必要条件

用法