应用场景

我喜欢用 Markdown 写文档，但不是所有读者都愿意花时间学习它，所以我需要将 Markdown 转换为他们习惯接受的格式，比如 docx 或 html；偶尔需要做幻灯片演示，也可以用 Markdown 来写，然后转换为幻灯片(Slideshow)。

Pandoc 的最基本的应用场景就是做这类转换。

当然，Pandoc 能做的远远不止这些。实际上它是一个非常强大的文档格式转换工具，支持数十种文档格式互转。至于有多强大，作者有张个图表，大家感受下。

本文仅以 Windows 平台为例介绍 Pandoc 最基础的应用方法。

安装使用

• 推荐在 Github Pandoc Releases 页面下载适合自己操作系统的最新版本安装包，一路按默认设置安装即可。

• 安装完看不到软件界面？别担心，一切都在命令行中完成！CTRL+R 输入 cmd进入命令提示符，运行下列命令：

  pandoc --version

  如果安装成功，可以看到 Pandoc 的当前版本和其他相关信息。

• 进入到 Pandoc 的工作目录，可能需要用到以下常用 cmd 命令：
  • 进入F盘，直接运行 F:
  • 查看子目录和文件，运行 dir
  • 进入 myforder 文件夹，运行 cd myforder
  • 进入上级目录，运行 cd ../
  • 进入根目录，运行 cd /
  • 按上下方向键可以快速键入前后输入的命令

Pandoc 命令格式

• 查看帮助，运行

  pandoc --help

  可以看到 Pandoc 的命令格式

• 基本格式

  pandoc [options（选项）] [input-file（输入文件）]

  详细选项请看 User's Guide 。

文件转换示例

1. 将 Markdown 格式转换为 Html。下面这条命令将 input.md 转为html并且输出为 output.html

   pandoc -o output.html input.md

2. Pandoc 会自动根据文件扩展名判断文件格式，也可指定输入和输出文件格式：

   pandoc -f markdown -t html -o output.html input.md

3. 除了文件，还可以转换一个网页：

   pandoc -f html -t markdown -o index.md http://miu.im

4. 指定 css 样式，用到 -c 选项

   pandoc -c style.css -o output.html input.md

5. 生成独立的文件 (Standalone 模式)

   pandoc -s -o output.html input.md

6. 生成目录，--toc 可以自动提取 h1 - h6 并生成目录，使用--toc-depth 控制输出的目录级别，默认值是3，就是说会自动提取h1 - h3 作为输出文件的目录。

   pandoc -c style.css -o output.html --toc --toc-depth=3 input.md

更多示例请参考官方 Demos 。

生成幻灯片

利用 Pandoc 可以方便生成 Html 幻灯片，类似 PowerPoint、Keynote的效果。目前 Pandoc 对以下几种 Html 幻灯框架支持：

1. DZSlides
2. Slidy
3. S5
4. Slideous
5. reveal.js

这里我只介绍 reveal.js 的使用（我只用过这个..不过其他几个也大同小异 😳 ）。

reveal.js 是一个非常流行的 Html 幻灯片框架，通过编辑 Html 创建幻灯片，不过直接编辑 Html 相当繁琐。使用 Pandoc 的好处就是，一条命令就可以解决问题，不需要编辑 Html。

• 准备 reveal.js

  1. 在 reveal.js Release 页面下载 reveal.js 2.6.2 源码包（目前 Pandoc 1.12 还不能很好支持 reveal.js 3.0.0，主要是指定主题风格无效，可手动调整）。

  2. 解压 reveal.js 至工作目录，将解压得到的文件夹重命名为 reveal.js (去掉版本号)。工作目录结构类似这样：

     F:\workspace
     │　slides.md
     └─reveal.js
     　├─css
     　├─js
     　├─lib
     　├─plugin
     　└─test

• Markdown 文件 slides.md 的内容如下：

% Nonsense Stuff
% John Doe
% March 22, 2005
# In the morning
## Getting up
- Turn off alarm
- Get out of bed
## Breakfast
- Eat eggs
- Drink coffee
# In the evening
## Dinner
- Eat spaghetti
- Drink wine
------------------
## Going to sleep
- Get in bed
- Count sheep

• 生成幻灯片

  pandoc slides.md -o slides.html -t revealjs -s

• 指定主题，可以在 /css/theme 文件夹下查看支持的主题

  pandoc slides.md -o slides.html -t revealjs -s -V theme=night

• 幻灯片级别

  reveal.js 默认每个2级标题生成一个幻灯片，高于2级的标题（1级标题）生成一张独立的仅包含标题的幻灯片，而低于2级的标题（3级标题）将存在于上一级标题的幻灯片中，不单独生成新的幻灯片。

  可以使用 --slide-level 选项覆盖默认的幻灯片级别，不过严重不推荐。

  使用分割线可强制生成新的幻灯片，以下任意一种均可：

  ***
  ---
  +++
  

• 逐条显示

  生成幻灯片时加入 -i 选项，如果幻灯片中有列表，列表中每一项会逐条显示。

  两段文字显示之间的人为停顿，用如下分割线：

  . . .

• 幻灯片切换方式 transition， 可选切换方式有："default", "cube","page", "concave", "zoom", "linear", "fade", "none"

• 保存为完全独立文件 --self-contained。添加这个选项后会自动将需要的 css、js、图片、字体等资源都整合到一个单独的 html 中。（不过实测该选项有一些问题，还在摸索中...）

• 一个完整的示例，生成的幻灯片预览。

  pandoc slides.md -o slides.html -t revealjs -s -i -V theme=night  -V transition=default --toc  --toc-depth=1
  

相关链接

• Pandoc
• Pandoc Demos
• Pandoc User's Guide
• reveal.js

参考链接

• Producing slide shows with Pandoc
• Markdown+Pandoc→HTML幻灯片速成
• 幻灯片中图片来源于 Tame Your Tykes at Greens Cafe