Flyaway's Blog

神器Pandoc的安装与使用

前言

其实很早就知道Pandoc这个东西了，只是一直没有什么需求促使我去使用它。平时写博客虽然也是用Markdown，但是由于Jekyll并不支持Pandoc，所以也没有特别去研究它(目前博客使用的是Kramdown渲染器，它在很多扩展语法都是借鉴Pandoc的。)。可是时过境迁，现在平时需要写一些非正式报告和总结，每次使用word的时候总觉得不舒服，有次为了调整一个段落的行距搞了1个多小时，虽然可以说是我自己没有学好word的基本操作，但是每次为了寻找一个功能"翻箱倒柜"地在网上找方法，彻底破坏了写作的情绪，这实在让我很难受。因此我选择markdown来进行平时的写作，为了达到这个目的，必须要选择一个markdown的渲染器，网上有着各式各样的渲染器，还有一些可以直接在线渲染的网站。但是平时在本地编辑的时候，总要开个浏览器，这实在让人接受不了。在众多渲染器中，最先映入眼帘的就是Pandoc了，号称为文本格式转换的瑞士军刀，既然有了这个称号，说明其功能是非常不错的。后来查了一下，发现果然是一个神器，它甚至可以生成pdf和docs！

Pandoc的官网在这里，网上有很多具体介绍Pandoc的文章，其中质量比较高的有:

本文就不再赘述上面文章提到过的一些基本概念和操作了，如果读者还不知道Markdown和Pandoc是什么的话，请阅读上述文章。

配置

具体的安装过程上述文章和Pandoc的官网上都有，此处不再细说了，这里主要说明一些在安装过程遇到的问题和解决方法(以windows7为例)。

系统路径

在Windows下Pandoc安装的时候，默认是安装在用户主目录下的，以win7为例，就是C:\Users\USERNAME\AppData\Local\Pandoc，照理来说安装程序是应该会把这个目录添加到Path中去的，但是我发现并没有自动添加，因此首先要将这个目录手动加入到Path中，这样才能在任何的目录下进行调用。

生成HTML

就我自己而言，我使用Pandoc最主要的功能就是利用它来生成HTML和PDF文件，本节先讨论HTML的配置方法，下一节再来说明pdf的配置。

其实将markdown生成html，是Pandoc最基本的一个功能，使用起来也是非常简单的，打开cmd，切换到makrdown文本所在的目录，写入如下代码1:

:::bash
pandoc in.md -o out.html

程序运行之后，就会在当前目录下生成一个相应的out.html文件。

CSS样式

上面这是最基本的用法了，但是这还不能满足我的日常需求，单纯的html文件太过单调了，只有配上相应的CSS样式，才能使得文本以更加优美的方式展现出来。

可喜的是pandoc完全支持加入css一起渲染，利用如下的命令：

:::bash
pandoc in.md -c style.css out.html

其中style.css是为生成的html文件编写的样式文件，但是这个style.css应该放在哪呢？放在当前目录下，当然没问题，但是每次编写markdown的时候，都要将这个css文件复制到当前目录下，那岂不是很麻烦？因此我要想办法把它放在一个固定的地方，每次直接调用就可以了。

这就引出了pandoc的默认目录了，可以通过pandoc --version命令来查看pandoc当前的默认目录，还是以windows7为例，它的默认目录是C:\Users\USERNAME\AppData\Roaming\pandoc ,只需要将这个style.css文件放入到这个目录下，那么在任意目录使用pandoc时，都能自动读取到这个文件，而且，如果需要一些特殊的css样式，可以在当前目录编写，pandoc会自动使用当前目录下的style.css替代默认目录中的style.css文件。

生成独立HTML

通常来说，写作的目的是写给别人来看的，但是如果是使用html文件的格式的话，那么每次传输都需要传送整个目录文件，因为会有很多图片或css文件需要一起被传送，否则html会无法正确显示。这显然是很麻烦的，有没有办法让pandoc在生成的时候，自动把style.css中样式代码直接嵌入到html中呢？办法当然是有的，主要是参考了这篇文章。主要有两种方法：

第一种是使用方法是使用如下的命令:

:::bash
pandoc -s -H style.css  in.md -o out.html

