6  Taller: colección de apuntes

En este capítulo, vamos a poner en práctica los conocimientos adquiridos para crear un documento de apuntes de clase, que también puede servir como cuaderno de laboratorio, cuaderno de prácticas o bitácora de experimentos.

Para ello, vamos combinar lo que ya sabemos acerca de los documentos y libros en Quarto junto con nuevas opciones de configuración y plantillas que abrirán nuevas e interesantes posibilidades de diseño. Por supuesto, con los conocimientos adicionales adecuados (no necesariamente muy avanzados), muchos usuarios serán capaces de adaptar y personalizar el diseño gráfico y la maquetación de sus documentos en PDF o LaTeX para ajustarlos a sus necesidades.

6.1 Opciones de diseño del documento

Además de las numerosas opciones que hemos explorado para ajustar el comportamiento de muchos elementos de nuestros documentos, Quarto todavía nos reserva muchas más alternativas para controlar el diseño de la página y la distribución de su contenido de forma que:

En este taller nos centramos en la generación de salida en HTML. Por defecto, en un documento HTML producido con Quarto tenemos un diseño estándar del espacio de la página en tres columnas:

  • La columna central, body más ancha, para el contenido principal de la página.
  • La columna izquierda, sidebar (barra lateral), que se suele emplear en los libros para la tabla de contenidos desplegable que permite navegar por la colección de documentos.
  • La columna derecha, margin, que se suele utilizar para mostrar la tabla de contenidos del documento o capítulo que aparece en el body en ese momento, junto con otros enlaces a contenido adicional (e.g. enlace al código fuente, a la web de la organización o editorial, etc.).

Por supuesto, las dimensiones de estas tres columnas son totalmente personalizables.

6.1.1 Contenido principal

Si no especificamos ninguna variación en la configuración, el documento de Quarto muestra los elementos ocupando todo el ancho de la columna central (document body).

Si queremos que el contenido sobrepase un poco los límites de ese espacio central, pero sin llegar a ocupar todo el ancho de la pantalla, podemos usar una nueva sección div HTML con un estilo específico:

:::{.column-body-outset}
Outset content...
:::

Para ampliar aún mas el ancho de presentación, pero dejando cierto margen de espacio respecto a ambos bordes de la pantalla se puede usar en su lugar el estilo {.column-page}. Por último, si realmente queremos ocupar todo el ancho de la pantalla (sin dejar margen a ambos lados) se puede usar el estilo {.column-screen}. Estas opciones de diseño también son aplicables a la configuración de los bloques de código ejecutable. Veamos un ejemplo:

```{r}
#| column: page

knitr::kable(
  mtcars[1:6, 1:10]
)
```
mpg cyl disp hp drat wt qsec vs am gear
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3
Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3

Por último, las opciones de estilo {.column-screen-inset} o {.column-screen-inset-shaded} dan una apariencia de ocupar el ancho de la pantalla al completo pero dejando un ligero margen en los bordes (con sombreado, en el segundo caso).

6.1.2 Contenido en los márgenes

El estilo {.column-margin} permite ubicar en la columna derecha de la página cualquier elemento, ya sea un texto, una figura o gráfica, una tabla, ecuación, etc.

::: {.column-margin}
![A margin image](image.png)
:::

Veamos un ejemplo aplicado a una ecuación que se muestra al margen:

We know from the first fundamental theorem of calculus that for \(x\) in \([a, b]\):

\[\frac{d}{dx}\left( \int_{a}^{x} f(u)\,du\right)=f(x).\]

Ahora con una figura al margen:

```{r}
#| label: fig-mtcars
#| fig-cap: "MPG vs horsepower, colored by transmission."
#| column: margin

library(ggplot2)
mtcars2 <- mtcars
mtcars2$am <- factor(
  mtcars$am, labels = c('automatic', 'manual')
)
ggplot(mtcars2, aes(hp, mpg, color = am)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess") +
  theme(legend.position = 'bottom')
```
Figura 6.1: MPG vs horsepower, colored by transmission.

Por último, probamos con una tabla ubicada en el margen:

```{r}
#| column: margin

knitr::kable(
  mtcars[1:6, 1:3]
)
```
mpg cyl disp
Mazda RX4 21.0 6 160
Mazda RX4 Wag 21.0 6 160
Datsun 710 22.8 4 108
Hornet 4 Drive 21.4 6 258
Hornet Sportabout 18.7 8 360
Valiant 18.1 6 225

