Quarto: un proyecto, muchas salidas

Taller práctico · de cero a GitHub Pages en 60 minutos

Diego Villalba

2026-09-01

Un archivo. Una hora. Un sitio publicado.

Lo que construiremos hoy

Al terminar tendrás un miniportafolio profesional que:

• combina texto, código Python y resultados;
• se previsualiza mientras escribes;
• puede convertirse a HTML, PDF y otros formatos;
• vive en una URL pública de GitHub Pages.

Evidencia final

Una persona abre tu enlace y entiende en menos de un minuto:

1. qué problema resolviste;
2. cómo lo analizaste;
3. qué resultado obtuviste.

No abrir con una definición. Enseñar primero el resultado esperado y, si es posible, una versión ya publicada. Preguntar: «¿Quién ha sufrido pegando gráficas de un notebook a Word o PowerPoint?». Esta pregunta crea el problema que Quarto resuelve.

La ruta de los próximos 60 minutos

Encuadre0–5 min

Entorno5–13 min

Primer .qmd13–22 min

Sitio22–32 min

Python32–42 min

Formatos42–50 min

Publicar50–60 min

Regla del taller: primero hacemos que funcione; después lo hacemos bonito.

Explicar que todos, incluido quien imparte, seguirán la misma ruta. Los tiempos son límites: cuando termina un bloque se usa el material preparado y se sigue adelante.

Cómo sabremos si podemos avanzar

Listo

Voy
cerca

Necesito
apoyo

Verde

Muestra tu pantalla y ayuda a alguien cercano.

Amarillo

Compara comandos y rutas con tu pareja.

Rojo

Usa proyecto-demo/ y vuelve al flujo común.

No depurar una computadora frente a todo el grupo. En rojo, copiar el proyecto demo y continuar. Recuperar los casos individuales al final.

1 · Prepara tu entorno

5–13 min · cuatro piezas y una verificación

Quarto no reemplaza a Python ni al editor

EditorVS Code + extensión Quarto

→

Quarto CLIconvierte y organiza

→

Python + Jupyterejecuta el análisis

→

Git + GitHubversiona y publica

Idea clave: Quarto es una aplicación independiente. No se instala con pip. Python solo es necesario cuando el documento ejecuta código Python.

Instalación: Windows y macOS

Pieza	Windows	macOS
Quarto	instalador .msi	instalador .pkg
Python 3	python.org · activar Add to PATH	python.org o Homebrew
Editor	VS Code + extensiones Quarto y Python	igual
Git	Git for Windows	Xcode CLT o instalador de Git

Descargas oficiales: Quarto · Python · VS Code · Git

Idealmente estas descargas ocurren antes de la sesión. En Windows, evitar la Microsoft Store si crea aliases confusos. No instalar TinyTeX todavía: se mostrará al hablar de PDF.

Un entorno Python por proyecto

Windows · PowerShell

PowerShell

py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install jupyter pandas matplotlib

macOS · Terminal

Terminal

python3 -m venv .venv
source .venv/bin/activate
python -m pip install jupyter pandas matplotlib

Cuando aparezca (.venv) al inicio de la terminal, estás dentro del entorno.

Checkpoint 1 · la máquina responde

Terminal

quarto --version
python --version
python -m jupyter --version
git --version
quarto check

Avanzamos cuando: quarto, python, jupyter y git muestran una versión. No es necesario que todos tengan la misma versión.

Si python no existe en macOS, probar python3; si falla en Windows, probar py. quarto check puede emitir advertencias no críticas. Buscar la marca de Quarto y Jupyter.

2 · Escribe tu primer documento

13–22 min · de texto plano a página web

El modelo mental de Quarto

FuenteMarkdown + YAML + código
.qmd

→

Quartocoordina ejecución y conversión

→

Pandoctransforma el documento

→

SalidaHTML · PDF · DOCX · slides

El archivo fuente es texto legible, versionable y reutilizable. La salida es desechable: se puede regenerar.

Crea index.qmd

index.qmd

---
title: "Mi portafolio de datos"
author: "Tu nombre"
format: html
---

# Un problema que vale la pena resolver

