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:
---
output:
bookdown::gitbook:
highlight: tango
---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>
<head>
<!-- head content here, e.g. CSS and JS -->
</head>
<body>
<!-- body content here -->
</body>
</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:
\documentclass{book}
% LaTeX preamble
% insert in_header here
\begin{document}
% insert before_body here
% body content here
% insert after_body here
\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:
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
TeX: { TagSide: "left" }
});
</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.,
---
output:
bookdown::gitbook:
includes:
in_header: mathjax-number.html
---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).
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:
\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}%
}%
}%
\fiThe above LaTeX code is saved in a file preamble.tex, and the YAML metadata looks like this:
---
output:
bookdown::pdf_book:
includes:
in_header: preamble.tex
---