作者：Yihui Xie
译者：郑宝童
日期：2021.05.28

4.1 YAML options

For most types of output formats, you can customize the syntax highlighting styles using the highlight option of the specific format. Currently, the possible styles are default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, and breezedark. For example, you can choose the tango style for the gitbook format:

对于大多数类型的输出格式，您可以使用特定格式的突出显示的选项 highlight 自定义语法突出显示样式。目前，用的风格是default, tango, pygings, kate, monochrome, espresso, zenburn, haddock和breezedark。例如，你可以选择tango 风格的gitbook格式

  1. ---
  2. output:
  3.   bookdown::gitbook:
  4.     highlight: tango
  5. ---

For HTML output formats, you are most likely to use the css option to provide your own CSS stylesheets to customize the appearance of HTML elements. There is an option includes that applies to more formats, including HTML and LaTeX. The includes option allows you to insert arbitrary custom content before and/or after the body of the output. It has three sub-options: in_header, before_body, and after_body. You need to know the basic structure of an HTML or LaTeX document to understand these options. The source of an HTML document looks like this:

对于HTML输出格式，您最有可能使用css选项来提供您自己的css样式表来定制HTML元素的外观。有一个选项includes 适用于更多的格式，包括HTML和LaTeX。include选项允许您在输出正文之前和/或之后插入任意自定义内容。它有三个子选项:in_header、before_body和after_body。要理解这些选项，您需要了解HTML或LaTeX文档的基本结构。HTML文档的源代码是这样的:

  1. <html>
  3.   <head>
  4.   <!-- head content here, e.g. CSS and JS -->
  5.   </head>
  7.   <body>
  8.   <!-- body content here -->
  9.   </body>
  10. </html>

The in_header option takes a file path and inserts it into the <head> tag. The before_body file will be inserted right below the opening <body> tag, and after_body is inserted before the closing tag </body>. A LaTeX source document has a similar structure:

in_header选项接受一个文件路径，并将其插入<head>标签中。before_body文件将被插入到开始标签<body>的正下方，after_body文件被插入到结束标签</body>的前面。
LaTeX源文档具有类似的结构:

  1. \documentclass{book}
  2. % LaTeX preamble
  3. % insert in_header here
  4. \begin{document}
  5. % insert before_body here
  6. % body content here
  7. % insert after_body here
  8. \end{document}

The includes option is very useful and flexible. For HTML output, it means you can insert arbitrary HTML code into the output. For example, when you have LaTeX math expressions rendered via the MathJax library in the HTML output, and want the equation numbers to be displayed on the left (default is on the right), you can create a text file that contains the following code:

include 选项非常有用和灵活。对于HTML输出，这意味着您可以在输出中插入任意的HTML代码。例如，当你在HTML输出中通过MathJax库呈现LaTeX数学表达式，并希望等式数字显示在左边(默认是在右边)，你可以创建一个包含以下代码的文本文件:

  1. <script type="text/x-mathjax-config">
  2. MathJax.Hub.Config({
  3.   TeX: { TagSide: "left" }
  4. });
  5. </script>

Let’s assume the file is named mathjax-number.html, and it is in the root directory of your book (the directory that contains all your Rmd files). You can insert this file into the HTML head via the in_header option, e.g.,

让我们假设该文件名为mathjax-number.html，它位于您的书的根目录(包含所有Rmd文件的目录)。你可以通过in_header选项把这个文件插入到HTML头中，例如，

  1. ---
  2. output:
  3.   bookdown::gitbook:
  4.     includes:
  5.       in_header: mathjax-number.html
  6. ---

Another example is to enable comments or discussions on your HTML pages. There are several possibilities, such as Disqus (https://disqus.com) or Hypothesis (https://hypothes.is). These services can be easily embedded in your HTML book via the includes option (see Section 5.5 for details).

另一个例子是在HTML页面上启用注释或讨论。有几种可能性，如 Disqus (https://disqus.com) or Hypothesis (https://hypothes.is)。这些服务可以很容易地通过includes选项嵌入到你的HTML书中(详情见 5.5 节)。

Similarly, if you are familiar with LaTeX, you can add arbitrary LaTeX code to the preamble. That means you can use any LaTeX packages and set up any package options for your book. For example, this book used the in_header option to use a few more LaTeX packages like booktabs (for better-looking tables) and longtable (for tables that span across multiple pages), and applied a fix to an XeLaTeX problem that links on graphics do not work:

类似地，如果您熟悉LaTeX，则可以在序言中添加任意LaTeX代码。这意味着您可以使用任何LaTeX软件包，并为您的书设置任何软件包选项。例如，本书使用了in_header选项来使用更多的LaTeX包，比如booktabs(用于展示更美观的表)和longtable(用于展示跨多个页面的表)，并修复了一个XeLaTeX问题（即图形上的链接不能用）:

  1. \usepackage{booktabs}
  2. \usepackage{longtable}
  3. \ifxetex
  4.   \usepackage{letltxmacro}
  5.   \setlength{\XeTeXLinkMargin}{1pt}
  6.   \LetLtxMacro\SavedIncludeGraphics\includegraphics
  7.   \def\includegraphics#1#{% #1 catches optional stuff (star/opt. arg.)
  8.     \IncludeGraphicsAux{#1}%
  9.   }%
  10.   \newcommand*{\IncludeGraphicsAux}[2]{%
  11.     \XeTeXLinkBox{%
  12.       \SavedIncludeGraphics#1{#2}%
  13.     }%
  14.   }%
  15. \fi

The above LaTeX code is saved in a file preamble.tex, and the YAML metadata looks like this:

上面的LaTeX代码保存在文件pream .tex中，YAML元数据如下所示:

  1. ---
  2. output:
  3.   bookdown::pdf_book:
  4.     includes:
  5.       in_header: preamble.tex
  6. ---