Este proyecto busca **explicar un hallazgo**, no solo mostrar código.

## Pregunta

¿Qué cambió y por qué importa?

Las líneas entre --- son YAML; el resto es Markdown.

Usar las flechas para revelar primero metadata, luego título y después contenido. Pedir que personalicen título, autor y pregunta: así cada trabajo deja de ser idéntico.

YAML: configuración legible

_quarto.yml

project:
  type: website

website:
  title: "Mi portafolio"
  navbar:
    left:
      - index.qmd
      - analisis.qmd

format:
  html:
    theme: cosmo
    toc: true

1

project decide cómo se organiza el conjunto de archivos.

2

website define navegación e identidad del sitio.

3

format controla cómo se ve y qué produce.

Hacer clic en 1, 2 y 3. Aclarar: espacios, no tabuladores; el nivel de indentación expresa jerarquía. _quarto.yml aplica al proyecto; el YAML de un .qmd aplica al archivo.

¿Quién manda? La configuración se combina

Proyecto

_quarto.yml

Valores compartidos por todos los documentos.

Documento

YAML al inicio de analisis.qmd

Excepciones para una página.

Comando

quarto render --to pdf

Elección puntual al compilar.

Piensa en valores generales → ajustes locales → orden de esta ejecución.

Checkpoint 2 · previsualiza mientras escribes

Terminal

quarto preview index.qmd

1. Se abre el navegador.
2. Cambia una frase en index.qmd.
3. Guarda con Ctrl + S o ⌘ + S.
4. La página se actualiza.

Avanzamos cuando: puedes señalar qué parte es YAML, cuál es Markdown y cuál es la salida HTML.

3 · Convierte el documento en sitio

22–32 min · estructura, navegación y vista previa

De cero a proyecto en cuatro comandos

Terminal

quarto create project website mi-portafolio
cd mi-portafolio
code .
quarto preview

mi-portafolio/
├── _quarto.yml   # configuración compartida
├── index.qmd      # portada
├── about.qmd      # segunda página
└── styles.css    # detalles visuales

Quarto crea una base funcional. Si alguien ya creó la carpeta, trabajar dentro de ella y copiar los archivos de proyecto-demo. No detenerse en CSS durante el taller.

Configura identidad y navegación

_quarto.yml

project:
  type: website

website:
  title: "Mi portafolio de datos"
  navbar:
    left:
      - href: index.qmd
        text: Inicio
      - analisis.qmd

format:
  html:
    theme: cosmo
    toc: true
    code-copy: true

Guarda el archivo: quarto preview detecta el cambio y reconstruye el sitio.

Añade una página con intención

analisis.qmd

---
title: "Análisis"
---

## Pregunta de negocio

¿En qué mes debemos preparar más inventario?

## Datos y método

Describe aquí la fuente, los supuestos y el criterio.

Checkpoint 3

• La barra muestra Inicio y Análisis.
• Ambos enlaces abren.
• El título identifica tu proyecto.

4 · Haz que Python cuente la historia

32–42 min · código, resultados y decisiones editoriales

Una llave cambia todo

Solo mostrar código

analisis.qmd

```python
ventas = [18, 24, 31, 27]
max(ventas)
```

No se ejecuta.

Ejecutar código

analisis.qmd

```{python}
ventas = [18, 24, 31, 27]
max(ventas)
```

Las llaves {python} activan Jupyter.

Código + opciones de celda + resultado

analisis.qmd

```{python}
#| label: fig-ventas
#| fig-cap: "Ventas mensuales (datos ficticios)."
#| echo: true
import matplotlib.pyplot as plt

meses = ["Ene", "Feb", "Mar", "Abr"]
ventas = [18, 24, 31, 27]

plt.bar(meses, ventas, color="#4285F4")
plt.ylabel("Unidades")
plt.show()
```

Resultado

Ene

18

Feb

24

Mar

31

Abr

27

Ventas mensuales (datos ficticios).

Avanzar con las flechas: primero delimitadores y opciones, luego datos, finalmente gráfica. Las opciones #| pertenecen a Quarto, no a Python.

Controla qué ve tu audiencia

