4.1 YAML 选项

对于大多数类型的输出格式来说，你可以使用特定格式的 highlight 选项自定义语法高亮样式，可用的样式为 default、tango、pygments、kate、monochrome、espresso、zenburn、haddock 和 breezedark。例如，你可以为 gitbook 格式选择 tango 样式：

---
output:
  bookdown::gitbook:
    highlight: tango
---

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

<html>
  
  <head>
  <!-- 这里放置首部内容，例如 CSS 和 JS -->
  </head>
  
  <body>
  <!-- 这里放置正文内容 -->
  </body>

</html>

in_header 选项接受一个文件路径然后将文件内容插入到 <head> 标签之间。before_body 所指文件将会被插入到 <body> 标签的正下方，after_body 所指文件将会被插入到 </body> 标签之前。

一个 LaTeX 源文档有着相似的结构：

\documentclass{book}

% LaTeX 导言 (preamble)
% 这里插入 in_header

\begin{document}
% 这里插入 before_body

% 这里是正文内容

% 这里插入 after_body
\end{document}

includes 选项非常有用且使用灵活。对于 HTML 输出，它意味着你能够将任意 HTML 代码插入到输出中。例如，当你在 HTML 输出中通过 MathJax 库渲染 LaTeX 数学表达式，并希望方程编号显示在左侧（默认显示在右侧），你可以创建一个包含有以下代码的文本文件：

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

让我们假设文件名为 mathjax-number.html，并且它位于你的书籍的根目录下（包含有你的全部 Rmd 文件的目录）。你可以通过 in_header 选项将该文件插入到 HTML 首部，例如：

---
output:
  bookdown::gitbook:
    includes:
      in_header: mathjax-number.html
---

另一个例子是在 HTML 页面上启用评论区或讨论区。有这么几种可能的选择，例如：Disqus (https://disqus.com) 或 Hypothesis (https://hypothes.is)。这些服务可以通过 includes 选项轻松地嵌入到你的 HTML 书籍中（有关更多详细信息，请参阅第 5.5 节）。

类似地，如果你熟悉 LaTeX，则可以在导言 (preamble) 中添加任意 LaTeX 代码。这意味着你可以使用任何 LaTeX 软件包，并为书籍设置任何软件包选项。例如，本书通过 in_header 选项使用了更多的 LaTeX 软件包，如 booktabs（用于更美观的表格）和 longtable（用于跨多个页面的表格），并对图形环境中的链接不起作用的 XeLeTeX 问题进行了修复：

中文版还使用了 ctex 软件包以在 PDF 输出中渲染中文字符。

\usepackage{booktabs}
\usepackage{longtable}

\ifxetex
  \usepackage{letltxmacro}
  \setlength{\XeTeXLinkMargin}{1pt}
  \LetLtxMacro\SavedIncludeGraphics\includegraphics
  \def\includegraphics#1#{% #1 catches optional stuff (star/opt. arg.)
    \IncludeGraphicsAux{#1}%
  }%
  \newcommand*{\IncludeGraphicsAux}[2]{%
    \XeTeXLinkBox{%
      \SavedIncludeGraphics#1{#2}%
    }%
  }%
\fi

上述 LaTeX 代码保存在文件 preamble.tex 中，而书籍的 YAML 元数据如下所示：

---
output:
  bookdown::pdf_book:
    includes:
      in_header: preamble.tex
---