También es posible especificar opciones individualizadas para cada elemento cuando un bloque de código genera varios resultados.

Se recomienda consultar la [guía completa de diseño de los artículos] de Quarto para explorar más opciones adicionales de configuración.

6.1.3 Notas al margen y citas bibliográficas

Si se añaden las siguientes opciones en la cabecera del documento (o de la salida HTML del proyecto global), se modifica la ubicación de las notas al pie y las citas bibliográficas, que pasan a mostrarse en el margen derecho del documento, a la misma altura de la llamada o cita en el texto principal, siguiendo los principios de diseño de los documentos de Tufte:

reference-location: margin
citation-location: margin

Adicionalmente, también podemos poner notas puntuales (no numeradas) en el margen del documento con el estilo de párrafo {.aside}:

[This is a span that has the class `aside` which places 
it in the margin without a footnote number.]{.aside}

This is a span that has the class aside which places it in the margin without a footnote number.

6.2 Anotaciones en bloques de código

Una característica muy útil para la creación de documentació y tutoriales es la de anotar las líneas dentro de los bloques de código ejecutable. Veamos un ejemplo:

```r
#| label: demo-code-annotation
#| message: false
#| output: false
library(tidyverse)
library(palmerpenguins)
penguins |>                                      # <1>
  mutate(                                        # <2>
    bill_ratio = bill_depth_mm / bill_length_mm, # <2>
    bill_area  = bill_depth_mm * bill_length_mm  # <2>
  )                                              # <2>
```
1. Take `penguins`, and then,
2. add new columns for the bill ratio and bill area.

Que produce el siguiente resultado:

library(tidyverse)
library(palmerpenguins)
1penguins |>
2  mutate(
    bill_ratio = bill_depth_mm / bill_length_mm,
    bill_area  = bill_depth_mm * bill_length_mm
  )
1
Take penguins, and then,
2
add new columns for the bill ratio and bill area.

Se pueden utilizar más opciones de configuración para controlar cómo se muestran las anotaciones de código (al hacer click sobre la anotación, al pasar el ratón por encima o la opción por defecto que hemos visto).

6.3 Configuración del proyecto

6.3.1 Opciones globales

6.3.2 Idioma de los documentos

Una opción de configuración muy interesante para nuestros documentos y proyectos es la de especificar el idioma de los mismos. Por defecto, los documentos de Quarto se generan en inglés. Si embargo, varias herramientas, incluyendo paquetes LaTeX para localización del contenido y división de palabraas, así como Pandoc y el propio Quarto pueden traducir muchas etiquetas automáticamente (“Figura”, “Tabla”, “Ecuación”, etc.) al idioma adecuado.

Para ello, tenemos que proporcionar un nuevo valor para la opción lang en la cabecera de nuestro documento o en el archivo de configuración _quarto.yml de nuestro proyecto:

---
title: "Mi documento en castellano"
lang: es    
---

También es posible ofrecer traducciones personalizadas para etiquetas y campos estándar del documento o proyecto, de forma que se ajuste perfectamente a nuestras directrices de estilo o las de nuestra organización. Para más detalles, consulta la siguiente guía:

En particular, si vamos a proporcionar una larga lista de traducciones alternativas conviene codificarlas en un fichero independiente y pasarlo a las opciones de configuración del documento o proyecto:

language: custom_translations.yml

Podemos llegar incluso al extremo de tener traducciones personalizadas para diferentes idiomas, que se usan en función del valor que pasemos a la opción de selección de idioma lang.

Respecto al soporte multilenguaje simultáneo (el mismo documento en varios idiomas), dicha característica todavía no está soportada en Quarto. Sin embargo, un paquete de reciente creación en la comunidad ROpenSci llamado babledown (aún en fase expermental), permite gestionar estas versiones multidioma de forma simultánea (mostrando en un idioma enlaces al resto de idiomas disponibles). Más aún, el objetivo principal de este paquete es ofrecer una interfaz para el servicio de traducción automática DeepL, de forma que se traduzcan automáticamente los textos de nuestros documentos a otros idiomas.

6.3.3 Enlaces a otros formatos

Cuando generamos un documento Quarto en múltiples formatos, de manera automática se debería generar en la parte superior derecha (o en algún punto de la columna a la derecha de la página) un enlace a las otras versiones disponibles de dicho documento. La figura Figura 6.2 muestra un ejemplo del enlace que aparece en la página:

Figura 6.2: Enlace a otra versión en PDF del documento creado con Quarto

