Actualizado el

Por qué Quarto se volvió mi herramienta para documentar y hacer reportes

Por qué Quarto se volvió mi herramienta para documentar y hacer reportes

Uso Quarto desde sus inicios para documentar trabajos y preparar reportes. Durante mucho tiempo trabajé con RStudio y seguía de cerca a Posit, la compañía que le da soporte. Nunca terminé de engancharme con los Jupyter Notebooks. Con Quarto, en cambio, la conexión fue rápida.

He ido aprendiendo sus posibilidades con el uso. Muchos documentos de investigación los escribo con Quarto, y estas son algunas pautas que he acumulado. Más adelante me gustaría preparar un curso más amplio, porque la herramienta ofrece bastante más de lo que uno suele usar al comienzo.

Lo que me atrapó de Quarto

Lo primero que me gustó de Quarto fue que no se siente como un formato cerrado ni como una herramienta que obliga a trabajar de una sola manera. Parte de algo sencillo: escribir en Markdown. Desde ahí permite producir documentos distintos con pocos cambios.

Ese rasgo, aunque parezca menor, para mí es central. Me interesa escribir una sola fuente bien organizada y luego transformarla en un reporte HTML, un PDF, una presentación o un documento técnico sin rearmar todo desde cero.

Además, la integración con RStudio lo hace todavía más natural para quienes ya veníamos trabajando en ese ecosistema. No se siente como una capa extra. Se siente como una evolución lógica.

Un mismo documento, varias salidas

Una de las mayores ventajas de Quarto es esa: generar varios tipos de documentos a partir de una misma base.

En los documentos estáticos, por ejemplo, uno puede escribir en Markdown y luego usar parámetros para adaptar el contenido sin duplicar archivos. Ese enfoque me parece especialmente útil cuando un reporte cambia en algunos valores, pero mantiene la misma estructura general.

En Python, los parámetros pueden definirse con un estilo cercano a Papermill:

#| tags: [parameters]

alpha = 0.1
ratio = 0.1

str(alpha)

En R, lo habitual es declararlos en el YAML:

---
title: "My Document"
params:
  alpha: 0.1
  ratio: 0.1
---

Y luego, desde terminal, esos mismos parámetros pueden cambiarse al renderizar:

quarto render doc.qmd -P alpha:0.2 -P ratio:0.1
quarto render notebook.ipynb --execute-params params.yml

Eso vuelve más flexible el trabajo repetitivo. En lugar de mantener cinco versiones de un mismo informe, se puede mantener una sola estructura y cambiar lo necesario al renderizar.

El detalle visual también importa

Otra razón por la que me quedé en Quarto es que no solo sirve para “sacar resultados”. También ayuda a producir documentos bien presentados. En investigación, docencia o consultoría, no basta con que el contenido sea correcto; también debe estar bien organizado y ser legible.

Quarto hereda bastante poder de Pandoc y de su propio sistema de bloques. Por ejemplo, los bloques delimitados con ::: permiten controlar layout, clases y composición visual con bastante elegancia.

::: {.class}
El texto a cambiar
:::

O en un caso más visual:

::: {layout-ncol=2}
plot(cars)
plot(pressure)
:::

Ese tipo de recurso sirve cuando un documento necesita dejar de ser lineal y requiere columnas, agrupaciones o una composición más editorial.

También me parece muy interesante que se pueda aplicar una clase CSS a fragmentos concretos de texto, especialmente en presentaciones:

This is [magic text]{.clase}

No es un detalle menor. Poder tocar partes específicas del documento permite construir piezas más cuidadas sin caer en maquetaciones pesadas.

Layouts, bloques y organización del contenido

Con el tiempo, uno descubre que Quarto no solo compila Markdown. También ayuda a pensar la estructura visual del documento.

Por ejemplo, los layouts definidos con #| permiten organizar gráficos o salidas en disposiciones más complejas. Un ejemplo típico sería:

#| layout: [[45,-10, 45], [100]]

plot(cars)
plot(pressure)
plot(mtcars)

Eso ayuda mucho cuando se quiere que los resultados no aparezcan simplemente uno debajo del otro, sino distribuidos de una forma más clara y legible.

En reportes analíticos esta posibilidad vale mucho. Permite que el documento final no parezca una libreta de laboratorio, sino un producto pensado para ser leído por otras personas.

Mostrar código, ocultarlo o dejarlo plegable

Una de las decisiones más útiles en Quarto tiene que ver con el código. No siempre el lector necesita verlo. A veces sí conviene mostrarlo; otras veces es mejor ocultarlo y dejar solo el resultado. Y otras veces lo ideal es que esté disponible, pero sin interrumpir la lectura.

