使用 pypandoc 转换各类文档

使用 pypandoc 转换各类文档

[TOC]

pandoc 是一个能转换各种文档的神器,使用 python 中的 pypandoc 库可以很方便的操作 pandoc 进行文件转换。

首先我们参考了pypandoc 的介绍页面。第一步就是安装,简单是使用 pip 安装会报错,不支持 python 3.6。所以这里推荐使用 conda 安装。安装命令如下:

 conda install -c conda-forge pypandoc

该命令会自动安装好一切所需环境,所以只用等着就好了。(安装 pandoc 的时候非常慢,要翻墙才会快一些。)推荐这种安装方法,安装好 pandoc 后会自动添加到 path 中。如果使用其他安装方式,就需要手动添加路径.

import os
os.environ.setdefault('PYPANDOC_PANDOC', '/home/x/whatever/pandoc')

安装好之后就可运行了。

import pypandoc

# With an input file: it will infer the input format from the filename
output = pypandoc.convert_file('somefile.md', 'rst')

# ...but you can overwrite the format via the `format` argument:
output = pypandoc.convert_file('somefile.txt', 'rst', format='md')

# alternatively you could just pass some string. In this case you need to
# define the input format:
output = pypandoc.convert_text('#some title', 'rst', format='md')
# output == 'some title\r\n==========\r\n\r\n'

以上都很好解释,可以将 markdown 文件转换为格式的字符串。对中文支持也是友好的。难点在于转化为 pdf,pandoc 转化 pdf 需要 latex 的支持,完全安装好 texlive 就没什么问题了,这里默认已经安装好了。

安装好后,对于英文文档,使用以下名利就可以转换了。

output = pypandoc.convert_file('input.md', 'pdf', outputfile='output.pdf')

难点在于中文文档,因为 pandoc 默认是使用 pdflatex 编译的,不支持中文,因此首先要添加命令,使用 xelatex 来编译文件。

output = pypandoc.convert_file('input.md', 'pdf', outputfile='output.pdf', 
                               extra_args=['--latex-engine=xelatex'])

使用关键词 extra_args 来添加编译引擎。这时编译后发现所有中文字都不显示。这是字体的问题,因为编译时默认的字体时不支持中文的,所以我们得手动设置中文字体。导出字体命令为:fc-list >> C:\fonts.txt。从中挑选希望的中文字体。

output = pypandoc.convert_file('input.md', 'pdf', outputfile='output.pdf',
  extra_args=['--latex-engine=xelatex', '-V', 'mainfont="SimSun"'])

如果没有问题的话就可以显示中文了。我是一边写这个文档,一边用 pandoc 转换看效果的。到目前为止有两个问题:1. 有些字符转换会报错,比如这个 fc-list >> C:\fonts.txt,如果没有用字符包起来就会报错,主要原因好像是有些字符再 latex 里是有其他意义的,因此会导致转换错误,应对的方法是在前面加斜杠转移一下。或者嫌麻烦尝试包装起来;2. 转换后的中文字符不会自动换行。因此十分不美观。因此还需要使用 latex 模板来修复这个问题。这里用到的是 tzengyuxio 提供的 pm-template.latex。下载完成后,将文件中 LiHei Pro 字体替换为我们的中文字体,如 SimSun。将 pm-template.latex 文件放在 md 源文件所在目录下,同时添加命令 --template = pm-template.latex 使用该模板生成目标 pdf 文件。

output = pypandoc.convert_file('input.md', 'pdf', outputfile='output.pdf',
  extra_args=['--template=pm-template.latex', '--latex-engine=xelatex', '-V',
              'mainfont="SimSun"'])

现在应该可以正常显示中文了,不过又遇到一个麻烦的问题,就是转换为 pdf 后图片会自动浮动到页面顶部,而不是 latex 中常用的 htbp (即表示优先就地放置,然后在顶部,底部,下一页,如果我没记错应该是这个顺序,反正优先就地放置是没错的)。所以还要修改一下模板文件,我也不太会修改,但是 pandoc 默认的输出时对的,所以我们可以先看一下默认模板里的设置,在 cmd 中使用命令 pandoc -D latex > my.latex 导出默认设置,可以看到里面有这么几行

% set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother

原来 htbp 是这么设置的,我们把这几行复制到 pm-template.latex 中,位置应该无所谓,我复制到了 graphics 代码块的下面。再次运行转换命令,就可以得到我们期待已久的结果了。下面插入了一个公式和图片是测试效果的。

虽然 pandoc 可以转成 pdf,但是效果确实不太好,不如直接使用 typora 软件的导出 pdf 功能。如果这个功能也能命令行就好了。

$$E=MC^2+\int^{2}_{3}$$

xihu

References:

1. pandoc 官方网址

2. 利用Pandoc将markdown文件转化为pdf

3. 使用Pandoc实现Markdown文件转PDF文件