Opción	Úsala cuando…	Valor típico
echo	decides si mostrar el código	true / false
output	decides si mostrar el resultado	true / false
warning	limpias ruido técnico	false
fig-cap	la gráfica necesita contexto	texto breve
code-fold	el sitio debe ser legible y auditable	true

_quarto.yml

execute:
  warning: false

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

Checkpoint 4 · del cálculo a la conclusión

Antes

Escribe una pregunta que pueda responderse con tus datos.

Durante

Ejecuta una celda y conserva solo el código que aporta confianza.

Después

Escribe una oración: “Esto sugiere que…”

Avanzamos cuando: la página muestra un resultado y una interpretación, no solo código.

5 · Un mismo contenido, varias salidas

42–50 min · formato no es lo mismo que tipo de proyecto

La fuente permanece; cambia el contenedor

Proyecto
Quarto.qmd + YAML + código

🌐 HTML / sitio

📄 PDF

📝 Word / DOCX

🎞 Reveal.js

No copies y pegues el análisis. Renderiza otra presentación del mismo análisis.

Un documento, tres formatos

reporte.qmd

---
title: "Reporte ejecutivo"
format:
  html:
    code-fold: true
  pdf:
    toc: true
  docx: default
---

Terminal

quarto render reporte.qmd            # todos los formatos del YAML
quarto render reporte.qmd --to pdf   # solo PDF
quarto render reporte.qmd --to html  # solo HTML

Un mismo párrafo, distinto según el formato

reporte.qmd

::: {.content-visible when-format="html"}
Explora la gráfica interactiva:
pasa el cursor sobre cada punto.
:::

::: {.content-visible when-format="pdf"}
Figura 3 muestra la distribución
completa (ver Anexo A).
:::

No dupliques el documento. Marca qué bloque pertenece a cada salida.

• Figuras interactivas en HTML, estáticas en PDF.
• Texto técnico para revisión, texto simple para difusión.
• Un quarto render mantiene ambas versiones sincronizadas.

Mostrar que when-format acepta cualquier formato declarado en el YAML. Útil cuando la misma fuente atiende a públicos distintos sin mantener dos archivos separados.

Tipo de proyecto ≠ formato de salida

Tipo de proyecto	Organiza	Salidas habituales
default	reportes independientes	HTML, PDF, DOCX
website	navegación, páginas, blog	sitio HTML
book	capítulos, índice, referencias	libro HTML, PDF, EPUB
manuscript	artículo + notebooks + revisión	HTML, PDF, DOCX

project.type define la estructura. format define la representación. Un libro HTML también es un sitio navegable.

El mismo proyecto puede ser un libro

_quarto.yml

project:
  type: book

book:
  title: "Proyecto profesional"
  chapters:
    - index.qmd
    - analisis.qmd
    - conclusiones.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub: default

Para practicar sin editar en vivo, abre proyecto-demo/_quarto-book.yml.

Divide un documento largo en piezas reutilizables

proyecto/
├── reporte.qmd  # ensambla todo
└── secciones/
    ├── intro.qmd
    ├── metodologia.qmd
    └── resultados.qmd

reporte.qmd

# Reporte del proyecto

{{< include secciones/intro.qmd >}}
{{< include secciones/metodologia.qmd >}}
{{< include secciones/resultados.qmd >}}

Cada sección vive en su propio archivo; reporte.qmd solo las ordena.

Por qué importa: varias personas editan secciones distintas sin pisarse el trabajo en un mismo archivo, y cada sección se puede previsualizar sola.

PDF requiere un motor adicional

Terminal

quarto install tinytex
quarto render reporte.qmd --to pdf

Durante el taller

Si TinyTeX aún se descarga, continúa con HTML. La instalación puede terminar después.

Para entregar

Genera PDF al final y revisa saltos de página, figuras y referencias.

No iniciar la instalación masiva si el tiempo o la red son limitados. Quarto recomienda TinyTeX; la salida HTML no necesita TeX. Mostrar un PDF ya renderizado como respaldo.

6 · Publica en GitHub Pages

50–58 min · de localhost a una URL compartible

Primero: guarda la historia del proyecto

Terminal