但是当我试用这种方式的时候，发现style.css文件必须放在当前目录下，这个命令才能正常执行，否则会报错说找不到style.css文件。

另外一种更加好的方式使用--self-contained参数:

:::bash
pandoc -s --self-contained -c style.css in.md -o out.html

这个命令不但会把css文件嵌入到html中，它会把所有外部文件全部压缩进单个html文件中，包括图片、视屏、音乐等。这是何等强大的功能！！

利用上述这个命令，就能将markdown文档轻易地生成一个真正独立的html文件，不需要任何其他外部文件支持，这就非常方便传递了。

生成pdf

生成一个pdf文件也是pandoc的主要功能之一，但是它要依赖于latex，如果需要使用pandoc来生成pdf文件，那么需要另外安装Latex，pandoc官方推荐安装MiKTeX，具体安装过程也不说了，非常简单。安装好MikTex之后，可以利用如下的命令来生成pdf:

:::bash
pandoc in.md -o out.pdf

但是这样命令会出现这样的错误

! Package inputenc Error: Unicode char \u8:鍒?not set up for use with LaTex. pandoc: Error producing PDF from Tex source. See the inputsnc package documentation for explanation. ...

原因是pandoc默认选择的pdf引擎是pdflatex，而pdflatex是不支持中文的，因此会发生上述错误。因此在使用pandoc的时候，可以手动指明Latex引擎为xelatex，这是完全支持中文显示的。这样我们的命令就变成了:

:::bash
pandoc in.md -o out.pdf --latex-engine=xelatex

使用这个命令能够正常的编译出pdf文件，但是当你打开编译出来的pdf文件时，会发现其中的中文部分全是空白，这是字体的问题，因为Latex的默认字体是不支持中文的，因此我们可以继续修改命令：

:::bash
pandoc in.md -o out.pdf --latex-engine=xelatex -V mainfont=SimSun

其中mainfont参数是用来指明所使用的字体，SinSun表示的是宋体，你可以选择其他支持中文的字体。

但是这个命令还是有问题的，打开生成的pdf，你会发现其中的中文完全是没有断行的，这是因为pandoc本身对中文支持不够，但这不是说我们没有解决方案，解决方案是使用网友编辑好的latex模板来生成pdf，这里用到的是tzengyuxio提供的pm-template.latex4。 下载模板后将其中的LiHei Pro字体替换成系统中安装有的中文字体即可，然后编译命令改为

:::bash
pandoc in.md -o out.pdf --latex-engine=xelatex --template=pm-template.latex

这时就能生成一个比较完美的pdf文件了。

Vim与Pandoc

既然现在有了panodc这个神器，那么大部分的文本编辑操作我就可以在Vim中进行了，而不需要去使用那个无比臃肿的word了，配合Vim强大的定制功能，我就能配置出一个功能完善的pandoc写作环境了。

这显然又是一个很深的话题，这里我只是稍微写一下配置过程，因为我自己本身也还在研究当中。

首先可以为markdown文件映射几个命令，使得可以快捷的生成html，在Vim的_vimrc文件中加入如下代码：

:::vim
function! ToHtml()
    exec 'w'
    exec "!pandoc  -s -S --self-contained -c style.css % -o %<.html "
endfunction

function! ToPdf()
    exec 'w'
    exec "!pandoc  % -o %<.pdf --latex-engine=xelatex --template=pm-template.latex"
endfunction
:nmap <silent> <F5> :call ToHtml()<CR>
:nmap <silent> <F6> :call ToPdf()<CR>

上述的代码中，我首先定义了两个函数，分别是用来调用pandoc来生成html和pdf文件的，然后映射了两个快捷键<F5>和<F6>去调用这两个函数，这样就实现了直接在Vim中调用pandoc生成html或pdf，而不再需要通过命令行来调用。

最后推荐一个比较好的pandoc插件:vim-pandoc，这个插件我也是刚刚开始使用，感觉还不错，值得推荐。

参考资料

  1. 如果发现没有pandoc命令，说明还没有将安装目录添加到系统Path中，请查看上一节内容。 ↩

Share on: Twitter ❄ Facebook ❄ Email

Flyaway is the owner of this blog.
Comments

So what do you think? Did I miss something? Is any part unclear? Leave your comments below

comments powered by Disqus

Published

Category

misc

Tags

Contact