1 Publicar algo que se reconstruye solo
Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means
La mayoría de los informes se hacen a mano. Un analista ejecuta un script, copia un número en un documento de Word, pega un gráfico en una diapositiva, vuelve a escribir el mismo número en un correo y exporta un PDF para el sitio web. Quien trabaja en aprendizaje automático pega los puntajes de una evaluación en un informe, en una presentación para el equipo de producto y en una ficha del modelo (model card). Quien funda una startup copia las cifras de este mes en un informe para inversionistas. Cada copia es un pequeño acto de fe: que el número era correcto y que lo sigue siendo. Cuando los datos cambian, alguien tiene que encontrar cada copia, y nadie puede decir con certeza de dónde salió cada una.
Esa fe es el problema, porque la razón para publicar datos es que la gente se apoya en ellos. Un trabajo que se puede reproducir se gana la confianza: quien lo lee, lo revisa o lo dirige puede ver de dónde salió cada número y reconstruirlo. Justifica las decisiones, porque la evidencia detrás de una elección se puede mostrar, volver a revisar y defender más tarde. Y sirve de base para otros: alguien parte de tu fuente en lugar de empezar de cero, la amplía y la corrige, que es como mejoran la ciencia, la tecnología y el entendimiento. Un trabajo que no se puede reproducir no ofrece nada de esto; pide que lo aceptes por fe.
La alternativa es una sola fuente que reconstruye cada salida, el paso Publica del ciclo de este libro. Cuanto más de ese trabajo hace un programa, menos lugares hay por donde se cuele un error, y mejor es la experiencia para todas las personas involucradas: las que hacen los documentos y las que leen documentos que coinciden entre sí y con los datos.
- Explicar por qué los números copiados a mano se desactualizan, y cómo una sola fuente que reconstruye cada salida lo evita.
- Seguir un archivo
.qmda través de los tres pasos dequarto render, y decir de qué paso viene un error dado. - Distinguir lo que hace Quarto de lo que hace un agente de programación, y decir cómo se revisa cada uno.
- Decidir si vale la pena construir un documento con Quarto, a partir de lo que promete “reproducible” y de dónde Quarto no es la herramienta adecuada.
1.1 Por qué los informes se desactualizan
La guía para visitantes de Londres que recorre la Parte II es un ejemplo pequeño de un problema común. La oficina de turismo publica los mismos datos para varios públicos: una guía web para los visitantes, un dashboard para la gerencia, un informe en Word para los socios, una tarjeta cuadrada para redes sociales y, más adelante, un documento técnico. En el proyecto terminado, cinco páginas leen la misma tabla de visitas a atracciones, y entre todas escriben diez archivos: solo la guía se convierte en una página web, un documento de Word, un PDF, una presentación de PowerPoint, un libro electrónico y una presentación que se ve en el navegador.
Supón que la Association of Leading Visitor Attractions (ALVA), la fuente de esos conteos, corrige una cifra. En un flujo de copiar y pegar, esa corrección tiene que llegar a mano a diez archivos. Suelen fallar tres cosas:
- Números viejos. Se pasa por alto una copia, y el informe para los socios no coincide con el dashboard.
- Origen perdido. Seis meses después, nadie puede decir qué versión de los datos produjo el número del documento técnico.
- Cambios lentos. Como cada actualización es cara, se dejan de hacer, y los documentos envejecen sin que nadie lo note.
Las mismas tres fallas aparecen dondequiera que los números se publiquen más de una vez: el informe mensual cuyo gráfico contradice su resumen, la evaluación cuya presentación cita el puntaje de la semana pasada, el informe para inversionistas que copia una cifra del mes equivocado. Nada de esto es falta de cuidado. Es lo que pasa cuando la salida se trata como lo que se edita. La solución es estructural: edita la fuente y deja que un programa reconstruya las salidas (Figura 1.1).
1.2 Qué es Quarto
Quarto es un sistema de publicación de código abierto, gratuito para cualquiera: un programa de línea de comandos, de esos que ejecutas escribiendo un comando en una terminal (Sección 4.3), que convierte archivos fuente de texto plano en documentos terminados.
La entrada es un archivo de Markdown simple (.md) o un documento de Quarto (.qmd). Markdown es una forma de escribir texto estructurado con unos pocos signos de puntuación, como # antes de un título (Capítulo 6). Un archivo .qmd es Markdown con dos agregados: un bloque de configuración al principio, escrito en YAML, un formato de configuración en el que la sangría tiene significado (Sección 7.1), y celdas de código, bloques de código delimitados que se ejecutan cuando se construye el documento. Aquí va uno completo, el archivo que la prueba del Capítulo 4 le pide escribir a tu agente:
---
title: "Hello"
format:
html: default
typst: default
---
```{python}
answer = 6 * 7
```
The answer is `{python} answer`.Entre las dos líneas --- está la configuración: un título y dos formatos, una página web (html) y un PDF (typst). El bloque delimitado que sigue es una celda de código. La oración del final contiene código en línea: cuando se construye el documento, Quarto ejecuta answer y escribe su valor en la oración. Cuando se construyó este libro, el mismo cálculo dio 42, y ese número se calculó, no se escribió a mano.
1.2.1 Tres pasos: ejecutar, convertir, componer
Renderizar un documento es construir sus salidas a partir de su fuente, y quarto render lo hace en tres pasos (Figura 1.2).
quarto render. Una sola fuente se convierte en Markdown con resultados, que Pandoc convierte a cada formato de salida; para el PDF, Typst compone el resultado.
- Ejecutar. Un motor de cálculo ejecuta las celdas de código: Jupyter para Python, knitr para R. Los resultados (números, tablas, figuras) reemplazan al código en un archivo Markdown intermedio. Las celdas se ejecutan una vez por formato, así que cada salida recibe resultados hechos para ella (Sección 7.5). Este libro usa solo Python.
- Convertir. Para cada formato, Pandoc, un conversor de documentos con larga trayectoria, lee ese Markdown y escribe la salida: HTML, Word (
docx), EPUB, PowerPoint (pptx) o una presentación de Reveal.js. - Componer. Para el PDF, Pandoc escribe fuente para Typst, un sistema de composición tipográfica moderno que viene dentro de Quarto, y Typst produce el PDF. No hace falta instalar LaTeX. (Quarto también puede hacer PDF a través de LaTeX,
format: pdf, si instalas una distribución de TeX.)
La separación importa en la práctica. Una falla en el paso 1 es una falla de tu código: un paquete que falta, un nombre de columna equivocado, una celda que lanza un error. Una falla en el paso 2 o 3 es una falla del documento: una tabla mal formada, una imagen demasiado grande para la página, una opción de un formato que no existe. Cuando un renderizado falla, el mensaje de error te dice qué paso se detuvo, y eso te dice dónde buscar.
Un renderizado de london.qmd se detiene con KeyError: 'visits_2025'. ¿Qué paso falló y dónde buscas primero?
En el paso 1, ejecutar. Una celda de código le pidió a los datos una columna que no tienen, así que compara la celda con los nombres de columna del archivo de datos. La configuración de los formatos no es el problema: Pandoc y Typst nunca llegaron a ejecutarse.
Pandoc convierte entre muchos formatos leyendo cada entrada en un único modelo interno de documento y escribiendo cada salida desde ese modelo. Por eso un solo archivo de Markdown puede convertirse a la vez en un documento de Word y en una presentación: ninguna salida se deriva de la otra. Las dos salen del mismo tipo de intermedio estructurado, construido desde la misma fuente, así que un título es un título en todas partes.
1.2.2 Qué sale
La lista oficial de formatos es larga y está agrupada por tipo (Quarto, All Formats, consultada el 2026-11-12):
| Tipo | Formatos que usa este libro | Otros |
|---|---|---|
| Documentos | HTML, PDF (Typst), Word, EPUB | OpenDocument, PDF a través de LaTeX |
| Presentaciones | Reveal.js, PowerPoint | Beamer |
| Markdown | GitHub, CommonMark, Hugo y otros | |
| Wikis | MediaWiki, DokuWiki y otros | |
| Más formatos | Jupyter, JATS, AsciiDoc y muchos más |
Los sitios web y los blogs son tipos de proyecto construidos con los mismos archivos .qmd; un dashboard es un formato propio, cuyos títulos organizan páginas y filas (Capítulo 8).
1.3 Quarto no es IA
Este libro combina Quarto con un agente de programación, y esa combinación se presta a un malentendido: que Quarto mismo es una herramienta de IA. No lo es. Quarto es software convencional. Con los mismos archivos fuente y los mismos datos, escribe las mismas salidas cada vez. No genera texto, código ni figuras por su cuenta, y no le envía nada a ningún servicio de IA.
El agente es un programa aparte. Lee y escribe los archivos de la carpeta de tu proyecto y ejecuta los comandos que apruebas; luego Quarto convierte esos archivos en formatos. Los dos fallan de maneras distintas, y el flujo de trabajo de este libro está diseñado alrededor de esa diferencia:
| Agente de programación | Quarto | |
|---|---|---|
| Salida para la misma entrada | varía de una ejecución a otra | idéntica |
| Error típico | código o prosa plausibles pero equivocados | un error preciso y reproducible |
| Cómo lo revisas | lees sus cambios, los ejecutas y los comparas con los datos | lees la salida renderizada |
Como la generación y el renderizado están separados, cada error del agente termina en un archivo que puedes leer o en un comando que apruebas antes de que se publique nada: en ese intervalo ocurre el paso Revisa del ciclo. Y como el renderizado es repetible, cualquiera puede reconstruir tus salidas para confirmarlas, sin tener que confiar en el agente.
Si le pides dos veces el mismo gráfico, el agente escribe dos celdas de código distintas. Si te quedas con una y la renderizas dos veces, ¿obtienes dos gráficos distintos?
No. El agente varía; Quarto no. Una vez que la celda está en el archivo, cada renderizado ejecuta el mismo código con los mismos datos, así que revisas la celda una vez y cada reconstrucción hereda esa revisión.
Quarto ejecuta el código que contengan tus celdas, sea cual sea. Si una celda llama a un servicio de IA, el documento se vuelve tan impredecible como ese servicio, y la causa es tu código, no Quarto. Deja las llamadas a modelos fuera de los documentos que renderizas, a menos que la variación sea justamente lo que buscas.
1.4 Reproducible: misma fuente, mismo resultado
Reproducible se usa a la ligera, así que este es el sentido preciso que le da este libro: otra persona, o tú dentro de seis meses, puede reconstruir los mismos resultados a partir de los mismos archivos con un solo comando, y puede ver de dónde salió cada número. Cuatro propiedades lo hacen posible:
Una sola fuente. El texto, el código y los datos viven en archivos de texto plano en una sola carpeta. Nada importante existe solo dentro de una aplicación.
Los números se calculan. Cada figura, tabla y número dentro de una oración sale de una celda de código o de código en línea que lee los datos. Nada se escribe a mano ni se pega desde otro lado.
Un solo comando. quarto render lo reconstruye todo. No hay una secuencia de pasos manuales de exportación que recordar.
Con versiones. Git, la herramienta de control de versiones que se instala en el Capítulo 4, es algo así como el control de cambios de Word para una carpeta entera, con un historial que perdura; una carpeta de proyecto con su historial es un repositorio. Cada estado de la fuente, los datos y la configuración que decides registrar se convierte en un commit, con un mensaje que dice por qué cambió. Cualquier estado anterior se puede restaurar, dos estados se pueden comparar y un resultado se puede atar a los archivos exactos que lo produjeron. Los paquetes de Python del proyecto también quedan fijados, en un archivo de bloqueo o lockfile (uv.lock, que se presenta en la Sección 6.10), así que la computadora de un colega construye el mismo entorno que la tuya: la versión de Python y los paquetes con los que corre el código.
La promesa tiene condiciones, y vale la pena conocerlas desde el principio: el mismo resultado sale de las mismas entradas, el mismo entorno declarado y la misma configuración. Tres cosas la rompen sin avisar. Los datos que se leen en vivo desde un sitio web pueden cambiar entre dos renderizados, así que un proyecto guarda en su carpeta una copia fechada de sus datos. Todo lo aleatorio, como los puntos de partida de un método de agrupamiento, da la misma respuesta solo cuando su semilla, el número que inicia la secuencia aleatoria, está fijada. Y un caché, del que se habla más abajo, puede servir un resultado viejo.
Juntas, estas propiedades le dan la vuelta al problema de la desactualización. Corrige un valor en los datos, renderiza, y la tabla, el gráfico y la oración que lo citan se actualizan juntos, en todos los formatos. La Sección 5.5 te hace hacer exactamente eso, con un archivo de cinco filas, en tu primer capítulo práctico.
Corriges un número en los datos. ¿Qué vuelves a escribir en el informe?
Nada. Arreglas el archivo de datos y renderizas de nuevo. Si la respuesta es cualquier otra cosa, algún número del informe se escribió a mano en lugar de calcularse, y ese es el error que hay que corregir.
Reproducible no significa correcto. Un análisis equivocado se reproduce a la perfección: el mismo número equivocado aparece en cada formato, cada vez. La reproducibilidad hace que los errores se puedan encontrar, porque cualquiera puede rastrear un número hasta su código y sus datos, pero igual tienes que revisar los resultados contra sus fuentes. El Capítulo 22 es un ejemplo extenso de un resultado que se reproduce sin problemas y que aun así no se debe leer como parece a primera vista.
Hay una sutileza más, que importa cuando los proyectos crecen. Renderizar cada página desde cero puede ser lento, así que Quarto puede guardar en caché los resultados con una opción llamada freeze. Un caché vale lo que vale su regla para descartar resultados, y Quarto vuelve a ejecutar una página congelada cuando cambia la fuente de esa página, no cuando cambia un archivo de datos que lee. El Capítulo 23 muestra cómo usar el caché de forma segura. Este mismo libro usa uno, con una forma documentada de vaciarlo (Apéndice H).
1.5 Cuándo Quarto no es la herramienta adecuada
Quarto se gana su lugar cuando el mismo contenido se reconstruye, ya sea porque cambian los datos o porque el contenido va a varios públicos. A cambio te pide un flujo de trabajo en texto plano, una línea de comandos y algo de preparación. Ese trato no siempre conviene:
- Colaboradores que editan en Word. Si las personas que revisan el documento trabajan en un procesador de texto con control de cambios, pueden comentar la salida en Word, pero sus ediciones hay que llevarlas a mano de vuelta a la fuente. Para documentos cuyo trabajo principal es la edición línea por línea entre varias personas, un procesador de texto compartido puede encajar mejor, sin más.
- Diseños maquetados. Quarto produce documentos estructurados: títulos, párrafos, figuras, tablas. Typst y CSS pueden llevar el aspecto bastante lejos, pero un póster o un folleto muy cargado de marca y maquetado al milímetro es más fácil en una herramienta de diseño.
- La fidelidad de los formatos en los bordes. Cada formato solo puede llevar lo que admite. Pandoc escribe buenos archivos de Word y PowerPoint, pero una tabla de PowerPoint no puede contener imágenes, por ejemplo, así que la tabla de fotos de la guía de Londres muestra en su versión
pptxel texto alternativo de cada foto. Revisa cada formato que prometas entregar. - Documentos de una sola vez. Una nota de dos párrafos, sin datos y sin un segundo público, gana poco con un sistema de construcción.
- Diseño y coedición en una startup. Una presentación para inversionistas con cada diapositiva diseñada, un sitio de marketing y un plan que el equipo fundador comenta en Google Docs o Notion se van a quedar en esas herramientas, y un equipo que recién empieza puede, con razón, poner la velocidad primero. El método rinde donde cambian los números de una startup: el informe mensual para inversionistas, el documento técnico (white paper) de un benchmark, el informe por cliente y el sitio de documentación del proyecto.
Una prueba útil: ¿este documento se va a construir una segunda vez? Si los datos van a cambiar, si un segundo público lo va a necesitar en otro formato o si alguien va a preguntar “¿de dónde salió este número?”, el flujo en texto plano se paga solo rápidamente. Si nada de eso es probable, usa lo que sea más rápido.
Resumen
- Los informes se desactualizan cuando sus salidas se editan a mano; editar una sola fuente y dejar que un programa reconstruya cada salida elimina las copias.
quarto renderejecuta las celdas de código, convierte el resultado con Pandoc y, para el PDF, lo compone con Typst; el paso que se detiene te dice dónde buscar.- Quarto es software convencional, no IA: la misma fuente y los mismos datos dan las mismas salidas, así que revisas el trabajo del agente una vez y cualquiera puede reconstruir el tuyo sin tener que confiar en él.
- El trabajo reproducible se gana la confianza, justifica decisiones y sirve de base para otros. Significa una sola fuente, números calculados, un solo comando y archivos con versiones, y hace que los errores se puedan encontrar, no que desaparezcan.
- Un caché como
freezevuelve a ejecutar una página cuando cambia su fuente, no cuando cambian sus datos, así que necesita una regla para vaciarlo. - Quarto conviene para documentos que se van a construir de nuevo, como los informes mensuales, las evaluaciones y los informes para inversionistas, y no es la herramienta adecuada para coeditar, para diseños maquetados ni para notas de una sola vez.
Pero Quarto solo renderiza lo que le dan. En este libro esas fuentes las escribe un agente de programación, y lo que produce varía de una ejecución a otra y puede estar equivocado con total seguridad. ¿Cómo le pides trabajo a un programa así, y cómo revisas lo que te devuelve antes de que se publique nada? El Capítulo 2 lo responde.
Lecturas adicionales
- Quarto, Get Started (consultado el 2026-10-30) y All Formats (consultado el 2026-11-12).
- Quarto, Using Python: cómo se ejecutan las celdas de código a través de Jupyter (consultado el 2026-11-12).
- Quarto, Typst Basics: PDF sin LaTeX (consultado el 2026-10-30).
- Quarto, Licence: la herramienta de línea de comandos tiene la licencia MIT desde la versión 1.4 (antes, la GNU GPL v2), y las herramientas que incluye conservan sus propias licencias de código abierto (consultado el 2026-11-06).
- Pandoc, User’s Guide: el conversor detrás de cada formato (consultado el 2026-11-12).
- Typst, Documentation (consultado el 2026-11-12).