Pandoc新手使用常见问题

一、Pandoc可以做什么？

Pandoc 可以很方便快捷地对不同语言的文件进行格式转换，因此被誉为格式转换的「瑞士军刀」。常见的应用包括但不限于将markdown格式文件转换为latex格式和pdf格式等等。

二、下载与安装

访问Pandoc官网进行安装包下载。

下载完成后在本地运行安装程序。

完成后可以按Win+R打开控制台，输入

pandoc --version

如果返回了一个具体的pandoc版本，没有发生报错，说明安装成功。

三、使用问题

问题一：xelatex not found. Please select a different --pdf-engine or install xelatex

问题产生的原因：在将含有latex格式代码的进行转换时尝试调用xelatex库，但这个库在本地没有安装。

解决方案：

下载并安装MiKTeX发行版。

下载到本地并进行安装后，我们需要手动添加环境变量。将MiKTex目录下的

\miktex\bin\x64

文件夹添加到Windows系统的环境变量。

Tip：

1.按Win+I打开系统设置

2.选择设置->系统->系统信息->高级系统设置->环境变量->系统变量->Path

3.双击打开Path目录，将上面的目录添加到环境变量。

添加路径完成后，在cmd中输入

xelatex --version

检查MiKTeX是否安装成功并已经被添加的环境变量。

再次运行Pandoc相关指令，不再发生此报错。

问题二：[WARNING] Missing character: There is no 绗?pandoc.exe: <stderr>: hPutChar: invalid argument (Invalid argument)

类似的报错还有很多，比如：

[WARNING] Missing character: There is no 绗?pandoc.exe: <stderr>: hPutChar: invalid argument (Invalid argument)

[WARNING] Missing character: There is no 涓?pandoc.exe: <stderr>: hPutChar: invalid argument (Invalid argument)

[WARNING] Missing character: There is no 鍨?pandoc.exe: <stderr>: hPutChar: invalid argument (Invalid argument)

[WARNING] Missing character: There is no 鍒?pandoc.exe: <stderr>: hPutChar: invalid argument (Invalid argument)

问题产生的原因：Pandoc 默认使用转换方式 pdflatex 命令无法处理 Unicode 字符，如果要处理的Markdown 文件包含中文，我们需要使用 xelatex ，并且需要使用 CJKmainfont 选项指定支持中文的字体。

解决方案：

使用类似下面格式的指令。

其中"KaiTi"表示的是指定中文字体为“楷体”

pandoc --pdf-engine=xelatex -V CJKmainfont="KaiTi" test.md -o test1.pdf

如何查看自己的系统支持什么字体？

在cmd中输入如下指令

fc-list :lang=zh

可以看到控制台打印出类似下图的支持列表

问题三：当我添加了中文转换的参数后，Pandoc在将Markdown转换为PDF格式时仍然发生和问题2中相同的报错

问题产生的原因：在latex公式里如果使用中文，需使用\text命令将公式中的中文包裹起来。

在多行公式中使用单行公式，其中的中文即使已经在\text中，仍然需要再次使用\text进行包裹，具体格式如图中的例子。

问题四：引用块、表格或列表无法正确渲染

转换后得到的PDF文件中，引用块（Block Quote）、表格（Table）或列表（List）无法正确渲染。

问题产生的原因：在 Pandoc 中规定，Block Quote，Table 以及 List 前需要空一行。

解决方案：在每个没有正确换行并渲染的位置前面多打一个回车，额外空出一行。

四、参考

本文参考了@jdhao大佬的Pandoc教学：纯文本做笔记 --- 使用 Pandoc 把 Markdown 转为 PDF 文件

大佬好厉害qwq

参考了@小林up大佬的报错解决方案：

pandoc输出中文pdf cmd命令记录_pandoc 中文-CSDN博客

大佬太强了pwp

如果有帮助到您的话，可以点一个赞吗TwT，我会很开心。