Publicación: GitHub Pages, Netlify, QuartoPub

quarto
reproducibilidad
Tres caminos para poner un sitio Quarto online. GitHub Pages como default open-source, Netlify para configuración custom y dominios, QuartoPub para preview rápida. Pros, contras y los detalles de configuración.

Tres rutas

Plataforma Cuándo Pros Contras
GitHub Pages Sitio open, hospedaje gratis Simple, gratis, ilimitado Solo HTTPS via *.github.io. Dominio custom requiere config
Netlify Sitio profesional, dominio propio Build automático en push, dominios, formularios, redirects Free tier con límites. Configuración inicial más larga
QuartoPub Drafts, prototipos Un comando, instant publish Limitado a sitios pequeños, no es para producción

Para 80 % de los casos serios, Netlify. Para libros open + colaboración con GitHub, GitHub Pages. Para mostrar algo a un cliente rápidamente, QuartoPub.

Antes de publicar: lo que pasa al renderizar

Quarto renderiza tu proyecto a la carpeta _site/ (websites) o _book/ (libros). Es lo que vas a publicar, HTML, CSS, JS, imágenes ya generados.

quarto render

Después de esto, _site/ (o _book/) tiene todo lo necesario. Las tres rutas de publicación difieren en cómo sirven esos archivos.

Ruta 1: GitHub Pages

Setup inicial

  1. Tu proyecto vive en un repo de GitHub.
  2. Configura GitHub Pages del repo para servir desde la rama gh-pages.
  3. Renderiza y publica con Quarto.
quarto publish gh-pages

Quarto:

  • Renderiza el proyecto.
  • Crea (o actualiza) la rama gh-pages con el output.
  • Pushea esa rama.
  • Te da la URL: https://usuario.github.io/repo/.

La primera vez te pregunta si quieres confirmar. Después de eso es quarto publish gh-pages y listo.

CI automático con GitHub Actions

Para que cada push a main regenere y publique:

# .github/workflows/publish.yml
on:
  push:
    branches: main
  workflow_dispatch:

name: Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
          render: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Con esto, push a main → CI renderiza → push a gh-pages → sitio actualizado. Tres minutos sin tocar nada.

Si tu render necesita R o Python

Añadir setup al workflow:

      - name: Set up R
        uses: r-lib/actions/setup-r@v2

      - name: Set up R dependencies
        uses: r-lib/actions/setup-renv@v2

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

Para R, renv es la solución estándar (lo vemos en el siguiente tutorial). Sin renv, el CI no sabe qué paquetes instalar.

Alternativa más simple: usa freeze: auto y commit _freeze/, el CI no necesita ejecutar R/Python, solo renderiza desde los outputs pre-computados. Patrón ideal para sitios donde R es solo para el análisis local.

Ruta 2: Netlify

Setup inicial

  1. Cuenta en netlify.com.
  2. Conecta tu repo de GitHub.
  3. Configura el build:
    • Build command: quarto render
    • Publish directory: _site (o _book para libros)

Netlify detectará pushes a main y disparará builds automáticos.

_site ya generado vs Netlify renderizando

Dos modos de uso:

A) Netlify renderiza (necesita Quarto + R/Python en CI):

# netlify.toml en raíz del repo
[build]
  command = "quarto render"
  publish = "_site"

[build.environment]
  QUARTO_VERSION = "1.5.57"

Netlify instala Quarto y ejecuta el render. Si tu sitio necesita R/Python, configura también en netlify.toml. Funciona pero el build es más lento (5-10 minutos cada vez).

B) Tú renderizas localmente, Netlify solo sirve estáticos:

[build]
  command = "echo 'Site already built'"
  publish = "_site"

Renderizas con quarto render localmente, commiteas _site/ (o usas _freeze/ + freeze auto), Netlify solo sirve. Build instantáneo, pero requiere disciplina al commitear.

Para proyectos donde el render lleva minutos, B es mejor. Para sitios sencillos, A.

Dominio custom

Netlify hace esto bien y sencillo:

  1. En la dashboard del sitio: Domain management → Add custom domain.
  2. Sigue las instrucciones para configurar DNS.
  3. SSL/HTTPS automático con Let’s Encrypt.

Funciona con tu dominio comprado en cualquier registrar.

