pandoc新手入门教程：1小时掌握基础转换操作

pandoc新手入门教程：1小时掌握基础转换操作

【免费下载链接】pandoc Universal markup converter 项目地址: https://gitcode.com/gh_mirrors/pa/pandoc

你是否还在为文档格式转换烦恼？从Markdown到Word，从HTML到PDF，不同场景需要不同格式的文档，手动转换既耗时又容易出错。pandoc作为一款通用标记转换器（Universal markup converter），能帮你轻松解决这些问题。本文将带你在1小时内掌握pandoc的基础转换操作，读完你将能够：安装pandoc、了解支持的文件格式、掌握常用转换命令、学会自定义转换选项，并解决常见问题。

安装pandoc

pandoc支持多种操作系统，包括Windows、macOS和Linux，你可以根据自己的系统选择合适的安装方式。

Windows系统

在Windows上安装pandoc有多种方法，最简便的是使用安装程序。你可以从pandoc的下载页面获取最新的msi安装包，双击运行即可完成安装，安装程序会自动将pandoc添加到系统路径中。

如果你更喜欢命令行方式，可以使用Chocolatey包管理器安装：

choco install pandoc

或者使用winget：

winget install --source winget --exact --id JohnMacFarlane.Pandoc

macOS系统

macOS用户可以通过Homebrew安装pandoc：

brew install pandoc

也可以从下载页面，运行命令perl uninstall-pandoc.pl即可。

Linux系统

Linux用户可以通过系统的包管理器安装，例如在Debian/Ubuntu上：

sudo apt-get install pandoc

如果系统仓库中的版本较旧，你可以从下载页面获取最新的deb包或tarball。安装deb包的命令为：

sudo dpkg -i pandoc-*.deb

认识pandoc支持的格式

pandoc支持丰富的输入和输出格式，几乎涵盖了所有常见的标记语言格式。

输入格式

pandoc可以从多种格式读取文档，包括但不限于：

• Markdown系列：commonmark、gfm（GitHub-Flavored Markdown）、markdown（Pandoc的Markdown）等
• 办公文档：docx（Word文档）、odt（OpenDocument文本）
• 标记语言：html、latex、rst（reStructuredText）
• 其他：json（AST表示）、org（Emacs Org mode）、ipynb（Jupyter notebook）等

完整的输入格式列表可以查看pandoc官方文档中的相关部分。

输出格式

pandoc可以将文档转换为多种输出格式，常见的有：

• 文档格式：docx、pdf、odt、rtf
• 标记语言：html、markdown、latex、rst
• 演示文稿：beamer（LaTeX幻灯片）、pptx（PowerPoint）、revealjs（HTML5幻灯片）
• 电子书：epub（电子书格式）

pandoc还支持生成多种幻灯片格式，如dzslides、slidy、s5等，对应的模板文件位于data/dzslides/等目录下。

基础转换操作

掌握pandoc的基础转换操作非常简单，核心命令格式为：

pandoc [输入文件] -o [输出文件]

pandoc会根据输入文件和输出文件的扩展名自动识别格式。

Markdown转HTML

将Markdown文件转换为HTML文件：

pandoc example.md -o example.html

Markdown转PDF

要将Markdown转换为PDF，pandoc默认使用LaTeX引擎，因此需要系统中安装有TeX发行版（如TeX Live、MiKTeX）。转换命令为：

pandoc example.md -o example.pdf

Word文档转Markdown

将Word文档转换为Markdown：

pandoc example.docx -o example.md

HTML转Markdown

将HTML文件转换为Markdown：

pandoc example.html -o example.md

自定义转换选项

pandoc提供了众多选项来自定义转换过程，满足不同的需求。

设置元数据

你可以通过-M或--metadata选项设置文档的元数据，如标题、作者、日期等：

pandoc example.md -o example.pdf -M title="我的文档" -M author="张三" -M date="2023-10-07"

这些元数据会在输出格式中相应的位置显示。

指定格式

如果文件名不能明确表示格式，可以使用-f（--from）和-t（--to）选项显式指定输入和输出格式：

pandoc -f html -t markdown example.html -o example.md

使用模板

pandoc允许使用自定义模板来控制输出格式的样式。你可以使用--template选项指定模板文件：

pandoc example.md -o example.html --template mytemplate.html

pandoc提供了一些默认模板，位于data/templates/目录下。

添加CSS样式

转换为HTML时，可以通过-c选项添加CSS样式表：

pandoc example.md -o example.html -c style.css

实际应用示例

批量转换多个文件

如果需要批量转换多个Markdown文件为HTML，可以使用shell脚本：

for file in *.md; do
    pandoc "$file" -o "${file%.md}.html"
done

转换Jupyter笔记本

将Jupyter笔记本（ipynb格式）转换为Markdown：

pandoc example.ipynb -o example.md

生成电子书

使用pandoc可以轻松生成EPUB电子书：

pandoc chapter1.md chapter2.md -o book.epub -M title="我的电子书" -M author="作者名"

常见问题解决

中文字体显示问题

在生成PDF时，如果中文字体显示不正常，需要在LaTeX模板中指定中文字体。可以创建一个包含以下内容的LaTeX模板文件（如chinese-template.tex）：

\documentclass{article}
\usepackage{fontspec}
\setmainfont{SimSun} % 设置宋体
\setsansfont{SimHei} % 设置黑体
\begin{document}
$body$
\end{document}

然后使用该模板生成PDF：

pandoc example.md -o example.pdf --template chinese-template.tex --pdf-engine=xelatex

转换后格式错乱

如果转换后的文档格式错乱，可能是因为原文档中使用了pandoc不支持的复杂格式。此时可以先将文档转换为pandoc的AST JSON格式进行调试：

pandoc example.md -t json -o example.json

查看JSON文件，分析格式问题所在。

缺少依赖

转换某些格式时，pandoc可能需要额外的依赖。例如，生成PDF需要LaTeX环境，转换SVG图片可能需要rsvg-convert工具。你可以根据错误提示安装相应的依赖。

总结与进阶

通过本文的学习，你已经掌握了pandoc的基础安装、格式认识和转换操作。pandoc还有更多强大的功能等待你探索，如：

• 使用Lua过滤器扩展pandoc功能，相关文档和示例可参考doc/lua-filters.md
• 自定义读者和作者，详见doc/custom-readers.md和doc/custom-writers.md
• 集成到自动化工作流中，如使用GitHub Actions或GitLab CI/CD

pandoc的官方文档MANUAL.txt提供了更详细的信息，建议深入阅读以发掘更多高级用法。现在，你可以开始使用pandoc简化你的文档格式转换工作了！

【免费下载链接】pandoc Universal markup converter 项目地址: https://gitcode.com/gh_mirrors/pa/pandoc