PDF 文档

概览

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

  1. ---
  2. title: "Habits"
  3. author: John Doe
  4. date: March 22, 2005
  5. output: pdf_document
  6. ---

输出路径

你可以通过 path 来定义文档的输出路径。例如： 

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     path: /Exports/Habits.pdf
  6. ---

如果 path 没有被定义，那么 PDF 将会在相同的文件夹下生成。

目录

你可以通过 toc 选项来添加目录，以及 toc_depth 来控制目录的等级。例如： 

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     toc: true
  6.     toc_depth: 2
  7. ---

如果 toc_depth 没有被定义，那么默认 3 将会被使用。（意味着等级 1，2，已经 3 的标题将会被列举在目录中）。

注意： 这个 TOC 和用 Markdown Preview Enhanced <!-- toc --> 生成的是不同的。

You can add section numbering to headers using the number_sections option:

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     toc: true
  6.     number_sections: true
  7. ---

语法高亮

highlight 选项定义了高亮的样式。支持的样式包括 “default”，“tango”，“pygments”，“kate”，“monochrome”，“espresso”，“zenburn”，以及 “haddock” （设置 null 来禁用语法高亮）：

例如： 

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     highlight: tango
  6. ---

LaTeX 选项

你可以用 YAML metadata 来定义你的 LaTeX 模版（注意这些选项不是出现在 output 部分下的，但是出现在最上层）。例如

  1. ---
  2. title: "Crop Analysis Q3 2013"
  3. output: pdf_document
  4. fontsize: 11pt
  5. geometry: margin=1in
  6. ---

支持的 metadata 变量包括：

变量 描述
papersize 纸张大小，e.g. letter, A4
lang Document language code
fontsize 字体大小 (e.g. 10pt, 11pt, 12pt)
documentclass LaTeX document class (e.g. article)
classoption Option for documentclass (e.g. oneside); may be repeated
geometry Options for geometry class (e.g. margin=1in); may be repeated
linkcolor, urlcolor, citecolor Color for internal, external, and citation links (red, green, magenta, cyan, blue, black)
thanks specifies contents of acknowledgments footnote after document title.

更多的可用变量请查看 这里.

LaTeX Packages for Citations

By default, citations are processed through pandoc-citeproc, which works for all output formats. For PDF output, sometimes it is better to use LaTeX packages to process citations, such as natbib or biblatex. To use one of these packages, just set the option citation_package to be natbib or biblatex, e.g. 

  1. ---
  2. output:
  3.   pdf_document:
  4.     citation_package: natbib
  5. ---

高级自定义

LaTeX Engine

默认情况下 PDF 文档由 pdflatex 生成。你可以用 latex_engine 选项来定义你想用的引擎。支持的引擎有 pdflatex，xelatex，以及 lualatex。例如： 

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     latex_engine: xelatex
  6. ---

Include

You can do more advanced customization of PDF output by including additional LaTeX directives and/or content or by replacing the core pandoc template entirely. To include content in the document header or before/after the document body you use the includes option as follows: 

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     includes:
  6.       in_header: header.tex
  7.       before_body: doc_prefix.tex
  8.       after_body: doc_suffix.tex
  9. ---

自定义模版

你可以替代 pandoc 的基础模版通过 template 选项：

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     template: quarterly_report.tex
  6. ---

请参考 pandoc 模版 文档了解更多关于模版的信息。你还可以学习 default LaTeX template 作为一个例子。

Pandoc Arguments

If there are pandoc features you want to use that lack equivalents in the YAML options described above you can still use them by passing custom pandoc_args. For example: 

  1. ---
  2. title: "Habits"
  3. output:
  4.   pdf_document:
  5.     pandoc_args: [
  6.       "--no-tex-ligatures"
  7.     ]
  8. ---

Shared Options

If you want to specify a set of default options to be shared by multiple documents within a directory you can include a file named _output.yaml within the directory. Note that no YAML delimeters or enclosing output object are used in this file. For example:

_output.yaml

  1. pdf_document:
  2.   toc: true
  3.   highlight: zenburn

All documents located in the same directory as _output.yaml will inherit it’s options. Options defined explicitly within documents will override those specified in the shared options file.