9  Publicar y demostrar la reconstrucción

Palabras clave

Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means

La guía está terminada y nadie más que tú puede verla: cada salida está en una carpeta de tu computadora. Este capítulo la pone en la web, donde cualquiera puede abrirla en el teléfono, con GitHub para guardar una copia del historial que vienes registrando con tus commits y GitHub Pages para servir el resultado. Luego hace la pregunta que todo el flujo de trabajo está construido para responder: si cambia un dato de entrada, ¿qué salidas cambian con él, y cómo lo sabes? Esa pregunta no trae prompt. Pone a prueba si puedes predecir lo que hará una reconstrucción, y luego comprobarlo.

En este capítulo
  • Explicar qué agregan el push, las ramas y los pull requests a los commits que ya haces.
  • Convertir la carpeta en un sitio web y publicarlo en GitHub Pages.
  • Elegir entre servicios de alojamiento que reciben tus archivos y servicios que construyen.
  • Predecir, reconstruir y explicar hasta dónde llega un dato de entrada que cambia.

Partes deel final del Capítulo 8, con la sesión de gh iniciada

Construyesun sitio web, su repositorio de GitHub y el sitio en vivo

Punto de controlninguno; para ponerte al día se copia examples/london/

9.1 Git: cada cambio, con seguridad

La Sección 1.4 comparó Git con el control de cambios de Word para una carpeta entera, con un historial que perdura, y desde el primer informe (Sección 5.4) llevas uno tú: git status y git diff antes de cada commit, un mensaje que dice por qué, y git restore para un cambio que no querías. Eso es lo que hace Git dentro de una carpeta, y ya conserva cada versión anterior de la guía, cada una con una nota que dice por qué cambió. Publicar necesita lo que hace Git más allá de la carpeta: una copia del historial a la que otros puedan llegar, y una forma de que otra persona lea un cambio y lo apruebe antes de que cuente.

El vocabulario para eso es corto (Figura 9.1; Pro Git y la documentación de GitHub, consultados el 2026-10-31). Tu carpeta ya es un repositorio, una carpeta de proyecto con su historial, y cada uno de tus commits es una instantánea de cada archivo con seguimiento, con su mensaje. Las palabras nuevas tienen que ver con compartirlos.

Seis pasos. Rama: trabaja en una rama, para que main quede intacta. Commit: guarda una instantánea de los archivos con un mensaje que diga por qué. Push: copia los commits a GitHub. Pull request: propone el cambio y muestra la diferencia. Revisión: alguien lee la diferencia y comenta, aprueba o pide cambios. Merge: los commits se suman a main. Si trabajas sin equipo, haces commit en main y push; en un equipo, cada cambio recorre el ciclo entero.
Figura 9.1: Cada cambio, con seguridad. Un equipo lleva cada cambio por todo el ciclo; si trabajas sin equipo, como en este libro, haces commit en la línea principal y haces push.

Hacer push es copiar los commits al repositorio compartido en GitHub, el sitio web que guarda una copia de un repositorio en línea. Una rama es una etiqueta móvil sobre una línea de commits, para que el trabajo pueda seguir ahí mientras la línea principal, main (el nombre que le dio git init -b main), sigue funcionando. Un pull request propone hacer merge de una rama y muestra su diferencia, o diff, línea por línea, como hace git diff en tu terminal, pero en una página que otros pueden leer; una revisión lo comenta, lo aprueba o pide cambios; hacer merge agrega sus commits a main.

Si trabajas sin equipo, como en este libro, haces commit directamente en main y haces push; en un equipo, cada cambio recorre el ciclo. En los dos casos, la revisión es la que ya haces: leer el diff antes de que un cambio cuente. De aquí en adelante, el agente también puede ejecutar los comandos de Git. Pídele que “haga commit con un mensaje que diga por qué”, y lee su diff antes de aprobar: un diff es la comprobación más clara que tienes de lo que de verdad hizo el agente.

Detente y piensa

El agente informa “Committed the dashboard changes” (hice commit de los cambios del dashboard) y pide hacer push. ¿Qué revisas antes de aprobar?

Respuesta

El diff detrás del commit: qué archivos y líneas cambiaron, que sean los que pediste, que no haya cambiado nada en data/ ni en images/ y que el mensaje diga por qué.

9.2 Dónde vive un sitio

