5  Libros

La diferencia visible entre los libros y los demás documentos creados con Quarto es la división de los libros por capítulos.

Aunque pudiera parecer que esta es una diferencia menor, tiene implicaciones, tanto en el desarrollo del proyecto como en el resultado final. La más inmediata es que ya no se trabaja con un único archivo fuente (qmd), sino con un archivo fuente para cada uno de los capítulos del libro. Pero empecemos por el principio…

5.1 Creación del proyecto

La escritura de un libro en Quarto empieza con la creación de un proyecto.

¿¡Proyecto!?

Aunque en el lenguaje cotidiano, el término proyecto suele referirse al conjunto de tareas que permiten lograr un objetivo, no es así en RStudio.

En RStudio un proyecto (R project o simplemente Project) es un entorno de trabajo organizado y aislado que facilita la gestión de los recursos (archivos, imágenes, datos, scripts…) relacionados con una labor específica.

Algunas labores complejas —como el desarrollo de un libro en Quarto— deben gestionarse mediante un proyecto.


A continuación se detallan los pasos para crear un proyecto de libro en Quarto:

  1. Se accede al menú File > New Project… O equivalentemente, se presiona el ícono .

    Aparece el asistente para nuevos proyectos (New Project Wizard), que irá guiando el proceso.

  2. La ventana Create Project permite elegir si el nuevo proyecto se ubicará en un directorio nuevo (New Directory) o en uno existente (Existing Directory).

    ¡Parta de cero!

    Lo ideal es empezar en un directorio vacío, de manera que únicamente tenga el contenido del proyecto que se está creando.

  3. En la ventana Project type, se selecciona Quarto Book.

  4. En la ventana Create Quarto Book, se indica el nombre del directorio y se selecciona el botón Create Project.

Una vez surtidos los anteriores pasos, se crea un proyecto de libro Quarto en el directorio especificado y se abre el nuevo proyecto.

El nuevo proyecto contiene los siguientes elementos:

  • Archivo de configuración “Milibro.Rproj”

  • Carpeta “.quarto”

  • Archivo de imagen “cover.png”

  • Cuatro archivos qmd: “index.qmd”, “intro.qmd”, “references.qmd” y “summary.qmd”

  • Archivo YAML “_quarto.yml”

  • Archivo de referencias “references.bib”

Estos archivos sirven de plantilla para el desarrollo del nuevo libro.

5.2 Archivo de configuración del proyecto

Cada proyecto de RStudio tiene asociado un archivo con extensión Rproj, que constituye su núcleo.

Al invocar este archivo, se carga el entorno de trabajo del proyecto, es decir, la ruta de trabajo y su configuración asociada.

5.3 YAML

La configuración del libro, escrita en lenguaje YAML, ya no aparece como encabezado en el documento (cf. sección 2.1.1.1), sino en un documento de texto plano, llamado “_quarto.yml”.

Para editarlo, se abre desde la pestaña Files, que en RStudio está ubicada por defecto en el panel inferior derecho. Lo primero que se notará al abrirlo es que no está encerrado por las líneas de tres guiones, como sí lo debe estar el encabezado YAML en los documentos que no son libros, para separarlo del contenido escrito en Markdown.

Todo lo demás funciona igual que en el encabezado YAML: se usa la sintaxis clave: valor y debe prestarse atención a las indentaciones.

Si aún no ha revisado la sección 2.1.1.1, le recomendamos hacerlo, pues allí se presentan los aspectos básicos del YAML. A continuación se detallarán los que son de particular pertinencia para los libros.

Partamos del archivo YAML que se crea como plantilla con el nuevo proyecto.

project:
  type: book

book:
  title: "Mi libro"
  author: "Norah Jones"
  date: "26/3/2025"
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

bibliography: references.bib

format:
  html:
    theme:
      - cosmo
      - brand
  pdf:
    documentclass: scrreprt

editor: visual

