简单介绍

pandoc 是一款开源的跨平台的标记语言格式转换工具,功能强大且非常好用。

由于平时习惯使用 markdown 作为文本语言,因此在这里简单介绍如何利用 pandoc 将 markdown 文本转为 pdf、html 或者 docx 等格式。

注意,标记语言文本的格式需为 UTF-8 编码格式。如遇格式问题,可复制文本内容后打开 notepad++ 选定 UTF-8 编码格式,然后将文本粘贴。

安装 pandoc

Windows 下安装 pandoc

  • 下载 pandoc-2.1.3-windows.msi 安装包,运行后默认安装

  • 下载 pandoc-2.1.3-windows.zip 压缩包解压缩,并添加 PATH 路径。

MacOS 下安装 pandoc

推荐使用 brew 直接进行安装

$ brew install pandoc

Linux 下安装 pandoc

在官网下载 pandoc-2.1.3-linux.tar.gz 压缩包。

# pandoc 2.0 之后的版本可如下安装
$ sudo tar xvzf pandoc-2.1.3-linux.tar.gz --strip-components 1 -C /usr
# 查看 pandoc 路径,可直接用 rm /usr/bin/pandoc 删除
$ which pandoc
$ pip install pandocfilters  # 安装依赖
# 查看语法
$ pandoc -h
# 查看支持的输入格式
$ pandoc --list-input-formats 
# 查看支持的输出格式
$ pandoc --list-input-formats 
# 查看支持的脚本高亮语言
$ pandoc --list-highlight-languages
# 查看支持的高亮风格
$ pandoc --list-highlight-styles

一些选项

  • -f 指定输入文件格式,省略参数则自动根据后缀判断文件类型
  • -t 指定输出文件格式,省略参数则自动根据后缀判断文件类型
  • -o 必选,指定输出文件名
  • -s 使生成的文件包含头段脚注信息和元数据,能够离线观看
  • -i 控制幻灯片中的列表每条逐渐进入
  • --toc 使生成的文件以目录开始
  • --listings 利用 listings 包渲染代码高亮
  • --mathjax 使生成的 html 支持数学公式
  • --pdf-engine=xelatex 使用 xelate 引擎使生成的 pdf 支持中文
  • -V mainfont=SimSun theme=default 一些设置
  • --slide-level=3 设置 3 级标题生成幻灯片,默认为 2
# md2html    
$ pandoc -f markdown -t html test.md -o test.html -s --mathjax
$ pandoc test.md -o test.html

# md2pdf  转换 pdf 需要安装 latex,我安装了 texlive
# pandoc 默认模板不支持中文,生成的 pdf 代码块不显示中文注释,可以更改模板 documentclass 为 ctex,例如 ctexrep ctexbook ctexart 等
$ pandoc test.md --pdf-engine=xelatex -V mainfont=SimSun -o test.pdf
$ pandoc test.md -o test.pdf --template=zzy.tex --listings --pdf-engine=xelatex

# md2rst
$ pandoc test.md -o test.rst

# md2docx
$ pandoc test.md -o test.docx

制作幻灯片

利用 markdown 书写文本简单快捷,利用 pandoc 转换为幻灯片更是快捷方便。

转化前可以在 markdown 文本开头输入三行以 % 开头的元信息:标题、作者和日期。

在默认情况下每个二级标题是一张独立的幻灯片,在写作的时候需注意把每个二级标题下的内容控制在适当的长度。

为了调整幻灯片的格式可以在 markdown 中利用 -------- 来强制生成新的幻灯片,也可以利用 . . . 添加停顿。

pandoc 内置了多种 html 框架幻灯片模板,包括比较简单的 DZslides 和 slidy。也可以选择直接下载别人的模板使用,例如 s5、slidous 和 reveal.js 等

reveal.js 包含了多个主题可供选择: default、beige、sky、night、serif、simple、solarized、black、blood、league、 moon、white 等。

# DZslides 模板
$ pandoc test.md -o slides.html -t dzslides -s --mathjax -i
# Slidy 模板,依赖 www.w3.org,打开速度慢
$ pandoc test.md -o slides.html -t slidy -s --mathjax -i
# revealjs 模板,从官方下载到本地
$ git clone https://github.com/hakimel/reveal.js
$ pandoc test.md -o slides.html -t revealjs -s -V theme=beige --mathjax -i
# beamer 模板, 生成 pdf 格式的幻灯片,支持数学公式
$ pandoc test.md -o slides.pdf -s -i -t beamer --pdf-engine=xelatex -V mainfont=SimSun
# 导出 beamer 模板进行自定义,修改 documentclass 为 ctexrep
$ pandoc -D beamer > test.tex
$ pandoc -o test.pdf -t beamer --template test.tex --pdf-engine=xelatex test.md 

一些可用的模板可在此下载