Libros con Quarto Book

El sistema Quarto Book para contenido largo. Estructura por capítulos, parts, salida a HTML / PDF / EPUB, índice y referencias cruzadas entre capítulos, y los detalles que distinguen un libro publicable de una colección de Markdown.

Por qué un “book”

Quarto Book es un tipo de proyecto distinto a Website. Lo que lo distingue:

• Capítulos numerados automáticamente.
• Parts (agrupaciones de capítulos).
• Navegación lineal “Anterior / Siguiente” entre capítulos.
• Salida nativa a PDF y EPUB, no solo HTML.
• Cross-references cross-chapter: @fig-x desde un capítulo a otro.

Caso de uso: documentación técnica larga, manuales, libros educativos. Es el sistema con el que Hadley escribe sus libros (Advanced R, R for Data Science).

Crear el proyecto

quarto create project book mi-libro
cd mi-libro
quarto preview

Estructura inicial:

mi-libro/
├── _quarto.yml
├── index.qmd               ← prefacio
├── intro.qmd
├── summary.qmd
├── references.qmd
├── references.bib
└── cover.png

_quarto.yml del libro

project:
  type: book

book:
  title: "Análisis de RNA-seq con DESeq2"
  author: "Ana López"
  date: "2026-05-19"
  cover-image: cover.png
  search: true
  repo-url: https://github.com/ana/libro-rnaseq
  repo-actions: [edit, issue]

  chapters:
    - index.qmd
    - intro.qmd
    - part: "Datos"
      chapters:
        - 01-bioconductor.qmd
        - 02-counts.qmd
        - 03-summarized.qmd
    - part: "Análisis"
      chapters:
        - 04-deseq2.qmd
        - 05-contrastes.qmd
    - summary.qmd
    - references.qmd

  appendices:
    - apendice-instalacion.qmd
    - apendice-sessioninfo.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
    css: styles.css
  pdf:
    documentclass: scrreprt
    classoption: [11pt]
  epub:
    cover-image: cover.png

Lo clave:

• chapters:: orden de los capítulos. Cada entrada es un .qmd.
• part:: agrupa capítulos en una sección con título.
• appendices:: capítulos especiales que van al final con numeración A, B, C…
• repo-url + repo-actions: añade botones “Edit on GitHub” en cada página. Práctica recomendada para libros open.

Capítulos: estructura mínima

Cada capítulo es un .qmd con front matter mínimo:

---
title: "Bioconductor"
---

# Bioconductor

Contenido del capítulo...

## Sección

Más contenido.

El primer # (h1) se trata como título del capítulo. Las secciones internas son ##, sub-secciones ###, etc. Quarto numera automáticamente: “1.1”, “1.2”, “2.1”…

index.qmd por convención es el prefacio, la “home” del libro.

Salida a múltiples formatos

format:
  html: default
  pdf: default
  epub: default

Render:

quarto render                 # los tres formatos
quarto render --to pdf        # solo PDF
quarto render --to epub

HTML

Sitio web navegable, similar a un website Quarto. Navegación lateral con capítulos, “Anterior / Siguiente”, buscador integrado.

PDF

LaTeX por debajo. scrreprt es buen documentclass por defecto (de la familia KOMA, layout más moderno que report estándar). Para libros largos:

pdf:
  documentclass: scrbook       # libro KOMA con páginas izda/dcha
  classoption: [11pt, twoside]
  geometry:
    - margin=2.5cm
    - inner=3cm
    - outer=2.5cm
  toc-depth: 2
  number-depth: 2

scrbook da páginas pares e impares con márgenes asimétricos (estilo libro real). inner (interior, junto al lomo) más grande que outer.

EPUB

Formato e-book. Calidad razonable out-of-the-box. Lo que controla:

epub:
  cover-image: cover.png
  toc-depth: 2
  epub-cover-image: cover.png

Validar EPUB antes de publicar:

quarto render --to epub
epubcheck _book/mi-libro.epub

epubcheck es una herramienta Java separada, útil para asegurar que tiendas como Kindle aceptarán el archivo.

Cross-references entre capítulos

En el capítulo 1 (01-intro.qmd):

## Resultados {#sec-resultados}

Desde el capítulo 4:

Como vimos en @sec-resultados...

Quarto resuelve la referencia. En HTML: enlace al capítulo. En PDF: número de sección + número de página automáticos.

