! Undefined control sequence.
<recently read> \tightlist 

l.213 \end{frame}

pandoc: Error producing PDF from TeX source
make: *** [test.pdf] Error 43

这是因为在 Markdown 文件中使用-表示无序列表，被转化成了\tightlist但是 Pandoc 版本太老，不支持这个命令。（严格来说是 Pandoc 没有处理这个 LaTeX 命令，不是不支持，因为这是 LaTeX 命令和 Pandoc 没关系）。

有两种方式解决，一是升级 Pandoc 版本，二是将处理\tightlist的命令加到自己使用的模板中。

\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

或者

\def\tightlist{}

在 LaTeX 编译中报错：Missing character: There is no (U+00A0) (U+00A0) in font JetBrains Mono。

探究原因

如果要搞清楚具体原因，就得从字符与字符编码说起了。解决办法直接跳到下一节吧。

字符，就是“a”，“A”，“你”等书写符号。

字符集，通常就是某种语言字符集合，比如英语就是ASCII 字符集，中文有GBK 字符集等

注意，不是每种语言只对应一种字符集（比如 GB2312，GBK，GB18030 都包含了常用汉字，后者是前者的超集），而且字符集也不是只对应一种语言，例如 Unicode 字符集就包含所有语言字符，字符集只是设计者为了给字符编码（Code Point/Numbering）设计编码时，为了收录到命名的字符集合，但是通常设计者都为字符集设计了对应的编码规范。

字符编码,给字符集里的字符编号。

编码页，在 unicode 发明之前，各个地区都用 2 字节编码自己的字符集，相同的编码对应不同的字符，为了本地化，Windows 发明了编码页，来对应不同的字符集。

字符编码，对给定的字符编码编码成字节表示。

早期，字符被编号后，存储时就按照编号的方式存储，没有 encoding 的过程，后来发明 Unicode 后，发现如果按照 Unicode 的编号直接存储的话，对于英文字符就有很大存储浪费，因为任意字符都需要 2 字节存储，后来人们发明 UTF-8 这种编码方式，这样 UTF-8 就可以一个字节表示英文字符，2 个以上字节表示汉字字符。

字体，定义了字符的图形表示，现在的软件展示字符时用 Unicode 表示，字体是 Unicode 编码和字符图形的映射，而以往比如 WindowsCMD 控制台，没有对应 Unicode，则用编码页来区分，所以字体就是字符编码金和代码页到字符图形的映射。

文本文件存储在磁盘上，都是一系列的字节流，如果不告诉文本编辑器该文件的编码方式，编辑器会尝试用默认的编码（依赖于操作系统设置）又或者自己探测（detect，比如文件开头有 FFEF 或者 EFFF 字节就表明 UTF-16 编码，有很多 10，110 开头的字节，很可能是 UTF-8 编码）并尝试解码，如果没有猜对，那就会显示乱码。

回到出错的问题，提示我们在字体 JetBrains Mono中没有U+00A0，我们搜索一下就知道这是一个 Unicode 字符NO-BREAK SPACE。我们通过上面的了解也知道了，字体就是字符编码到字符图像的映射，但是一个字体尤其是一些有专门用途的字体（比如 JetBrains Mono 设计初衷是为软件工程显示代码用的），它不会映射所有的字符，JetBrains Mono 这个字体里就没有映射 U+00A0。这就导致在 LaTeX 编译时无法在字体中找到对应的字符图像显示。

所有解决办法就是要不替换掉这个字符，要不换个字体。

解决方法

VSCode 正则搜索\U00A0即可搜索到相关字符，将其替换成空格。

参考

字符，字符集，字符编码，编码页，字体 - 简书

backgroundcolor 背景颜色

numbers 代码行号

\lstset{
    numbers             = left,             % 行号靠左
    basicstyle          = \ttfamily,        % 基本代码风格
    keywordstyle        = \bfseries,        % 关键字风格
    commentstyle        = \ttfamily,        % 注释的风格
    frame       = single,                   % 阴影效果
    escapeinside=``,                        % 英文分号中可写入中文
    xleftmargin=2em,xrightmargin=2em, aboveskip=1em,
    breaklines          =   true,
    language            = C,                % 语言选C
} 