Otras features útiles de Netlify

  • Formularios: sin backend, Netlify captura submissions de formularios HTML.
  • Redirects y rewrites en _redirects o netlify.toml.
  • Deploy previews: cada PR genera una preview URL temporal.
  • Branch deploys: branches alternativas (develop, staging) sirven en URLs separadas.

Es la elección más completa para sitios profesionales. Free tier suficiente para tráfico bajo-medio.

Ruta 3: QuartoPub

QuartoPub es el servicio de hosting propio de Quarto (de Posit). Diseñado para publicar rápido sin configurar nada.

quarto publish quarto-pub

La primera vez:

  1. Te pide login con email.
  2. Renderiza y sube.
  3. Te da una URL https://usuario.quarto.pub/proyecto/.

Después es instantáneo:

quarto publish quarto-pub

Renderiza local, sube, listo en 30 segundos.

Cuándo merece la pena

  • Prototipos: mostrar algo a un cliente sin setup.
  • Drafts: iterar rápido con un colega.
  • Slides: presentaciones Quarto con URL compartible.

Cuándo no

  • Sitio público con tráfico real (no es plan de pago serio).
  • Dominio custom (no se soporta).
  • SEO (no se controla bien).
  • Cualquier libro o sitio que vaya a perdurar.

QuartoPub es la “Heroku free tier” del mundo Quarto. Útil para lo que es, no para producción.

Otros destinos

Quarto soporta más targets:

quarto publish posit-cloud         # Posit Cloud (gratis con límites)
quarto publish connect             # Posit Connect (corporativo)
quarto publish confluence          # Confluence (corporativo Atlassian)

posit-connect es lo que muchas empresas usan internamente. Si tu organización paga Posit Connect, es la mejor opción: hosting privado, autenticación, scheduled re-renders, integración con SSO corporativo.

Workflow recomendado

Para un sitio público open-source:

  • Repo en GitHub.
  • freeze: auto, commit _freeze/.
  • GitHub Actions con quarto publish gh-pages automático en push a main.
  • Si quieres dominio custom, configurar GitHub Pages con CNAME.

Para un sitio profesional con dominio:

  • Repo en GitHub.
  • Netlify conectado al repo, modo “Quarto renderiza en CI” o “estáticos ya generados”.
  • Dominio configurado en Netlify.
  • Deploy previews automáticas en PRs.

Para un draft que muestras a un cliente esta tarde:

  • quarto publish quarto-pub. URL en 30 segundos.

URL absolutas y SEO

Cuando publicas, asegúrate de que site-url: en _quarto.yml apunta al dominio real:

website:
  site-url: https://misitio.com

Sin esto, los enlaces internos pueden ser relativos pero los de Open Graph (compartir en redes) usarán localhost. Síntoma típico: al pegar el enlace en Slack, la preview aparece rota.

Tracking y analytics

Para Google Analytics o Plausible:

format:
  html:
    include-in-header:
      - file: analytics.html

analytics.html contiene el snippet del proveedor. Quarto lo inyecta en el <head> de cada página.

Para opciones built-in de Quarto:

website:
  google-analytics: "G-XXXXXX"

Trampas habituales

  • site-url apuntando a localhost al publicar. Open Graph y RSS rotos.
  • CI que tarda 10 minutos porque renderiza todo desde cero cada push. Usa freeze: auto + commit _freeze/.
  • .gitignore con _site/ y luego intentar commitearlo. Decide: o renderiza en CI (ignora _site/) o renderiza localmente (commitea _site/). Pero _freeze/ siempre se commitea.
  • GitHub Pages activado en la rama equivocada. Quarto usa gh-pages por defecto, pero hay que activarlo en Settings → Pages del repo apuntando a esa rama.
  • HTTPS no activado en GitHub Pages con dominio custom. En Settings → Pages, marca “Enforce HTTPS”. Sin esto, queda HTTP normal.

En la siguiente entrega

Última entrega de la ruta: reproducibilidad real. Hasta ahora has aprendido a publicar el output. Pero si dentro de tres años alguien quiere regenerar tu análisis y obtener exactamente lo mismo, necesitas más: renv para bloquear versiones de paquetes R, Docker para bloquear el sistema operativo. Lo siguiente.