Lo mismo con figuras, tablas, ecuaciones. Para que funcione, cada label debe ser único en todo el libro, no dos #fig-tendencia en capítulos distintos.

Bibliografía global

Un archivo references.bib compartido entre todos los capítulos:

bibliography: references.bib

Citas ([@love2014]) desde cualquier capítulo. La lista de referencias se agrega:

• En HTML: en references.qmd (último capítulo).
• En PDF: al final del libro.

references.qmd puede ser simplemente:

# Referencias {-}

Las citas se inyectan automáticamente. {-} quita la numeración del capítulo.

Parts: secciones del libro

chapters:
  - index.qmd
  - part: "Parte I: Fundamentos"
    chapters:
      - 01-intro.qmd
      - 02-setup.qmd
  - part: "Parte II: Análisis"
    chapters:
      - 03-modelo.qmd
      - 04-resultados.qmd

Quarto genera páginas de separador entre parts con “Parte I”, “Parte II”, etc. Numeración de capítulos sigue siendo continua (1, 2, 3, 4) aunque cambien de parte.

Apéndices

appendices:
  - apendice-instalacion.qmd
  - apendice-sessioninfo.qmd

Capítulos numerados como A, B, C… y separados visualmente del cuerpo principal. Ideal para material de referencia (instalación, troubleshooting, sessionInfo del análisis canónico).

Number depth: hasta dónde numerar

format:
  html:
    number-depth: 2

number-depth: 2 numera capítulo + sección (1.1, 1.2, 2.1…). number-depth: 3 añade sub-sección (1.1.1). Para libros, 2 es lo normal, 3 se vuelve ilegible.

Sidebar de capítulos

En HTML, la sidebar muestra el TOC del libro entero (todos los capítulos). El layout idiomático:

• Sidebar izquierda: capítulos y secciones.
• Cuerpo central: contenido.
• Sidebar derecha: secciones de la página actual + botones “Edit”, “Issue”.

page-navigation: true añade flechas “Anterior / Siguiente” al pie de cada capítulo.

Estructura para libros reales

libro-rnaseq/
├── _quarto.yml
├── index.qmd                  ← prefacio
├── 00-prologo.qmd
├── parts/                     ← capítulos agrupados
│   ├── 01-bioconductor.qmd
│   ├── 02-deseq2.qmd
│   ├── 03-visualizacion.qmd
├── apendices/
│   ├── instalacion.qmd
│   └── sessioninfo.qmd
├── data/                      ← datos de ejemplo
├── R/                         ← funciones reutilizables
├── references.bib
├── cover.png
└── styles.css

Para libros con análisis pesado, freeze: auto en _quarto.yml es obligatorio, sin él, render del libro = recalcular todos los chunks de todos los capítulos cada vez.

Render selectivo

Durante desarrollo, no quieres renderizar el libro entero. Para preview de un capítulo:

quarto preview 03-deseq2.qmd

Sirve solo ese capítulo, con auto-reload. Útil para iterar rápido sobre un capítulo en concreto.

Publicación: tres rutas

Los libros se publican igual que websites (lo veremos en el siguiente tutorial):

• GitHub Pages: gratis, ideal para libros open.
• Netlify: gratis hasta cierto tráfico, mejor configuración custom.
• Posit Connect / QuartoPub: para libros privados / corporativos.

Para libros que se venderán como PDF/EPUB (Gumroad, Leanpub, Amazon), genera el output y súbelo. Quarto produce los archivos finales. La distribución la haces aparte.

Trampas habituales

• Labels duplicados entre capítulos. #fig-tendencia en capítulo 1 y 4 rompe las cross-references. Prefija: #fig-cap1-tendencia, #fig-cap4-tendencia.
• PDF sin documentclass adecuado. El default puede no respetar twosided / márgenes esperables. Usa scrbook o book.
• EPUB sin cover-image. Algunas tiendas rechazan el archivo. Pon siempre cover-image.
• Capítulos olvidados en chapters:. Si añades nuevo.qmd y no lo metes en el YAML, no aparece en la sidebar. Quarto no auto-descubre capítulos.
• number-depth excesivo. 4 o 5 genera “1.2.3.4.5”, ilegible. 2 o 3 máximo.

En la siguiente entrega

Tienes el libro. Lo siguiente: publicarlo, GitHub Pages, Netlify, QuartoPub. Tres rutas, cuándo cada una, y los pasos prácticos. Lo siguiente.