git init
git add .
git commit -m "Crea portafolio con Quarto"
git branch -M main
git remote add origin https://github.com/USUARIO/mi-portafolio.git
git push -u origin main

Antes de git add ., confirma que .venv/, .quarto/ y _site/ estén en .gitignore. Nunca publiques contraseñas, tokens ni archivos .env.

La ruta corta: quarto publish

.gitignore

/.venv/
/.quarto/
/_site/

Terminal

quarto publish gh-pages

Quarto:

1. renderiza el proyecto;
2. crea o actualiza la rama gh-pages;
3. la envía a GitHub;
4. muestra la URL publicada.

La primera publicación puede pedir confirmación. Para un repositorio de proyecto, GitHub suele detectar gh-pages. En un sitio de usuario puede requerirse elegir esa rama en Settings → Pages. Verificar que estamos en main, no en gh-pages.

Qué ocurre después de git push

Tu equipofuentes .qmd

→

GitHubhistorial en main

→

RenderQuarto produce HTML

→

PagesURL pública

Después puedes automatizar el paso amarillo con GitHub Actions. Hoy priorizamos una primera publicación controlada.

Checkpoint 5 · prueba como visitante

Abre https://USUARIO.github.io/mi-portafolio/ en una ventana privada.

Abre

La URL carga sin iniciar sesión.

Navega

No hay enlaces rotos.

Explica

La portada dice qué problema resolviste.

Atribuye

Aparecen tu nombre y contacto.

Publicado no significa terminado: significa que ya puedes recibir retroalimentación real.

7 · Cierra y vuelve a publicar

58–60 min · el flujo profesional en seis verbos

El ciclo que usarás en tu proyecto

1 · Preguntadefine una decisión

→

2 · Analizacódigo reproducible

→

3 · Explicatexto + evidencia

→

4 · Renderizaformato adecuado

La rutina diaria

quarto preview
git add .
git commit -m "Explica el hallazgo principal"
git push
quarto publish gh-pages

Cinco ideas que deben sobrevivir a la hora

1. .qmd reúne narrativa, configuración y código.
2. _quarto.yml comparte decisiones para todo el proyecto.
3. quarto preview acorta el ciclo escribir → ver → corregir.
4. Una fuente puede generar varias salidas sin copiar y pegar.
5. GitHub Pages convierte el resultado en una evidencia profesional pública.

Ticket de salida: pega tu URL o escribe el único comando que todavía te bloquea.

Apéndice · para quien imparte

Material de respaldo; no forma parte del reloj de 60 minutos

Si algo falla, diagnostica por capas

Síntoma	Comprueba	Salida rápida
quarto: command not found	instalación + reiniciar terminal	abrir VS Code de nuevo
python no existe	py en Windows / python3 en macOS	recrear .venv
No module named jupyter	entorno activo	python -m pip install jupyter
YAML no compila	indentación con espacios	pegar el YAML mínimo
PDF falla	quarto list tools	entregar HTML y revisar TinyTeX
Pages da 404	rama y Settings → Pages	esperar 1–3 min y recargar

Automatización opcional con GitHub Actions

Ejecuta primero quarto publish gh-pages una vez. Después crea:

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: [main]

name: Quarto Publish
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Descargar repositorio
        uses: actions/checkout@v7
      - name: Instalar Quarto
        uses: quarto-dev/quarto-actions/setup@v2
      - name: Renderizar y publicar
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

En Settings → Actions → General → Workflow permissions, habilita lectura y escritura. Si el workflow ejecutará Python, también debe instalar Python y requirements.txt.

Atajos para presentar estas diapositivas

Navegar

→ siguiente paso · ← anterior · Esc mapa.

Enseñar código

Las líneas resaltadas cambian con →. Haz clic en los números de anotación.

Acompañar

S abre notas del presentador · B pausa · C pizarrón.

Recursos oficiales para continuar

• Primeros pasos con Quarto
• Proyectos Quarto
• Python y Jupyter
• Presentaciones Reveal.js
• Publicar en GitHub Pages

El mejor siguiente paso no es aprender todas las opciones: es publicar una historia breve con datos reales.