保留现场
1 |
|
探究原因
图片链接错误,转换 PDF 过程中会先下载所有图片到AppData/Local/Temp/tex2pdf.****
文件夹里,因为无法正常下载图片,所有报错。检查图片链接是否有效。
解决方法
检查图片链接是否有效。
Markdown 的简便性是 LaTeX 无法替代的,LaTeX 对排版的精准控制能力又是 Markdown 无法比拟的。一直在寻找一种能够将 Markdown 优雅地转换成 PDF 的解决方案,虽然早就听说也使用过 Pandoc 这把瑞士军刀,但是它太过强大,以致于一直都没用明白。只会简单的转换命令,但是实际效果并不好,最近学会了使用 LaTeX 模板的功能,这才让我眼前一亮,这才是我想要的结果。
Markdown 生成 PDF 主要需要使用 Pandoc 和 LaTeX 两个工具,具体安装方式如下:
Pandoc 是由 John MacFarlane 开发的标记语言转换工具,可实现不同标记语言间的格式转换。
Windows 下的安装:
choco install pandoc
winget install pandoc
Linux/FreeBSD下的安装:
apt/dnf/yum/pacman
之类的安装工具直接安装即可macOS 下的安装:
brew install pandoc
详细的安装说明参见:官方安装文档
LaTeX 工具,建议安装 texlive。
apt/dnf/yum/pacman/pkg
等安装工具安装 texlive、texlive-latex 等相关软件包为保证生成的 pdf 格式(自动插入封面、目录页、页眉页脚等信息),在本地环境中安装模板,具体步骤是:
template/mppl.latex
拷贝到*/pandoc/templates
目录下C:/Users/USERNAME/AppData/Roaming/pandoc/templates
,如果Roaming
没有pandoc
目录,请手动创建!~/.pandoc/templates/
模板定制主要修改模板最前面的模板基础配置相关内容,主要可修改的包括:
目前页面默认的字体是微软雅黑,对于非 Windows 系统,可能不存在该字体,则有以下两种解决方案:
若需要多个团队共同使用,建议采用方案一。
在每个 Markdown 最前面增加以下主要 metadata 信息,metadata 内容开始行内容为三个“-”,结束行为三个“.”,示例如下:
1 |
|
其他可选配置项目如下:
可选配置项中,建议除了 subtitle 外,全部在模板中定制,不在 Markdown 文件中定制
Pandoc 默认使用的 pandoc_markdown 格式,为避免 Markdown 转 pdf 格式异常,在编写 Markdown 的时候有几个原则要求:
总之,不同文本类型之间都要有空行。
1 |
|
打开 VSCode 编辑器,在插件页搜索 markdown-preview-enhanced
,接着点击 Install
按钮。详情参考VS Code 安装 MPE。
Markdown Preview Enhanced 以下简称 MPE
新建文件以.md
为后缀即可开始编辑 Markdown 文件,使用 MPE 实时预览与导出。
右击 MPE 的预览区域,可以看到 MPE 提供多种导出 PDF 的方案,如使用 Chrome 的 Puppeteer 导出,Prince 导出,Pandoc 导出等等。
在未使用 Pandoc 前,我也一直使用 MPE 提供的 Chrome 方式导出,但是导出的 PDF 排版总是不尽如意。现在介绍如何使用 Pandoc 方式导出。
创建 PDF 文档,你需要在 markdown
文件中的 front-matter
里声明 pdf_document
的输出类型:
1 |
|
front-matter
:文章的最开头,也就是上文元数据放的地方。和元数据放在一起即可,如图所示:
latex_engine
:默认情况下 PDF 文档由 pdflatex
生成。你可以用 latex_engine
选项来定义你想用的引擎。支持的引擎有 pdflatex
,xelatex
,以及 lualatex
。这里需要使用xelatex
。
pandoc_args
:配置 Pandoc 接受的一些参数,这里我们使用 --template=mppl.latex
和 --listings
来指定模板和使用 listings
。这里配置的参数就是执行 Pandoc 时使用的参数,以后就不需要命令行输入了。这里使用上文的mppl.latex
模板。
配置完之后,右击预览界面,选择 Pandoc 导出,稍等片刻,即可生成 PDF 文件。
VSCode 导出出错时报错信息较短,并且常常不知道具体报错原因及位置,因为是 LaTeX 转换成 PDF 的过程中出现的错误。报错位置是 LaTeX 中间源码的位置,而不是 VSCode 中的位置。这时候我常用的方法是先将 Markdown 转为 LaTeX,然后再转为 PDF,在 LaTeX 编辑器里就可以看到错误位置了。
比如下面这个错误,我们能看到一些报错信息cant use \spacefactor in math mode
,但是并不知道具体哪里的错误。从信息里可以看出和\LaTex
有关,大概能推测出是使用了这个命令,因为文章里使用了这个命令的地方只有一处。但是如果有其他的错误,就很难确定了。
这里还是以模板仓库的README.md
为例,当然这个文件是可以正常转换 PDF 的,不会报错。这里只是拿README.md
做一个如何使用命令的演示。
1 |
|
打开README.tex
文件,编译:
我们可以快速的定位到问题出现的位置,只要搜索相关问题即可。
\LaTeX{} 这个宏不能用在数学模式下。但是因为我在 Markdown 里必须使用美元符号
$$
才能表示 LaTeX 环境,才能正确输出 LaTeX 符号,而 Markdown 转换成 LaTeX 源码时,这个宏就会被包裹在数学环境里,就会报错。如果我想在 PDF 里显示这个符号,那就在 Markdown 里不使用美元符号$$
,而是直接输入\LaTeX{}
即可,再导出 PDF 时就不会报错。
Update your browser to view this website correctly. Update my browser now