Un sitio web de Quarto renderizado es estático: una carpeta de HTML, CSS, JavaScript, imágenes y documentos, sin ningún programa corriendo en un servidor. Cualquier servidor web puede servirlo, así que publicar significa copiar esa carpeta a un servicio de alojamiento. GitHub Pages es el que usa este libro, porque el repositorio ya está en GitHub y quarto publish gh-pages viene incluido (Figura 9.2).

La carpeta de tu proyecto contiene la fuente, que git sube a la rama main de un repositorio de GitHub. quarto publish gh-pages renderiza el sitio en tu computadora y sube solo el HTML renderizado a una rama aparte, gh-pages. GitHub Pages sirve esa rama en https://user.github.io/repo/. Cualquiera que tenga la dirección puede leer el sitio.
Figura 9.2: Publicar en GitHub Pages. La fuente va a la rama main con Git; quarto publish gh-pages renderiza el sitio en tu computadora y sube solo el HTML renderizado a una rama aparte, que GitHub sirve.

Hay dos formas de llevar un sitio a un servicio de alojamiento. O renderizas en tu propia computadora y subes el resultado, como hace quarto publish para GitHub Pages y Netlify, o el servicio construye el sitio a partir de tu repositorio en cada push. La segunda solo funciona si la construcción instala Quarto, Python y cada paquete que necesita el proyecto, o si la salida renderizada está en el repositorio. El repositorio de Londres deja afuera su carpeta renderizada _site/, así que un servicio que construye no produciría nada hasta que se configure la construcción.

Detente y piensa

Conectas london-guide a un servicio que construye desde Git, y publica un sitio vacío. ¿Por qué?

Respuesta

El repositorio no contiene ningún sitio renderizado, porque .gitignore deja afuera _site/, y la construcción del servicio no tiene Quarto, Python ni paquetes salvo que los instales en ella. O renderizas en tu computadora y subes el resultado, o configuras la construcción.

Seis servicios con planes gratuitos para sitios estáticos muestran las dos rutas (Tabla 9.1, Tabla 9.2). Sus planes gratuitos cambian, así que la Tabla K.2 del Apéndice K enumera los límites vigentes de cada uno, con la fecha en que se consultaron: léelos antes de elegir.

Tabla 9.1: Servicios para los que renderizas y a los que subes.
Servicio Subir con
GitHub Pages quarto publish gh-pages, la ruta de este libro
Netlify quarto publish netlify
Cloudflare wrangler deploy
Tabla 9.2: Servicios que construyen el sitio a partir de tu repositorio.
Servicio Cómo construye
Vercel desde el repositorio, en cada push
GitLab Pages publica una carpeta public desde un trabajo de CI
Render reconstruye en cada push

Dos detalles importan para este proyecto. El plugin de construcción de Quarto para Netlify no ejecuta Python, así que renderiza en tu computadora y sube el resultado. GitLab construye en un trabajo de CI, una construcción que ejecuta en cada push: fija output-dir: public e instala Quarto y Python en el trabajo. Quarto Pub, el servicio gratuito propio de Quarto, está siendo reemplazado por Posit Connect Cloud.

9.3 Una carpeta, un sitio web

Pídele a tu agente
Convierte esta carpeta en un sitio web de Quarto: _quarto.yml (renderiza solo los archivos .qmd; barra de navegación, en inglés: Guide, Dashboard y un menú Downloads con los archivos docx, pdf, pptx, epub y london-slides.html que existan) e index.qmd, y agrega /_site/ a .gitignore. Renderiza y revisa los enlaces.
Probablemente ejecute

escribe 2 archivos · agrega una línea a .gitignore · uv run quarto render → _site/

Tú haces

luego, en la pestaña de la vista previa: Ctrl+C, y uv run quarto preview

Un archivo _quarto.yml en la parte de arriba de la carpeta la convierte en un proyecto. quarto render sin nombre de archivo construye entonces cada página de la lista en _site/, con navegación compartida, y quarto preview sin nombre de archivo muestra la vista previa del sitio entero. El dashboard se vuelve una de sus páginas:

project:
  type: website
1  render:
    - index.qmd
    - london.qmd
    - london-dashboard.qmd
website:
  title: "Visit London"
  navbar:
    left:
      - {text: Guide, href: london.qmd}
      - {text: Dashboard, href: london-dashboard.qmd}
2      - {text: Downloads, menu: [...]}
1
Una lista render explícita evita que el README, las notas de los datos y los créditos de las fotos se vuelvan páginas del sitio.
2
El menú enlaza los archivos que escribieron los otros formatos: la guía en Word, el PDF, el folleto y los archivos opcionales que hayas hecho.

.gitignore gana una línea, para el sitio renderizado, _site/, que se reconstruye desde la fuente y se publica aparte (Sección 9.4). El resto de la lista está ahí desde que empezaste la carpeta (Sección 6.2): el entorno .venv/ (que se reconstruye desde uv.lock), los archivos de trabajo de Quarto y las salidas renderizadas junto a las fuentes. index.qmd se convierte en la página de inicio del sitio, index.html, la que ve quien visita la dirección del sitio.

ImportantePruébalo

Convierte la carpeta en un sitio web y reinicia la vista previa.

Terminaste cuando el sitio abre con Guide, Dashboard y Downloads en su barra de navegación, y cada enlace de Downloads abre su archivo.

9.4 Publicar

Antes de pegar el prompt siguiente, reemplaza <your-github-username> por tu nombre de usuario de GitHub (el agente puede averiguarlo con gh api user si se lo pides).

Pídele a tu agente
Si esta carpeta aún no es un repositorio de Git, ejecuta `git init -b main`; comprueba que .gitignore cubra _site/, .quarto/, .venv/, *_files/, *.quarto_ipynb, london*.html, *.docx, *.pdf, *.pptx y *.epub. Reemplaza el README.md de esta carpeta por uno corto, en inglés, que enlace a https://<your-github-username>.github.io/london-guide/ y enumere los archivos del menú Downloads del sitio. Haz commit de él junto con el trabajo que aún no tenga commit (nada de lo que .gitignore deja afuera), luego crea con gh un repositorio público de GitHub llamado `london-guide` y haz push de `main` a él. Fija el sitio web del repositorio en la misma URL con `gh repo edit --homepage`. Muéstrame el README y la URL que configuraste.
Probablemente ejecute

git status · git commit · gh repo create london-guide … · gh repo edit --homepage …

Tú haces

apruebas gh · en la pestaña de la vista previa: Ctrl+C, luego uv run quarto publish gh-pages y Enter · abres la dirección en tu teléfono

El agente crea el repositorio en GitHub a partir de tu carpeta con gh repo create london-guide --public --source=. --push, que también sube los commits, usando la sesión iniciada en la comprobación de la preparación. Con ellos va cada commit que hiciste desde que empezaste la carpeta, así que el repositorio en GitHub abre con todo el historial de la guía, un paso revisado a la vez. Su README es lo primero que ven quienes visitan el repositorio, y su enlace los lleva al sitio en vivo.

La primera publicación es tuya, escrita en la terminal. Detén antes la vista previa: la publicación renderiza el sitio entero, y dos renderizados en una carpeta chocan. Hace una sola pregunta, “Publish site … (Y/n)”, que Enter responde que sí; luego renderiza el sitio, crea la rama gh-pages, sube el sitio renderizado y lo abre. La guía de GitHub Pages de Quarto dice que ejecutes quarto publish gh-pages en tu computadora, una vez, antes de configurar una GitHub Action para publicar (consultada el 2026-11-12). Haz también interactiva esa primera ejecución: en una prueba con Quarto 1.6.40, --no-prompt detuvo la primera publicación con “the remote origin does not have a branch named gh-pages” (el remoto origin no tiene una rama llamada gh-pages). Eso se observó con 1.6.40 y no se volvió a probar con 1.10.20. Una vez que existe la rama, el agente puede actualizar el sitio con uv run quarto publish gh-pages --no-prompt.

En esa prueba, la primera publicación de cada sitio tardó entre un minuto y medio y dos minutos, y luego GitHub Pages lo construyó en 20 a 35 segundos, así que una página 404 en el primer minuto suele significar que el sitio todavía se está desplegando.

AdvertenciaError frecuente

Un push que falla con HTTP 400 (“RPC failed”, “the remote end hung up unexpectedly”) se vio con sitios más grandes, como dashboards con mapas incrustados. Aumenta el búfer de Git para este repositorio con git config http.postBuffer 524288000 y vuelve a hacer push.

TipEn la práctica

Publicar desde tu propia computadora es simple y mantiene la construcción donde está tu entorno. La alternativa, una GitHub Action que renderiza en cada push (quarto-dev/quarto-actions, de Quarto), necesita Python y los paquetes del proyecto instalados en el trabajo, o freeze configurado para que se reutilicen los resultados guardados en el repositorio, y la guía de Quarto igual pide un primer quarto publish gh-pages en tu computadora.

ImportantePruébalo

Publica la guía.

Terminaste cuando https://<your-github-username>.github.io/london-guide/london-dashboard.html se abre en tu teléfono.

¿Dos minutos sin avanzar? Pega esto en tu agente. Respalda tu trabajo y lleva el proyecto hasta este punto; luego sigue leyendo desde aquí.

Catch me up: follow ../quarto-workshop/examples/london/README.md

9.5 Cambia un dato de entrada, explica la reconstrucción

El Capítulo 1 empezó con una corrección (Sección 1.1): ALVA revisa una cifra y, en un flujo de copiar y pegar, alguien tiene que llevarla a mano a cada archivo que la cita. Aquí está ese escenario de verdad, en un proyecto en el que nunca se copió ningún conteo de visitantes. Hiciste el mismo movimiento a menor escala con el primer informe (Sección 5.5) y predijiste uno para los tres primeros formatos de la guía (Sección 7.5); ahora abarca cada página. No viene ningún prompt: escribe el tuyo, o hazlo a mano. Haz tú la edición de los datos, por ejemplo con nano data/attractions.csv (Ctrl+O, Enter, Ctrl+X): las reglas del proyecto mantienen al agente fuera de data/, que es justamente su propósito.

ImportantePruébalo
  1. Predice. Cambia el visits_2025 de la Tower of London en data/attractions.csv a 8000000. ¿Qué salidas van a cambiar? Anótalo antes de seguir leyendo.
  2. Reconstruye: detén la vista previa y luego ejecuta uv run quarto render.
  3. Explica qué salidas cambiaron, cuáles no y por qué.
  4. Deshaz el cambio con git restore data/attractions.csv, y luego reconstruye.

Terminaste cuando puedes nombrar las salidas que cambiaron, las que no, y la línea de código que conecta cada salida que cambió con el dato de entrada.

El valor es ficticio: elegido para que cambie la atracción más visitada, de modo que el efecto se vea, y reversible, porque el archivo real tiene commit desde que lo copiaste (Sección 6.8). git restore devuelve un archivo a como estaba en el último commit, y la segunda reconstrucción no deja ningún número de prueba en tus archivos.

Revisa tu predicción

Para revisarla, necesitas saber qué página lee qué dato de entrada. La Tabla 9.3 se calcula a partir de las fuentes del proyecto terminado, páginas opcionales incluidas: una página cuenta como lectora de un archivo solo si su código lo carga.

Tabla 9.3: Qué página del proyecto de Londres terminado (cada una, un archivo .qmd) lee qué archivo de data/, y los formatos que escribe. Calculado a partir de las fuentes: una marca significa que el código de la página carga el archivo.
Página Escribe attrac­tions visits churches sights
london html, docx, pdf, pptx, epub, diapositivas ●
london-dashboard html ● ● ●
london-email docx ●
london-flyer pdf
london-social pdf ●
london-whitepaper pdf ● ●

En total, cinco páginas cargan attractions.csv, y entre todas escriben diez archivos, así que el cambio llega a todos ellos en el siguiente renderizado.

Lo que hace ahí depende del código de cada página. De esas páginas, tres (la guía, el dashboard y el informe para socios) encuentran la atracción más visitada con attractions["visits_2025"].idxmax() y el total con .sum(), así que en cada una la Tower of London pasa a ser la atracción más visitada y el total sube. El anuncio cuadrado usa solo la primera llamada, así que también nombra a la Tower.

El documento técnico no nombra ninguna atracción más visitada: sus sumas por tipo de entrada cambian, pero su tabla conserva la columna rank_uk de ALVA tomada del archivo, que seguiría ubicando a la Tower en el noveno puesto del Reino Unido al lado de la mayor cantidad de visitas de las diez. Una columna copiada también queda vieja. Aun así, eso responde la pregunta con la que empezó el Capítulo 1: la corrección llega a diez archivos con un solo comando, y nadie tiene que salir a buscarlos.

Las copias merecen una segunda mirada. El folleto no carga ningún dato, y las tablas de atracciones de la guía y del informe para socios están escritas a mano, aunque los créditos de la guía nombran sights.csv: las tres copian sus datos (rangos de precio, estaciones más cercanas) del archivo citado al Markdown. Fue una decisión razonable, porque esos datos cambian poco, pero significa que una corrección en sights.csv no actualiza ninguna de ellas. Una copia citada sigue siendo una copia.

NotaPor qué funciona