En los proyectos de libro Quarto, es necesario especificar que se trata de un proyecto tipo libro, lo que genera un entorno adaptado a las particularidades de este tipo de proyectos:

project:
  type: book

A continuación —bajo la clave book— se presentan los metadatos del libro (cf. sección 2.1.1.1), que aunque no son obligatorios, sí son informativos. Estos se editarían en caso de querer mantenerlos en el nuevo proyecto.

Igualmente, bajo las claves book y chapters, se especifica el orden de los capítulos mediante una lista.

book:
  chapters:
    - index.qmd
    - intro.qmd
    - summary.qmd
    - references.qmd

Cada capítulo exige un documento fuente qmd. El libro plantilla que se crea al iniciar un nuevo proyecto de libro Quarto está conformado por cuatro capítulos y contiene, por tanto, cuatro archivos qmd.

Precaución 5.1: ¡Tiene que llamarse “index.qmd”!

El archivo fuente del primer capítulo de los libros creados con Quarto debe llamarse “index.qmd”.

Esto no significa, sin embargo, que el primer capítulo del libro deba tener ese mismo nombre. El título de cada capítulo lo decide su autor.

Mediante la clave bibliography se especifica el archivo que contiene las referencias bibliográficas.

Como parte del nuevo proyecto de libro, se incluye un archivo llamado “references.bib” que puede usarse como plantilla para la organización de la referencias bibliográficas.

bibliography: references.bib

Seguidamente, el YAML presenta lo concerniente al formato de salida:

format:
  html:
    theme:
      - cosmo
      - brand
  pdf:
    documentclass: scrreprt

La presente plantilla especifica dos formatos de salida: html y pdf. Para cada estos formatos se introducen especificaciones adicionales.

Para el formato html se definen los temas. Estos determinan la apariencia del documento, en términos de colores, fuentes, márgenes, etc.

El tema por defecto de los documentos html se denomina “Bootstrap 5”; es el que se usa en este libro. Hay otros 25 temas disponibles, que se listan en el sitio de Quarto, y cuya apariencia puede observase en el sitio del proyecto Bootswatch, de donde son tomados.

Cuando se especifican dos temas, como en la plantilla del YAML, el primer tema (cosmo en la plantilla) actúa como base, definiendo las variables iniciales (colores, fuentes, márgenes, etc.). El segundo tema (brand en la plantilla) sobreescribe solo las variables que están explícitamente definidas en este tema, manteniendo las del primero en caso de no haber conflicto.

Finalmente, en la plantilla YAML, se especifica el uso del editor visual:

editor: visual

Se recomienda trabajar en el editor fuente (cf. alerta 1.1):

editor: source

Como alternativa a la plantilla YAML que se genera con los nuevos proyectos de Quarto, se muestra a continuación el YAML de este libro:

project:
  type: book

book:
  title: Quarto
  author: Guillermo Correa Londoño
  page-navigation: true
  chapters:
    - index.qmd
    - 02-docs.qmd
    - 03-tools.qmd
    - 04-ref.qmd
    - 05-books.qmd

cover-image: images/quarto.png

lang: es

editor: source
    
format:
  html:
    code-overflow: wrap

toc-depth: 6
toc-title: Contenido del capítulo

number-sections: true

execute: 
  cache: true

crossref:
  lst-title: Código
  lst-prefix: código
  fig-prefix: figura
  tbl-prefix: tabla
  eq-prefix: expresión

A continuación, se destacan los aspectos no mencionados previamente.

Vínculos para pasar a los capítulos vecinos

book:
  page-navigation: true

En los libros html, como el presente, esta opción introduce vínculos al final de cada capítulo, para regresar al capítulo anterior (excepto en el primer capítulo) o para pasar al capítulo siguiente (excepto en el último capítulo):

🡐 Capítulo anterior\(\quad\quad\quad\quad\quad\quad\quad\quad\) Capítulo siguiente 🡒

Capítulos