Para que esto suceda, tenemos que declarar que se genere la salida del docoumento en varios formatos:

title: Sample Page
author: Sarah Connor
date: last-modified
toc: true
format: 
  html: default
  pdf: default
  ipynb: default

Las opciones anteriores generarían dos enlaces en la página HTML (el formato por defecto): uno para descargar la versión alternativa en PDF y otro para descargar la versión en formato notebook de Jupyter.

Se puede consultar la siguiente página de la guía de Quarto para descubrir más opciones de configuración, incluyendo cómo personalizar los textos de los enlaces o los formatos que se muestran para descarga:

Es importante saber que los proyectos de tipo book funcionan de una manera un tanto diferente, por ser un tipo de proyecto especial. En este caso, el enlace de descarga para versiones en otros formatos se pone junto al título del libro (en la parte superior izquierda) y se activa con la siguiente opción:

book:
  downloads: [pdf]

6.4 Ejercicio: personalizar el estilo gráfico del documento

Ahora, vamos a practicar con un ejemplo en el que se combinan varios aspectos que hemos estado tratando en este capítulo.

  1. Descarga este documento de ejemplo en tu equipo: Ejemplo apuntes Tufte.
  2. Crea un nuevo proyecto en RStudio, indicando como directorio de trabajo aquel en el que has guardado el ejemplo.
  3. Previsualiza el documento en su versión HTML. Comprueba que hay un enlace para descargar también la versión en PDF.
  4. Modifica algunos de los ejemplos para entender mejor cómo funcionan las opciones de configuración de los bloques de código ejecutables y los estilos gráficos aplicables al contenido en formato Markdown.
  5. Modifica las dimensiones de la columna central (document body), para reducir su anchua 50 píxeles.

Referencias adicionales para el ejercicio práctico

6.5 Personalización de los libros

Es importante entender la diferencia entre un proyecto configurado como libro y otro configurado como website. En el caso de un libro, se aplicarán las mismas opciones de formateo y diseño gráfico a todos los documentos que forman parte del mismo, puesto que se combinan en un solo documento (esto queda más claro cuando el formato de salida es PDF, puesto que se genera un único archivo con todo el contenido). Sin embargo, cuando creamos un sitio web es posible aplicar opciones de diseño y configuración personalizadas a cada documento del sitio, puesto que se comportan de forma independiente (aunque es posible aplicar también opciones globales para todo el sitio web).

En consecuencia, en un proyecto de tipo book cualquier opción de renderizado (incluso las específicas de un formato de salida) deben especificarse en el archvio global _quarto.yml. Se pueden utilizar muchas de las herramientas aplicables a los sitios web con Quarto (barras de navegación, encabezado y pie de página, barra de búsqueda textual, etc.). No obstante, todas estas opciones hay que especificarlas bajo la etiqueta book en el caso de un libro, no bajo la etiqueta website.

Una excepción a esta regla es la opción global output-dir, para seleccionar un directorio de salida diferentes donde almacenar los archivos HTML, PDF, etc. del libro ya renderizado. Esa opción se debe poner debajo de la etiqueta project:

project:
  type: book
  output-dir: docs

Por contra, la opción output-file, que cambia el nombre del fichero de salida generado (por defecto es el título del documento), se pone debajo de la etiqueta book:

book:
  title: "El título de este libro es una cosa larguísima"
  author: "Jane Doe"
  output-file: "nombre-corto"
Extensiones de los archivos de salida

Cuando configuremos un nombre personalizado para el fichero de salida del libro con la opción output-file no debemos añadir una extensión, ya que ésta se añadirá automáticamente en función del tipo de fichero de salida generado.

Personalización en LaTeX

Aunque no nos estamos centrando en la producción de salida LaTeX/PDF en este taller, aprovechamos este punto para resaltar que es posible también utilizar paquetes, scripts y otras herramientas LaTeX que ya tengamos desarrolladas previamente.

El método más directo (aunque a bajo nivel) para introducir los cambios es crear todo el libro con Quarto y compilar la salida en formato latex.

Terminal
quarto render --to latex

Esto nos dejará todo el código fuente de LaTeX dentro del subdirectorio _book/book-latex (o en el directorio de salida que hayamos configurado). Podemos acabar de editar esos ficheros y compilar con otra herramienta (e.g. un editor LaTeX o usando make) el documento final.

