PDF基础

概述

使用pdf格式创建PDF输出。例如：

---
title: "我的文档"
format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true
---

这个例子展示了一些可用于PDF输出的选项。本文详细介绍了这些选项以及其他选项。有关所有可用选项的完整列表，请参阅PDF 格式参考。

如果你想生成原始的LaTeX输出（一个.tex文件）而不是PDF，这里记录的所有选项仍然可用（有关更多详细信息，请参阅下面的LaTeX输出部分）。

Note

请注意，虽然我们将在此处专门讨论使用LaTeX创建PDF，但Pandoc还支持使用ConTeXt、roff ms或HTML（通过wkhtmltopdf）创建PDF。有关更多详细信息，请参阅Pandoc文档中的创建PDF。

先决条件

为了创建PDF，你需要安装一个最新的TeX发行版。我们推荐使用基于TexLive的TinyTeX，你可以使用以下命令进行安装：

终端
quarto install tinytex

有关使用其他TeX发行版和PDF编译引擎的详细信息，请参阅PDF引擎一文。

文档类

Quarto默认使用KOMA Script文档类来生成PDF文档和书籍。KOMA-Script类是标准类的即插即用替代品，强调排版和多功能性。

对于PDF文档，这导致默认设置以下Pandoc选项：

format:
  pdf:
    documentclass: scrartcl
    papersize: letter

你可以将documentclass设置为标准的article、report或book类，分别对应KOMA Script的scrartcl、scrreprt和scrbook，或者设置为任何由你安装的LaTeX包提供的其他类。

Note

将documentclass设置为book或scrbook将自动处理许多将PDF打印和装订成实体书籍的常见需求（即章节从奇数页开始，交替的页边距大小等）。

有关自定义LaTeX文档选项的更多详细信息，请参阅下面的输出选项部分。

目录

使用 toc 选项可以在输出文档中包含一个自动生成的目录。使用 toc-depth 选项可以指定在目录中包含的章节级别数量。默认值是 3（这意味着一级、二级和三级标题将列在目录中）。例如：

toc: true
toc-depth: 2

你可以使用 toc-title 选项自定义目录的标题：

toc-title: Contents

如果你想从目录中排除某个标题，可以为其添加 .unnumbered 和 .unlisted 类：

### More Options {.unnumbered .unlisted}

章节编号

使用 number-sections 选项为输出文档中的章节标题添加编号。例如：

number-sections: true

使用 number-depth 选项指定要添加编号的标题的最深层次（默认情况下所有标题都会编号）。例如：

number-depth: 3

要排除单个标题的编号，请为其添加 .unnumbered 类：

### 更多选项 {.unnumbered}

语法高亮

Pandoc 会自动高亮显示带有语言名称标记的 围栏代码块 中的语法。例如：

```python
1 + 1
```

Pandoc 可以为超过 140 种不同的语言提供语法高亮（查看 quarto pandoc --list-highlight-languages 的输出以获取所有支持的语言列表）。如果你想为不支持的语言提供高亮代码块的外观，只需使用 default 作为语言名称。

你可以使用 highlight-style 并指定一个支持的主题来指定代码高亮样式。支持的主题包括：arrow、pygments、tango、espresso、zenburn、kate、monochrome、breezedark、haddock、atom-one、ayu、breeze、dracula、github、gruvbox、monokai、nord、oblivion、printing、radical、solarized 和 vim。

例如：

highlight-style: github

高亮主题可以提供单一的高亮定义，或者提供两种定义，一种针对浅色背景优化，另一种针对深色背景优化。当可用时，Quarto 会根据代码块背景颜色的深浅自动选择合适的样式。你始终可以选择指定完整名称（例如 atom-one-dark）来绕过这种自动行为。

默认情况下，代码使用 arrow 主题进行高亮，该主题针对可访问性进行了优化。以下是 arrow 浅色和深色主题的示例：

展示 Arrow 浅色主题的代码块。

展示 Arrow 深色主题的代码块。

代码注释

你可以在代码块和可执行代码单元格中为代码行添加注释。详见代码注释。

输出选项

有许多选项可用于自定义PDF输出，包括：

  • 指定文档类及其选项

  • 包含图表和表格的列表

  • 使用geometry和hyperref包

  • 许多用于自定义字体和颜色的选项。

例如，这里我们使用其中的一些选项：