book:
  chapters:
    - index.qmd
    - 02-docs.qmd
    - 03-tools.qmd
    - 04-ref.qmd
    - 05-books.qmd

Tal y como se indicó en la alerta 5.1, el archivo fuente del primer capítulo tienen que llamarse “index.qmd”. Nótese, sin embargo, que esto no determina el nombre del primer capítulo (Introducción en el presente libro). De hecho, los nombres de los demás archivos fuente tampoco corresponden con los nombres de los capítulos.

El nombre de cada capítulo queda determinado por el encabezado de primer nivel (#) que aparece al comienzo del correspondiente archivo fuente.

Portada

cover-image: images/quarto.png

Mediante la opción anterior se especifica la ruta de la imagen que se usa a manera de portada, al comienzo del documento.

Código enrollable

format:
  html:
    code-overflow: wrap

Esta opción hace que el código de todos los fragmentos sea enrollable (cf. 3.1.3). Esto puede facilitar la visualización desde diferentes dispositivos.

Si eventualmente se quisiera evitar este comportamiento en algún fragmento de código particular, bastaría con agregarle la opción code-overflow: scroll.

Número de niveles que se muestran en la tabla de contenido

toc-depth: 6

En los documentos html se incluye por defecto una tabla de contenidos (Table Of Contents) (Podría evitarse su aparición mediante la instrucción toc: false). Esta tabla, que aparece en la parte derecha, actúa como herramienta de navegación entre las diferentes secciones del capítulo activo.

La profundidad por defecto para la tabla de contenidos (toc-depth) es 3, lo que hace que en aparezcan las secciones de nivel 2 (##) y nivel 3 (###)1, pero no las de los niveles más internos, si los hubiera. Es posible indicar hasta 6 niveles de profundidad en la tabla de contenidos.

Título personalizado para la tabla de contenido

toc-title: Contenido del capítulo

Esta opción permite personalizar el título de la tabla de contenidos.

Numeración de las secciones

number-sections: true

Mediante esta opción se activa la numeración jerárquica automática para los diferentes capítulos y secciones del libro.

Generar caché

execute: 
  cache: true

Esta opción hace que se genere un carpeta de caché para cada uno de los capítulos. En estas carpetas se guardan los resultados de las ejecuciones de los diferentes fragmentos de código, permitiendo reutilizarlos en renderizaciones futuras, siempre que no se hayan producido cambios ni en el código ni en los archivos de entrada. Esto agiliza los procesos de renderizado.

Nombres personalizados para las referencias

En el capítulo 4 se ilustró lo relativo a las referencias. El usuario puede elegir cómo desea que aparezcan los nombres de los diferentes elementos en el documento renderizado:

  1. Un nombre genérico acorde con el idioma. Usando, por ejemplo @tbl-atributos.

  2. Sin ningún tipo de nombre; únicamente con el nomenclador. Usando, por ejemplo, -@tbl-atributos.

  3. Con un nombre personalizado para esa referencia particular. Usando, por ejemplo, [cuadro @tbl-atributos].

En la advertencia 4.1 se indicó que era posible personalizar los nombres genéricos cuando se usa la primera forma de referenciación.

Así, por ejemplo, si el usuario no se siente satisfecho con el nombre genérico Tabla (con mayúscula) que aparece al referenciar las tablas, puede personalizar este nombre en el YAML, mediante la opción tbl-prefix: tabla. Esto mismo aplica para los demás elementos referenciables.

También es posible personalizar los títulos de los elementos referenciables. En la sección 4.8 se mostró cómo referenciar fragmentos de código, identificándolos como elementos de un listado. Para evitar que el título de los fragmentos vaya antecedido de la palabra Listado, se usa la opción: lst-title: Código

crossref:
  lst-title: Código
  lst-prefix: código
  fig-prefix: figura
  tbl-prefix: tabla
  eq-prefix: expresión

En desarrollo…

  1. Los capítulos (#) aparecen a la izquierda.↩︎