Para ocultar el código en un HTML, por ejemplo, se puede usar:

format: html
execute:
  echo: false

Si luego uno quiere forzar que un bloque específico sí se vea, puede hacerlo localmente:

#| echo: true

También existen alternativas intermedias más amables para el lector, como plegar código o activar herramientas:

format:
  html:
    code-fold: true
    code-tools: true

Y esos botones pueden afinarse todavía más:

format:
  html:
    code-tools:
      source: true
      toggle: false
      caption: true

Esto sirve mucho con audiencias mixtas. Hay lectores que solo quieren el resultado final y otros que quieren revisar cómo se generó. Quarto permite atender a ambos sin duplicar el trabajo.

Temas, estilos y personalización visual

Quarto utiliza Bootstrap 5 como base para documentos HTML, y eso abre bastante juego. Viene con varios temas preinstalados y además permite combinar temas con archivos propios.

Por ejemplo:

format:
  html:
    theme:
      - litera
      - custom.css

Eso permite partir de una base agradable y luego ajustar tipografías, colores, espacios o componentes concretos según el proyecto.

También se puede ajustar cómo se ve el código, activar temas claro/oscuro y cambiar estilos de resaltado. Quarto permite empezar rápido, pero también meterse en el diseño cuando hace falta.

PDF, LaTeX y documentos serios

Otra razón por la que sigo usando Quarto es que funciona muy bien para documentos formales. Si uno necesita un PDF más trabajado, puede apoyarse en plantillas LaTeX:

format:
  pdf:
    template: mytemplate.tex

Esto para mí es importante porque muchos documentos de investigación todavía terminan en PDF. Ahí Quarto ofrece un buen puente entre escritura reproducible y presentación académica.

De hecho, buena parte de mis documentos de investigación los escribo así. No solo por comodidad, sino porque el flujo de trabajo queda muy ordenado: texto, código, resultados y referencias conviven en un mismo proyecto.

Presentaciones: otro terreno donde Quarto brilla

Quarto también funciona muy bien para presentaciones. Se puede trabajar con Reveal.js o incluso generar salidas tipo pptx, y eso vuelve flexible el mismo material según la situación.

Reveal.js, en particular, tiene recursos que uso mucho: temas, fragmentos, posicionamiento absoluto y funciones como el zoom con Alt-clic en ciertos contextos.

Un ejemplo de posicionamiento absoluto sería:

::: {.absolute bottom=25 left=100 .fragment}
![](images/logo.png){width=150 fig-alt="Logo"}
:::

Esto permite construir diapositivas más cuidadas que las típicas exportaciones automáticas. Y como todo sigue viviendo en texto, es más fácil versionar, corregir y mantener.

Migrar desde R Markdown sin drama

Otro punto práctico: si uno ya viene de R Markdown, el paso a Quarto suele ser amable. En muchos casos basta con renderizar directamente o hacer pequeños ajustes.

Eso hace que la curva de entrada no sea tan dura. No se trata de tirar todo lo anterior y empezar de cero. Quarto se siente más bien como una plataforma más coherente para seguir haciendo muchas de las cosas que ya hacíamos, pero mejor organizadas.

Los proyectos de Quarto y el orden a largo plazo

Cuando el trabajo crece, aparece otra ventaja: los Quarto Projects. Tener un archivo de configuración del proyecto permite centralizar decisiones de salida, formato y estructura.

Eso vuelve más sencillo mantener varios documentos relacionados bajo una misma lógica. En lugar de configurar cada archivo por separado, se puede definir una base común y reutilizarla. Para trabajos largos, reportes recurrentes o sitios enteros, esto se vuelve especialmente útil.

En otras palabras, Quarto no solo sirve para documentos sueltos. También sirve para construir un sistema de publicación más consistente.

Por qué sigo volviendo a Quarto

Si después de tanto tiempo sigo usando Quarto, es por una razón simple: me permite escribir, analizar y publicar sin separar artificialmente esas tareas.

No necesito decidir entre un documento bonito y un documento reproducible. No necesito elegir entre una presentación y un reporte. No necesito abandonar el ecosistema con el que ya trabajaba para producir algo más flexible.

Quarto me da una forma muy cómoda de pensar documentos como piezas vivas: texto, código, gráficos, estilos y salidas distintas en un mismo flujo.

Por eso, cuando digo que me resulta útil para documentos de investigación, no lo digo como entusiasmo pasajero. Se convirtió en una de esas herramientas que cambian la forma de trabajar.

Más adelante me gustaría desarrollar un curso más completo. Estas notas son solo algunas pautas de uso; Quarto tiene bastante más por ofrecer.

Recursos