---
title: "我的文档"
format: 
  pdf: 
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    fontfamily: libertinus
    colorlinks: true
---

有关所有可用选项的文档，请参阅Pandoc文档中的LaTeX元数据变量。

引用

在创建PDF时，你可以选择使用基于citeproc的默认Pandoc 引用处理，或者选择使用natbib或BibLaTeX。这可以通过cite-method选项来控制。例如：

format:
  pdf: 
    cite-method: biblatex

默认情况下使用citeproc（Pandoc内置的引用处理器）。

有关引用语法、可用参考文献格式等的更多详细信息，请参阅关于使用引用与Quarto的主文章。

选项

在使用natbib或biblatex时，你可以指定以下附加选项来影响参考文献的渲染方式：

选项 描述
biblatexoptions biblatex的选项列表
natbiboptions natbib的选项列表
biblio-title 参考文献的标题
biblio-style 参考文献的样式

原始LaTeX

在创建PDF文档时，Pandoc允许在Markdown中混合使用原始LaTeX指令。例如：

\begin{tabular}{|l|l|}\hline
年龄 & 频率 \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}

原始LaTeX命令将被保留并原样传递给LaTeX写入器。

Warning

虽然使用原始LaTeX非常方便，但在渲染为其他格式（如HTML和MS Word）时，原始LaTeX会被忽略。如果你计划渲染为其他格式，那么上面的例子最好使用原生的Markdown表格编写。

在某些情况下，原始LaTeX将需要额外的LaTeX包。下面的LaTeX包含部分描述了如何在文档中包含这些包的\usepackage命令。

LaTeX包含

如果你想在你的文档中包含来自另一个文件的额外内容，可以使用 include-in-* 选项：

选项 描述
include-in-header 在头部末尾逐字包含 文件 的内容。例如，这可以用于在 HTML 文档中包含特殊的 CSS 或 JavaScript，或在 LaTeX 前言中注入命令。
include-before-body 在文档主体开始处逐字包含 文件 的内容（例如，在 HTML 中的 <body> 标签之后，或在 LaTeX 中的 \begin{document} 命令之后）。这可以用于在 HTML 文档中包含导航栏或横幅。
include-after-body 在文档主体末尾逐字包含 文件 的内容（在 HTML 中的 </body> 标签之前，或在 LaTeX 中的 \end{document} 命令之前）。

你可以直接为每个选项指定单个文件或多个文件，或者使用 file: 子键。要在 YAML 头部包含原始内容，请使用 text 子键。当使用 text: 时，在 text: 后添加 | 字符以指示该值是多行字符串。如果你省略了 file: 或 text:，Quarto 会假设你提供的是文件。

例如：

format:
  pdf:
    include-in-header:
      - text: |
          \usepackage{eplain}
          \usepackage{easy-todo}
      - file: packages.tex
      - macros.tex

任何使用包含指定的但你本地尚未安装的包，将在文档渲染期间由Quarto安装。

LaTeX输出

如果你希望Quarto生成LaTeX文件（.tex）而不是PDF（例如，如果你想自己处理PDF），有两种方法可以实现：

  1. 使用latex格式而不是pdf格式。例如：

    format:
  latex:
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true

    请注意，上述所有PDF格式选项也适用于latex格式。

  2. 结合使用pdf格式和keep-tex选项。例如：

    format:
  pdf:
    documentclass: report
    keep-tex: true

    此技术将生成一个用于预览的PDF文件，同时还会创建一个与之相邻的.tex文件，您可以对其进行后续处理。

这两种技术还会生成所有LaTeX临时文件，包括.bbl文件等，这些文件可能是希望获取LaTeX源文件的出版商所必需的。

Unicode字符

默认情况下，Quarto使用xelatex引擎从LaTeX生成PDF。xelatex原生支持unicode字符，但可能需要一些定制才能正确排版特定的unicode字符。特别是，重要的是使用支持文档中所使用字符的字体。要识别系统中支持特定语言字符的字体，可以使用以下命令：

Terminal
fc-list :lang=<lang>

例如，要查看支持日语字符的字体列表，请使用：

Terminal
fc-list :lang=ja

从列表中选择一个字体名称，并将其作为文档的主字体，例如：

---
title: Unicode测试
format: pdf
mainfont: "Hiragino Sans GB"
---

## 测试文档

青黑體簡體中文,ヒラギノ角