Sin embargo, si los cambios se limitan a modificar las opciones de configuración estándar del documento en LaTeX, entonces podemos usar la extensa [lista de variables de configuración para LaTeX de Pandoc], con la que podremos indicar:

  • Opciones de clase (páginas a doble cara, tamaño de página).
  • La opción documentclass para cambiar la plantilla del documento base; normalmente, Quarto usa scrreport, scrbook o scrartcl (clases del paquete LaTeX KOMA-Script).
  • La opción geometry para cambiar las dimensiones de la página, los márgenes, etc.
  • Fuentes y tipos de letra, color de la fuente, etc.
  • Enlaces: color, estilo, ubicación, etc.

Por último, debemos tener en cuenta que si en alguno de los capítulos de nuestro libro insertamos notas en el margen, figuras al margen o cualquier otro elemento en los márgenes, entonces el área de texto de los demás capítulos se mantendrá más reducida (dejando espacio en blanco en el margen), para poder presentar adecuadamente esos elementos en el margen de las páginas que sí los contienen. Nuevamente, esto se debe a que en el libro PDF la maquetación es común a todo el documento.

6.6 Plantillas y extensiones de Quarto

Por si no fuese suficiente con la larga lista de funcionalidades y opciones de configuración de Quarto estándar, se pueden instalar extensiones para ampliar todavía más su funcionalidad o modificar su comportamiento.

Es importante saber que antes de utilizar una extensión debemos de instalarla localmente y, además, que las extensiones se instalan para cada carpeta de proyeto en la que tengamos un documento individual, website, libro, etc. Por tanto, cada proyecto puede tener su propio listado de extensiones de Quarto instaladas y diferente del de otros proyectos.

Las extensiones se suelen publicar como proyectos en GitHub, por ejemplo la extensión quarto-ext/fontawesome. Si pulsamos en el enlace anterior vemos que una extensión es un conjunto de ficheros en un repositorio. Al instalar la extensión, estos ficheros se copiarán localmente en el directorio de nuestro proyecto, dentro de una carpeta de nombre _extensions.

Por ejemplo, supongamos que queremos instalar en nuestro proyecto mi-projecto dos nuevas extensiones creadas por quarto-ext en GitHub, que se llaman fontawesome y video. En una terminal del sistema, vamos al directorio de trabajo de nuestro proyecto (este paso previo es importante) y ejecutamos los comandos para instalarlas.

Terminal
cd myblog
quarto add quarto-ext/fontawesome
quarto add quarto-ext/video
Extensiones en documentos sin proyecto

No es obligatorio que tengamos un proyecto creado para instalar extensiones y aplicarlas a documentos Quarto. Si tenemos uno o varios documentos en un directorio (aunque no sea un proyecto) y ejecutamos los comandos para instalar extensiones dentro de ese directorio, entonces cualquier documento situado en ese directorio puede acceder a dichas extensiones.

Las extensiones están organizadas dentro de cuatro grandes tipos:

  • Códigos acortados o filtros: permiten usar una sintaxis más breve para operaciones complicadas o aplicar filtros de diversa índole para manejo de contenidos.
  • Artículos de revista: extensiones que ya contienen los archivos de estilo necesarios para generar artículos científicos según el formato requerido por diversas organizaciones y editoriales (véase Capítulo 7).
  • Formatos personalizados: Plantillas que aplican formatos predefinidos a nuestros documentos.
  • Reveal.js: Plantillas y temas para la creació de diapositivas con Quarto utilizando esta biblioteca JavaScript.

6.7 Publicación del proyecto

Si queremos publicar nuestro proyecto (documento, libro, sitio web), tenemos varias opciones de publicación, como ya vimos en la Sección 5.7. De entre las opciones disponibles, una bastante directa y que no tiene coste es utilizar GitHub Pages.

GitHub Pages es un método de publicación de documentación asociada a un proyecto de GitHub. Esencialmente, tenemos que seguir un procedimiento ya definido para subir los archivos ya compilados de nuestro proyecto a GitHub y configurar ciertos parámetros de nuestro proyecto en esa plataforma. Como resultado, el servicio GitHub Pages toma ese contenido y lo publica en un sitio web, asignándole una URL para que sea accesible mediante un navegador (igual que estos mismos apuntes).

Aquí vamos a explicar el método para publicar nuestro contenido utilizando el comando quarto publish.

6.7.1 Método con quarto-publish

Antes de empezar a usar Git y GitHub con RStudio