\lstset{
    numbers             = right,            % 行号靠左
    basicstyle          = \ttfamily,        % 基本代码风格
    keywordstyle        = \bfseries,        % 关键字风格
    commentstyle        = \ttfamily,        % 注释的风格
    frame       = single,                   % 阴影效果
    escapeinside=``,                        % 英文分号中可写入中文
    xleftmargin=2em,xrightmargin=2em, aboveskip=1em,
    breaklines          =   true,
    language            = C,                % 语言选C
} 

stepnumber 间隔显示行号

\lstset{
    numbers             = right,            % 行号靠左
    stepnumber          = 2,                % 每两行显示一次行号
}

firstnumber 开始行号

• firstnumber = 10 开始行号为 10
• firstnumber = last 开始行号为上一段 listing 的结束行号

xleftmargin/xrightmargin/aboveskip/below 距离外部元素距离

设置代码块上下左右的距离，与外部元素的距离，而不是代码与边框的距离。

\lstset{
    basicstyle          = \ttfamily,        % 基本代码风格
    numbers             = left,            % 行号靠左
    keywordstyle        = \bfseries,        % 关键字风格
    commentstyle        = \ttfamily,        % 注释的风格
    frame       = single,                   % 阴影效果
    escapeinside=``,                        % 英文分号中可写入中文
    xleftmargin=0em,xrightmargin=0em, aboveskip=0em,belowskip=0em,
    breaklines          =   true,
    language            = C,                % 语言选C
} 

\lstset{
    basicstyle          = \ttfamily,        % 基本代码风格
    numbers             = left,            % 行号靠左
    keywordstyle        = \bfseries,        % 关键字风格
    commentstyle        = \ttfamily,        % 注释的风格
    frame               = single,                   % 线框
    escapeinside        =``,                        % 英文分号中可写入中文
    xleftmargin         =5em,
    xrightmargin        =0em, 
    aboveskip           =2em,
    belowskip           =0em,
    breaklines          =   true,
    language            = C,                % 语言选C
} 

frame 边框样式

设置边框样式：

• none:无框
• single:单线框
• leftline,topline,rightline,bottomline:上下左右的线
• ltrb:上面参数的缩写，frame=lr 表示左右有线
• LTRB:大写表示双线

\lstset{
  frame               = single,        % 线框
} 

\lstset{
  frame               = shadowbox,        % 阴影
} 

\lstset{
  frame               = LR,        % 左右边框双线
} 

rulesepcolor 阴影颜色

\lstset{
  frame               = shadowbox,        % 阴影
  rulesepcolor= \color{ red!20!green!20!blue!20} , % 阴影颜色
} 

rulecolor 边框颜色

\lstset{
    rulecolor           = \color{red},      % 边框颜色
} 

frameround 边框倒角

\lstset{
  frameround          = fftt,        % 边框倒角，f表示尖角，t表示倒角，顺序是第一个字母表示右上角，顺时针
} 

framesep 边框与代码的距离

代码不会移动，动的是边框。

\lstset{
    framesep           = 6em,              % 边框与代码的距离
} 

\lstset{
    framesep           = 6em,              % 边框与代码的距离
} 

framexleftmargin/framexrightmargin/frameytopmargin/frameybottommargin 边框与代码距离

\lstset{
    framexleftmargin    = -2em,           % 左边框与代码距离
    framexrightmargin   = -5em,           % 右边框与代码距离
    framexbottommargin  = 2em,            % 下边框与代码距离
    framextopmargin     = 2em,            % 上边框与代码距离
} 

\lstset{
    framexleftmargin    = 1em,           % 左边框与代码距离
    framexrightmargin   = 1em,           % 右边框与代码距离
    framexbottommargin  = 0em,            % 下边框与代码距离
    framextopmargin     = 0em,            % 上边框与代码距离
} 

breaklines 强制换行

设置代码超长时自动换行：

\lstset{
    breaklines         = false,           % 不换行
} 

\lstset{
    breaklines         = true,           % 不换行
} 

numberstyle/keywordstyle/identifierstyle/commentstyle/commentstyle 行号、关键字、标识符、注释的样式

\definecolor{listing-background}{HTML}{F7F7F7}
\definecolor{listing-rule}{HTML}{B3B2B3}
\definecolor{listing-numbers}{HTML}{B3B2B3}
\definecolor{listing-text-color}{HTML}{000000}
\definecolor{listing-keyword}{HTML}{435489}
\definecolor{listing-identifier}{HTML}{435489}
\definecolor{listing-string}{HTML}{00999A}
\definecolor{listing-comment}{HTML}{8E8E8E}
\definecolor{listing-javadoc-comment}{HTML}{006CA9}

\lstset{
    numberstyle         = \color{listing-numbers},      % 行号颜色
    keywordstyle        = \color{listing-keyword},      % 关键字颜色
    identifierstyle     = \color{listing-identifier},   % 变量颜色
    commentstyle        = \color{listing-comment},      % 注释颜色
} 

Markdown 的简便性是 LaTeX 无法替代的，LaTeX 对排版的精准控制能力又是 Markdown 无法比拟的。一直在寻找一种能够将 Markdown 优雅地转换成 PDF 的解决方案，虽然早就听说也使用过 Pandoc 这把瑞士军刀，但是它太过强大，以致于一直都没用明白。只会简单的转换命令，但是实际效果并不好，最近学会了使用 LaTeX 模板的功能，这才让我眼前一亮，这才是我想要的结果。

效果演示

基础环境配置

Markdown 生成 PDF 主要需要使用 Pandoc 和 LaTeX 两个工具，具体安装方式如下：

Pandoc 的安装

Pandoc 是由 John MacFarlane 开发的标记语言转换工具，可实现不同标记语言间的格式转换。

• Windows 下的安装：

  • 下载安装包直接安装即可
  • 如果安装了 Chocolate：choco install pandoc
  • 如果安装了 winget：winget install pandoc

• Linux/FreeBSD下的安装：

  • Pandoc 已经包含在大部分 Linux 发行版的官方仓库中，直接使用诸如apt/dnf/yum/pacman之类的安装工具直接安装即可

• macOS 下的安装：

  • brew install pandoc

详细的安装说明参见：官方安装文档

LaTeX 的安装

LaTeX 工具，建议安装 texlive。

• Windows 下的安装：
  • 参考该文章下载完整 texlive，注意安装后需要再安装 cjk，cjk-fonts 等相关 package
• Linux/FreeBSD下的安装：
  • 使用 apt/dnf/yum/pacman/pkg 等安装工具安装 texlive、texlive-latex 等相关软件包
• macOS 下的安装：
  • 使用 HomeBrew 安装 texlive 即可

模板配置

配置 Pandoc 模板

为保证生成的 pdf 格式（自动插入封面、目录页、页眉页脚等信息），在本地环境中安装模板，具体步骤是：

• 下载MPPL: Markdown to PDF with Pandoc via Latex仓库
• 将template/mppl.latex拷贝到*/pandoc/templates目录下
  • Window 下：C:/Users/USERNAME/AppData/Roaming/pandoc/templates，如果Roaming没有pandoc目录，请手动创建！
  • Linux/FreeBSD/MacOS：~/.pandoc/templates/

配置 LaTeX 模板

模板定制主要修改模板最前面的模板基础配置相关内容，主要可修改的包括：

• 公司和组织，目前默认是"MPPL"
• 正文缩进，目前默认是 2em（2 个中文字符，4 个英文字符）
• 主要中文字体和英文字体：目前都是微软雅黑
• 页眉、页脚展示内容，目前是：
  • 左页眉：title
  • 右页眉：“企业机密 - 禁止外传”
  • 左页脚：company
  • 右页脚：页码

字体设置

目前页面默认的字体是微软雅黑，对于非 Windows 系统，可能不存在该字体，则有以下两种解决方案：

1. 手工安装微软雅黑字体（需要 msyh,msyhbd 两个文件）
2. 修改为其他字体，如苹方、文泉驿等

若需要多个团队共同使用，建议采用方案一。

如何生成 PDF

PDF 文件指定 metadata 信息

在每个 Markdown 最前面增加以下主要 metadata 信息，metadata 内容开始行内容为三个“-”，结束行为三个“.”，示例如下：

title: "MPPL"
version: "0.1"
subtitle: "Markdown to PDF with Pandoc via LaTeX"
date: "2022-08"
author: "Dominic"
company: COMPANYNAME
file-code: COMPANY-DEPARTMENT-00000000
logo: true
logo-url: ./img/logo.png
history:
  - version: V0.1
    author: Dominic
    date: 2022-08-19
    desc: 创建文档

其他可选配置项目如下：

• header-left: 左页眉
• header-right: 右页眉
• footer-left: 左页脚
• footer-right: 右页脚
• CJKmainfont: 主要中文字体
• mainfont: 主要字体
• lot: 是否创建表格目录
• lof: 是否创建图片目录

可选配置项中，建议除了 subtitle 外，全部在模板中定制，不在 Markdown 文件中定制

Markdown 其他编写要求

Pandoc 默认使用的 pandoc_markdown 格式，为避免 Markdown 转 pdf 格式异常，在编写 Markdown 的时候有几个原则要求：

• 每个标题前后都必须有空行
• 每个表格前后都必须有空行
• 每个代码块前后收必须有空行
• 每个列表前后必须有空行

总之，不同文本类型之间都要有空行。

生成 PDF 文件

pandoc --listings --pdf-engine=xelatex --template=mppl.latex README.md -o README.pdf

摆脱命令行，优雅的 VSCode 书写转换方案

VSCode 与插件安装

打开 VSCode 编辑器，在插件页搜索 markdown-preview-enhanced，接着点击 Install 按钮。详情参考VS Code 安装 MPE。

Markdown Preview Enhanced 以下简称 MPE

使用 VSCode 书写 Markdown

新建文件以.md为后缀即可开始编辑 Markdown 文件，使用 MPE 实时预览与导出。

配置 MPE 使用 Pandoc 导出

右击 MPE 的预览区域，可以看到 MPE 提供多种导出 PDF 的方案，如使用 Chrome 的 Puppeteer 导出，Prince 导出，Pandoc 导出等等。

在未使用 Pandoc 前，我也一直使用 MPE 提供的 Chrome 方式导出，但是导出的 PDF 排版总是不尽如意。现在介绍如何使用 Pandoc 方式导出。

创建 PDF 文档，你需要在 markdown 文件中的 front-matter 里声明 pdf_document 的输出类型：

---
output:
  pdf_document:
    latex_engine: xelatex
    pandoc_args: [--template=mppl.latex,--listings]
---

• 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 文件。

常见问题解决

LaTeX 相关错误

VSCode 导出出错时报错信息较短，并且常常不知道具体报错原因及位置，因为是 LaTeX 转换成 PDF 的过程中出现的错误。报错位置是 LaTeX 中间源码的位置，而不是 VSCode 中的位置。这时候我常用的方法是先将 Markdown 转为 LaTeX，然后再转为 PDF，在 LaTeX 编辑器里就可以看到错误位置了。

比如下面这个错误，我们能看到一些报错信息cant use \spacefactor in math mode，但是并不知道具体哪里的错误。从信息里可以看出和\LaTex有关，大概能推测出是使用了这个命令，因为文章里使用了这个命令的地方只有一处。但是如果有其他的错误，就很难确定了。

Markdown 转换 LaTeX

这里还是以模板仓库的README.md为例，当然这个文件是可以正常转换 PDF 的，不会报错。这里只是拿README.md做一个如何使用命令的演示。

pandoc --listings --template=mppl.latex -s README.md -o README.tex

LaTeX 编辑器打开，以 TexStudio 为例

打开README.tex文件，编译：

我们可以快速的定位到问题出现的位置，只要搜索相关问题即可。

\LaTeX{} 这个宏不能用在数学模式下。但是因为我在 Markdown 里必须使用美元符号$$才能表示 LaTeX 环境，才能正确输出 LaTeX 符号，而 Markdown 转换成 LaTeX 源码时，这个宏就会被包裹在数学环境里，就会报错。如果我想在 PDF 里显示这个符号，那就在 Markdown 里不使用美元符号$$，而是直接输入\LaTeX{}即可，再导出 PDF 时就不会报错。