Linux环境下安装pandoc

裘安阳
2023-12-01

概述

本篇文章主要讲解:

  • pandoc的安装及其一些注意事项
  • 使用pandoc将md文件转PDF,HTML文件指令介绍
  • pandoc进阶(用指令对图片的设定)

本文为我个人安装及使用pandoc过程中对遇到的一些问题及使用心得的总结,仅供参考。

pandoc简介

Pandoc 是一个命令行工具,用于将文件从一种标记语言转换为另一种标记语言。标记语言使用标签来标记文档的各个部分。常用的标记语言包括 Markdown、ReStructuredText、HTML、LaTex、ePub 和 Microsoft Word DOCX。
简单来说,Pandoc 允许你将一些文件从一种标记语言转换为另一种标记语言。典型的例子包括将 Markdown 文件转换为演示文稿、LaTeX,HTML,PDF等文件

1.pandoc安装前要知道的事情

第一件:

我个人不推荐直接使用 sudo apt-get install pandoc 这个指令来安装pandoc
直接使用这个指令安装的pandoc版本受制于你当前ubuntu系统版本,也就是说如果你当前的Ubuntu系统版本较低,那么使用该指令直接安装的pandoc版本也是低版本。
低版本的pandoc有什么头大的问题:
1.pandoc的编译指令不能编译beamer
2.不能通过指令给代码块,引用等设定语法高亮背景颜色等
(虽然有解决的办法,但是一次性安装好高版本的pandoc给你带来的丝滑感受难道不好吗?)

第二件:

如果要pandoc转PDF文件,你还需要安装latex环境的支持
Tex发行版,你可以安装texlive或者MiKtex,安装完成后需要配置环境,建议是安装texlive
如果你的的空间足够的话使用:sudo apt-get install texlive-full 安装完整版的tex套件,什么包都有了,就不用折腾在安装其他依赖的包了。
一般安装个texlive套件也够了,这里提供linux下texlive安装教程

第三件:

pandoc的插件(建议安装)
1.pandoc参考文献支持的插件:pandoc-citeproc
2.pandoc交叉引用支持的插件:pandoc-crossref (这是一个“用于对图表,方程式,表格和交叉引用进行编号的过滤器”)

2.pandoc的安装

从Haskell平台的软件包管理器cabal安装pandoc

  1. 安装Haskell平台
sudo apt-get install haskell-platform    #安装Haskell的包管理器
  1. 安装pandoc
cabal update              #获取Haskell包信息
cabal install pandoc      #通过cabal安装pandoc
(或cabal install pandoc --force-reinstalls )
  1. 插件的安装
cabal install pandoc-crossref  
cabal install pandoc-citeproc
  1. 配置环境变量

使用 vim ~/.bashrc.bashrc文件最后面把 ~/.cabal加到路径中去如下

export PATH=/home/myzh/.cabal/bin:$PATH

如果需要删除旧版本的pandoc更新至新版,使用如下命令 :

sudo apt-get autoremove pandoc            #删除pandoc
sudo apt-get install cabal-install
cabal update
cabal install pandoc

3.pandoc指令的使用

  1. 讲解使用pandodc指令给代码块,引用等设置高亮背景色
  2. 官网上许多pandoc指令的列子

3.1生成PDF文件指令

可参考上面的“讲解使用pandodc指令”的连接了解更多指令

pandoc --latex-engine=xelatex --template=mytemplate.latex --toc -N --highlight-style zenburn test.md -o test.pdf

–toc : 生成目录
-N :给标题添加编号

–latex-engine=xelatex :这是指定指定使用xelatex编译引擎(支持中文)

–template=mytemplate.latex : 这是指定编译使用的latex模板(该模板放到pandoc默认的模板文件夹下)

–highlight-style zenburn :给代码块设置语法高亮(推荐使用zenburn,espresso,breezedark,tango主题)

一些常用指令介绍

-f: 指定输入格式,比如docx、epub、md、html等
-t: 指定输出格式,比如docx、epub、md、html等
-o: 输出到file文件
–verbost: 显示详细调试信息
–log: 指定输出日志信息

–list-input-formats:列出支持的输入格式。
–list-output-formats:列出支持的输出格式。
–list-extensions:列表支持Markdown扩展,后面跟一个+或者-说明是否在pandoc的Markdown中默认启用。
–list-highlight-languages:列出语法突出显示支持的语言。
–list-highlight-styles:列出支持语法高亮的样式。。
-v: 打印版本信息。
-h:显示语法帮助

上面指令中使用的mytemplate.latex模板,
点此连接进行查看pandoc转pdf文件用的latex模板介绍(Linux环境)
了解使用模板要注意的问题。

3.2生成HTML

pandoc -s --self-contained -c mystyle.css test.md -o test.html

-s :生成独立的html文件
–self-contained : 这个命令不但会把css文件嵌入到html中,它会把所有外部文件全部压缩进单个html文件中,包括图片、视屏、音乐等。

-c mystyle.css : 指定使用css样式文件,单纯的html文件太过单调了,只有配上相应的CSS样式才能使得文本以更加优美的方式展现出来。

其中mystyle.css是为生成的html文件编写的样式文件,但是这个style.css应该放在哪呢?放在当前目录下,当然没问题,但是每次编写markdown的时候,都要将这个css文件复制到当前目录下,那岂不是很麻烦?因此我要想办法把它放在一个固定的地方,每次直接调用就可以了。
这就引出了pandoc的默认目录了,可以通过pandoc --version命令来查看pandoc当前的默认目录,以linux为例,它的默认目录是/ussr/share/pandoc/date/templates/ ,只需要将这个style.css文件放入到这个目录下,那么在任意目录使用pandoc时,都能自动读取到这个文件,而且,如果需要一些特殊的css样式,可以在当前目录编写,pandoc会自动使用当前目录下的mystyle.css替代默认目录中的mystyle.css文件。

4.pandoc进阶(图片处理)

1.图片乱排处理

pandoc将md文件转换为PDF文件时,事先用markdown布置好的图片位置,会发生自己没法控制的变化,它们会堆到一起。我相信这是由于通过LaTeX的转换,但我不确定如何在Markdown源中解决这个问题.
如果我使用带有几段示例文本的占位符图像并策略性地将图像放置在源代码中,它会变得太大而无法放在我放置它的位置的页面上,因此LaTeX布局引擎将它放在下一页.但是,我宁愿这没有发生,因为这意味着图像不是我期望的地方,更难以引用.
如果有必要,我可以包含一个示例,但重现并且源需要有点广泛来填充整个页面.
解决办法:
使用pandoc的语法尝试停用implicit_figures(可以使图片放在原先的位置,如果图片太大其也会自占一页,自己斟酌使用)

pandoc -f markdown-implicit_figures myfile.md -o myfile.pdf

可以在markdown文档中使用markdown语法修改图片的大小尺寸(注:此方法也是从网上找到的,自己亲测没有效果,不知是何原因,先放这吧也许某个人使用就行了呢)

![图片名](image/hua.jpg){width=50%}
2图片对齐

想在同一行中对齐两张图像,使用的markdown语法如下:

![图片名](image/aa.jpg)\ ![图片名](image/bb.jpg)

但是要注意图片尺寸,如果图片过大,转成pdf后两张图片并排会超出边界

控制图片尺寸可以用html的语法,但该语法只是适合转成html文件才有效。  
通过pandoc使用xelatex引擎编译成pdf不生效, 

<img src="图片连接" width = "400" height = "400" alt="图片名称" align=center>
参考

简书pandoc的安装
黑魔法利器pandoc
通过命令行Pandoc 来转换文件

 类似资料: