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

Desde sus inicios utilizo Quarto para documentar trabajos y realizar reportes. Durante mucho tiempo trabajé con RStudio con Rmarkdown,y seguía de cerca a la compañía Posit, que es quien le da soporte. Nunca llegué a engancharme con los Jupyter Notebooks. En cambio, con Quarto la conexión fue casi inmediata.

He aprendido mucho de sus posibilidades. Los documentos de investigación los escribo con Quarto, y me sigue pareciendo una maravilla. En ese sentido, estas son algunas pautas de uso que he ido acumulando. Más adelante, de hecho, me gustaría hacer un curso más amplio sobre todo lo que Quarto puede ofrecer, porque la herramienta da para 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 muy sencillo, que es escribir en Markdown, y desde ahí permite producir documentos muy distintos con pocos cambios.

Ese rasgo, que parece menor, para mí siempre fue central. Me interesa escribir una sola fuente bien organizada y luego poder transformarla en un reporte HTML, un PDF, una presentación o incluso un documento más 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

Uno de los mayores potenciales de Quarto es precisamente ese: la capacidad de generar muchos 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 mucho más flexible el trabajo repetitivo. En lugar de mantener cinco versiones de un mismo informe, se puede mantener una sola estructura y variar lo necesario en la ejecución.

El detalle visual también importa

Otra cosa que me hizo quedarme en Quarto fue que no solo sirve para “sacar resultados”, sino para producir documentos bien presentados. En investigación, docencia o consultoría, esa parte importa bastante. No basta con que el contenido sea correcto; también conviene que esté bien organizado y se vea bien.

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 recursos resulta muy útil cuando un documento necesita dejar de ser solo lineal y empieza a requerir 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 trivial. Esa capacidad de tocar solo ciertas partes del documento permite construir piezas mucho más cuidadas sin caer en maquetaciones pesadas.

Layouts, bloques y organización del contenido

Con el tiempo, uno descubre que Quarto no es solo una forma de compilar Markdown. También es una forma de 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 es oro. 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 me parece especialmente valioso cuando se trabaja con audiencias mixtas. Hay lectores que solo quieren el resultado final, y otros que sí quieren revisar cómo se generó. Quarto permite servir 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 significa que uno puede partir de una base ya agradable y luego ajustar tipografías, colores, espacios o componentes concretos según el proyecto.

También se puede afinar cómo se ve el código, activar temas claro/oscuro y cambiar estilos de resaltado. En otras palabras, Quarto no obliga a aceptar un estilo estándar sin personalidad. Permite empezar rápido, pero también profundizar 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, y ahí Quarto ofrece un puente muy bueno 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 muy flexible el mismo material según la situación.

Reveal.js, en particular, tiene detalles que me parecen muy potentes: 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 mucho más cuidadas que las típicas exportaciones automáticas. Y como todo sigue viviendo en texto, también 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 bastante amable. En muchos casos basta con renderear 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. Más bien, Quarto se siente como una plataforma más coherente y más amplia 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 bastante 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, todo en un mismo flujo.

Y por eso, cuando digo que para mis documentos de investigación es una maravilla, no lo digo como entusiasmo pasajero. Lo digo porque realmente se convirtió en una de esas herramientas que terminan cambiando la forma en que uno trabaja.

Más adelante me gustaría desarrollar un curso más completo sobre todas las posibilidades que brinda. Porque estas notas son solo algunas pautas de uso. Quarto tiene bastante más por ofrecer.

Recursos