Escritura de libros con `bookdown`

Introducción

El paquete bookdown de R permite escribir libros empleando R Markdown de forma fácil. Sin preocuparse mucho por los detalles de composición se pueden crear libros en distintos formatos (HTML / PDF / Word / …). Además de permitir emplear las extensiones Markdown de Pandoc (notas al pie de página, tablas, citas, ecuaciones LaTeX, …), se pueden emplear extensiones markdown para libros (leyendas de figuras y tablas, numeración y referencias cruzadas de figuras / tablas / secciones / ecuaciones / teoremas / ejemplos / …, widgets HTML, …).

El libro se generará (de forma simultánea en los formatos deseados) a partir de una serie de documentos R Markdown, cada uno correspondiente a un capítulo. Ejemplos de este tipo de libros se tienen en https://bookdown.org (los libros de Hadley Advanced R y R packages, serían ejemplos con una versión “preliminar” de este paquete). Uno en castellano que utilizaremos como ejemplo es Prácticas de Simulación, disponible en el repositorio de GitHub rubenfcasal/simbook (Zip).

Requisitos

1. Disponer de una versión reciente de RStudio. Descargar la última versión si la versión actual es anterior a la 1.0.0.

2. Instalar el paquete bookdown de R:

   # stable version on CRAN
   install.packages('bookdown')
   # or development version on GitHub
   # devtools::install_github('rstudio/bookdown')

3. Para compilar los libros en pdf bookdown emplea XeLaTeX. En windows es recomendable instalar MiKTeX, o actualizarlo (ejecutando MiKTeX Update) si ya está instalado. En Mac OS X se puede instalar MacTeX y en Linux TeXLive.

Get started

La recomendación es seguir el libro de bookdown:

The easiest way for beginners to get started with writing a book with R Markdown and bookdown is through the demo bookdown-demo on GitHub:

1. Download the GitHub repository https://github.com/rstudio/bookdown-demo as a Zip file, then unzip it locally.
2. Open the bookdown-demo repository you downloaded in RStudio by clicking bookdown-demo.Rproj.
3. Open the R Markdown file index.Rmd and click the button Build Book on the Build tab of RStudio.

Now you should see the index page of this book demo in the RStudio Viewer. You may add or change the R Markdown files, and hit the Knit button again to preview the book. If you prefer not to use RStudio, you may also compile the book through the command line. See the next section for details.

Although you see quite a few files in the bookdown-demo example, most of them are not essential to a book. If you feel overwhelmed by the number of files, you can use this minimal example instead, which is essentially one file index.Rmd: https://github.com/yihui/bookdown-minimal. The bookdown-demo example contains some advanced settings that you may want to learn later, such as how to customize the LaTeX preamble, tweak the CSS, and build the book on GitHub, etc.

Primeros pasos

Al abrir el proyecto (bookdown-demo.Rproj) podemos compilar el libro ejecutando “Build Book” en la pestaña “Build”. Por defecto se generará el libro (en los distintos formatos) en la carpeta _book y al terminar se abrirá automáticamente la versión HTML.

Nota: Si se produce un error, eliminar manualmente el fichero book_filename.Rmd (o book_filename.md) para poder volver a compilar.

Posteriormente se pueden ir añadiendo (modificando o eliminando) los ficheros .Rmd correspondientes a los distintos capítulos (se numerarán automáticamente por orden alfabético)

Nota: Evitar espacios (y acentos) en los nombres de los ficheros de los capítulos.

Información sobre como emplear las extensiones markdown para libros está disponible en el libro de bookdown:

• Figuras

• Tablas

• Referencias: ecuaciones, teoremas, figuras, tablas, y secciones

• Citas

Nos puede interesar modificar el encabezado de index.Rmd y un par de archivos YAML de configuración.

--- 
title: "A Minimal Book Example"
author: "Yihui Xie"
date: "2021-02-15"
site: bookdown::bookdown_site
output: bookdown::gitbook
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
github-repo: rstudio/bookdown-demo
description: "This is a minimal example of using the bookdown package to write a book. The output format for this example is bookdown::gitbook."
---

---
output:
  bookdown::gitbook:
    lib_dir: "book_assets"
  bookdown::pdf_book:
    keep_tex: yes
---

bookdown::gitbook:
  css: style.css
  config:
    toc:
      before: |
        <li><a href="./">A Minimal Book Example</a></li>
      after: |
        <li><a href="https://github.com/rstudio/bookdown" target="blank">Published with bookdown</a></li>
    edit: https://github.com/rstudio/bookdown-demo/edit/master/%s
    download: ["pdf", "epub"]
bookdown::pdf_book:
  includes:
    in_header: preamble.tex
  latex_engine: xelatex
  citation_package: natbib
  keep_tex: yes
bookdown::epub_book: default

book_filename: "bookdown-demo"
language:
  ui:
    chapter_name: "Chapter "

book_filename: "SimulationR"
chapter_name: "Capítulo "

new_session: yes
output:
  bookdown::gitbook:
    split_by: "section"
    split_bib: no

Licencia

Es recomendable incluir una licencia, por ejemplo, en el libro de Prácticas de Simulación se consideró una licencia Creative Commons Reconocimiento-NoComercial-SinObraDerivada 4.0 Internacional (de forma preliminar…).

Publicación en la web

La “publicación” del libro web puede ser tan simple como subirlo a GitHub, aunque también bastaría con subir la carpeta de salida _book a cualquier servidor web.

Para poder emplear GitHub Pages habría que cambiar el directorio de salida en el archivo _bookdown.yml:

output_dir: "docs"

Después de generar el libro, crear un fichero .nojekyll (vacio) en el nuevo directorio docs (GitHub procesa los sitios web con Jekyll; e.g. enlace ), para lo que bastaría con ejecutar en la consola file.create('docs/.nojekyll'). Finalmente crear el correspondiente repositorio en GitHub, estableciendo en la configuración de “GitHub Pages” la opción de “Source” como “master branch /docs folder” (p.e. siguiendo estos pasos).

Para ir añadiendo contenido a un sitio en GitHub, se puede emplear por ejemplo RStudio (e.g. R packages by Hadley Wickham) o instalar GitHub Desktop (lo que recomendaría en Windows…).

Más información y alternativas en el libro de bookdown.