bookdown: Escritura de libros y documentos técnicos con R Markdown

4.1 Opciones YAML

Para la mayoría de los tipos de formatos de salida, puede personalizar los estilos de resaltado de sintaxis utilizando la opción highlight del formato específico. En la actualidad, los estilos posibles son default, tango, pygments, kate, monochrome, espresso, zenburn, and haddock. Por ejemplo, se puede elegir el estilo tango para el formato de gitbook:

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

Para formatos de salida HTML, es preferible usar la opción css con el fin de proporcionar sus propias hojas de estilo CSS para personalizar la apariencia de los elementos HTML. Hay una opción includes que se aplica a más formatos, incluyendo HTML y LaTeX. La opción includes permite insertar contenido personalizado antes y/o después del cuerpo de salida. Tiene tres sub-opciones: in_header, before_body, y after_body. Es necesario conocer la estructura básica de un documento HTML o LaTeX para entender estas opciones. El código fuente de un documento HTML luce de la siguiente forma:

<html>
  
  <head>
  <!-- head content here, e.g. CSS and JS -->
  </head>
  
  <body>
  <!-- body content here -->
  </body>

</html>

La opción in_header toma una ruta de archivo y lo inserta en la etiqueta <head>. Se insertará el archivo before_body justo debajo de la apertura <body>, y after_body se inserta antes de la etiqueta de cierre </body>.

Un documento de origen LaTeX tiene una estructura similar:

\documentclass{book}

% LaTeX preamble
% insert in_header here

\begin{document}
% insert before_body here

% body content here

% insert after_body here
\end{document}

La opción includes es muy útil y flexible. Para la salida HTML, quiere decir que se puede insertar código HTML arbitrario a la salida. Por ejemplo, cuando se tienen expresiones matemáticas de LaTeX compiladas a través de la biblioteca MathJax en la salida HTML, y desea enumerar las ecuaciones en el entorno equation, puede crear un archivo de texto que contenga el siguiente código:

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

Asumiendo que el archivo se denomina mathjax-number.html, y que está en el directorio raíz de su libro (el directorio que contiene todos los archivos Rmd). Puede insertar este archivo en el encabezado del HTML a través de la opción in_header, por ejemplo,

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

Si se utiliza el formato de salida HTML html_book o gitbook en bookdown, esto ya se ha establecido en las plantillas HTML, por lo que no es realmente necesario insertar un archivo de este tipo en el encabezado HTML. Sólo es necesario que lo haga para otros formatos de salida HTML.

Del mismo modo, si usted está familiarizado con LaTeX, puede agregar código LaTeX arbitrariamente al preámbulo. Esto significa que puede utilizar cualquier paquete de LaTeX y configurar las opciones de cualquier paquete para su libro. Por ejemplo, este libro utiliza la opción in_header para utilizar unos pocas paquetes de LaTeX adicionales, tales como booktabs (para mejorar el aspecto de las tablas) y longtable (para las tablas que se extienden a través de múltiples páginas), y arreglar un problema XeLaTeX en el que el vínculo de los gráficos no funcionen:

\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

El código LaTeX anterior se guarda en un archivo preamble.tex, y los metadatos YAML se ven así:

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