前言

其实很早就知道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:

pandoc in.md -o out.html

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

CSS样式

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

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

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中呢?办法当然是有的,主要是参考了这篇文章。主要有两种方法:

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

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

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

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

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:

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,这是完全支持中文显示的。这样我们的命令就变成了:

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

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

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

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

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

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文件中加入如下代码:

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: TwitterFacebookEmail


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