¿Por qué se vuelve a calcular cada página, incluso las que no cambiaron su fuente? Porque el proyecto conserva el comportamiento por defecto de Quarto, freeze: false: cada renderizado vuelve a ejecutar el código de cada página, lo que mantiene simple la respuesta de este ejercicio. Con el caché activado, una página cuya fuente no cambió conservaría sus números viejos, y la respuesta dependería del caché; el Capítulo 23 vuelve sobre esa disyuntiva.

Hay dos cosas más que no cambian: el sitio en vivo, hasta que vuelvas a publicar (uv run quarto publish gh-pages --no-prompt), y cualquier salida que no reconstruiste. Las respuestas modelo, con las preguntas de seguimiento que vale la pena hacerse, están en el Apéndice E.

9.6 Un documento técnico (opcional)

Los mismos datos también se pueden convertir en un artículo académico: un resumen, secciones numeradas, resultados calculados y una lista de referencias, con la tipografía que usan los documentos de LaTeX, sin instalar LaTeX.

Pídele a tu agente
Crea london-whitepaper.qmd, un documento técnico A4 de Typst en inglés, con la tipografía "New Computer Modern": un resumen (sin código en línea), Introduction, Methods, Results y Conclusions numeradas, y luego References mediante `#set bibliography(title: [References])` (references.bib a partir de `url`). Analiza data/visits.csv frente a 2019 y data/attractions.csv según `admission`. Agrégalo a `render` y al menú "Downloads"; renderiza; revisa las citas. Las figuras tienen que ser vectoriales: fija `fig-format: svg` y comprueba que los archivos de `figure-typst/` terminen en .svg.
bibliography: references.bib
format:
  typst:
1    mainfont: "New Computer Modern"
2    section-numbering: "1.1"
3    bibliographystyle: ieee
4    fig-format: svg
1
Typst 0.15, que viene con Quarto 1.10.20, incluye New Computer Modern, la versión OpenType de la Computer Modern de LaTeX, así que el documento parece un artículo de LaTeX sin una instalación de TeX.
2
Numera los títulos: 1, 1.1, 2.
3
El estilo de referencias numeradas de Typst; [@key] en el texto cita una entrada de references.bib.
4
Las figuras vectoriales se ven nítidas con cualquier zoom; la comprobación del prompt se asegura de que de verdad sean vectoriales.
La primera página de un documento A4 en inglés, con una tipografía de estilo LaTeX: el título Visits to London's leading ALVA member attractions, 2015 to 2025, el subtítulo Pandemic loss and recovery: a descriptive analysis, el autor London Tourism Office, un resumen y las secciones 1, Introduction, y 2, Methods, con citas numeradas entre corchetes.
Figura 9.3: La primera página del documento técnico de Londres terminado: título, resumen y secciones numeradas con citas. Renderizado desde examples/london/london-whitepaper.qmd.
AdvertenciaError frecuente

Tres trampas, todas encontradas al construir el ejemplo. La configuración del documento necesita Quarto 1.10 o más reciente: el Typst de Quarto 1.6.40 la rechaza con “unexpected argument: spacing”. Una expresión en línea en un abstract del YAML se ejecuta antes de la celda de preparación y falla, así que el ejemplo terminado escribe su resumen en el cuerpo, en un bloque de Typst sin procesar. Y Typst imprime su propio título encima de la lista de referencias, “Bibliography” por defecto, que el prompt cambia con #set bibliography(title: [References]) para que el documento no necesite un título References propio.

También hay disponible un PDF de LaTeX auténtico, como format: pdf, pero necesita una distribución de TeX, por ejemplo quarto install tinytex. Para la mayoría de los informes, Typst es más rápido y más simple.

Resumen

  • Hacer push copia tus commits a GitHub; un pull request muestra un diff para que otra persona lo revise antes de que cuente.
  • Un sitio construido son archivos estáticos: súbelos, o deja que un servicio los construya.
  • Un _quarto.yml con una lista render convierte una carpeta en un sitio web.
  • El primer quarto publish gh-pages es tuyo; las actualizaciones siguientes pueden ser del agente.
  • Un dato de entrada que cambia llega a cada página cuyo código lo carga; las copias y el sitio en vivo, no.

Con eso se completa una guía para muchos públicos. En el análisis del agua, lo difícil es el análisis mismo: agrupar las zonas municipales de Colombia en tipos según la calidad del agua, los servicios y el contexto. Ese único análisis se publica luego como informe, diapositivas, entrada de blog y sitio web, todos leyendo los resultados de un solo script, y su prueba de reconstrucción cambia una opción del análisis en lugar de un número de una tabla.

Lecturas adicionales