Comenzar a utilizar un Sistema de Control de Versiones (SCV) como Git y un servicio como GitHub para gestionar nuestros proyectos es una tarea factible pero no tan sencilla como puede parecer, sobre todo si no has recibido previamente formación sobre estas tecnologías o no has aprendido a usarlas por tu cuenta.

Por tanto, hacemos una llamada a la cautela para afrontar el contenido de esta sección armados de mucha paciencia, ganas de aprender y sobre todo tiempo para seguir todos los pasos descritos en los diferentes capítulos de varios tutoriales.

Para poder publicar nuestro proyecto con este método, primero hemos tenido que crear un proyecto nuevo en GitHub, clonarlo en nuestra máquina y crear un nuevo proyecto (con RStudio o MS Visual Studio) dentro del directorio del proyecto para que esté bajo control de versiones. Alternativamente, también podemos realizar este proceso a la inversa: crear primero todo el proyecto en nuestra máquina, para luego subirlo a GitHub.

En cualquiera de los dos casos, el contenido de este taller no cubre la parte de poner nuestro proyecto en un SCV (Sistema de Control de Versiones) como Git, para después subirlo a un servicio como GitHub. No obstante, dejamos a continuación unos enlaces a un tutorial paso a paso que nos guiará por este proceso.

  1. Si no tenemos ya una cuenta de usuario/a en GitHub, debemos registrar una nueva cuenta.
  2. Ahora, debemos instalar Git en nuestra máquina, si no estaba ya instalado previamente.
  3. Para no tener problemas después cuando interactuemos con GitHub, es preciso configurar un método de autenticación para acceder a la plataforma con nuestro usuario. La forma más sencilla es mediante el navegador web y configurando un sistema de autenticación de doble factor (2FA). La opción más cómoda es instalar la app de GitHub en tu móvil y seguir las instrucciones. Una vez que esté funcionando:
    1. Abrimos la página web de GitHub en el navegador e ingresamos con nuestro usuario y contraseña.
    2. Usamos la app de GitHub en el móvil para confirmar nuestra identidad.
  4. Conectamos RStudio con Git y GitHub.
  5. Ahora ya podemos crear un nuevo proyecto en GitHub de varias formas:

Ahora ya podemos trabajar en nuestro proyecto, poniendo en práctica lo explicado hasta el momento en este taller para añadir secciones, bloques de código ejecutable, figuras, tablas, ecuaciones y demás elementos y opciones de configuración. En nuestra máquina, podemos previsualizar periódicamente el resultado (bontón Render en RStudio). Es conveniente que cada poco tiempo, confirmemos los cambios en Git.

Confirmación manual de cambios

Al contrario que en otros servicios que controlan cambios en ficheros (como Google Docs o MS Office 365 en OneDrive), Git no controla automáticamente los cambios realizados en los archivos. Por eso, cada cierto tiempo, cuando hemos terminado cambios relacionados y antes de seguir cambiando muchas cosas más, debemos indicar a Git que queremos confirmar el trabajo hecho hasta ese punto. En el último enlace del párrafo anterior se explica cómo hacerlo desde RStudio (vídeo incluido).

Finalmente, cuando ya tenemos una versión publicable de nuestro proyecto podemos seguir las siguientes instrucciones para publicar el proyecto con el comando quarto publish que automatiza varias fases del proceso.

Enviar los cambios de la rama main a GitHub

Si has prestado atención al último tutorial, verás que la publicación de los contenidos se hace en una rama diferente de la principal de tu repositorio en GitHub, llamada gh-pages. A esa rama sólo se van a subir los ficheros de salida ya generados en los formatos que hayamos configurado en nuestro proyecto (HTML, PDF, etc.).

Es muy importante darse cuenta de que los ficheros fuente de nuestro proyecto, con extensión .qmd, _quarto.yml etc. no se han copiado al repositorio remoto y, por tanto, todavía no tenemos una “copia de seguridad” de dichos archivos en GitHub.

Para conseguir esto, desde RStudio (pestaña Git) podemos hacer una operación push que envía los commits (cambios confirmados) desde nuestra máquina local al repositorio remoto. Alternativamente, también podemos abrir una terminal de sistema en RStudio y ejecutar (en el directorio raíz del proyecto) el siguiente comando:

Terminal
git push origin main

Si todo va correctamente, aparecerán varios mensajes en pantalla informando del progreso de la subida y confirmando que el historial de cambios en nuestro repositorio local ya está sincronizado con el repositorio remoto alojado en GitHub.