Quarto

Sistema de publicación científica polilingüe y multi-formato

quarto

publishing

reproducibility

websites

books

slides

parameterized-reports

Catálogo razonado del ecosistema Quarto: documentos, proyectos, webs, libros, presentaciones, informes parametrizados y manuscritos reproducibles, con criterios de uso, alternativas y trampas habituales.

Sobre Quarto

Quarto es el sistema de publicación científica de Posit, sucesor explícito de RMarkdown. Mantiene la filosofía literate programming de Knuth (texto + código + resultados en un único documento fuente) y la arquitectura knitr → pandoc, pero rompe la dependencia exclusiva de R: el mismo .qmd puede ejecutarse con R (vía knitr), Python o Julia (vía Jupyter), e incluso Observable para piezas interactivas. Yihui Xie sigue al frente de knitr. El equipo de Quarto (Carlos Scheidegger, J.J. Allaire y otros) construye encima un front-end uniforme y multi-formato.

Instalación canónica y verificación:

# Quarto es una CLI independiente (no un paquete R).
# Descarga desde https://quarto.org/docs/get-started/
# o vía installers / chocolatey / homebrew.

# Verificación desde R:
quarto::quarto_version()        # versión instalada
quarto::quarto_path()           # binario detectado
system2("quarto", "check")      # diagnóstico completo (R, Python, LaTeX...)

Tres principios que conviene interiorizar antes de tocar nada serio:

Un fuente, muchos formatos. Un .qmd produce HTML, PDF, Word, ePub, slides (reveal.js / beamer / pptx) y libros, cambiando únicamente la sección format: del YAML o del _quarto.yml.
Proyectos sobre documentos sueltos. A partir de tres o cuatro .qmd, salir del documento aislado y declarar un proyecto (_quarto.yml) deja de ser opcional: centraliza formato, navegación, freeze y render.
Polilingüe real. Bloques R y Python conviven en el mismo documento. El engine (knitr o jupyter) se elige por documento o por proyecto. Esto es la diferencia operativa principal frente a RMarkdown.

Esta página cataloga las piezas que componen un flujo Quarto en R. El orden sigue jerarquía conceptual: primero la base (documento, proyecto, freeze), después los formatos de salida (HTML, PDF, slides, libros) y finalmente las aplicaciones avanzadas (informes parametrizados, manuscritos reproducibles).

Quarto Document

El documento Quarto (.qmd) es la unidad mínima de trabajo: un fichero de texto con front matter YAML, prosa en Markdown y chunks de código ejecutable. Es el reemplazo directo del .Rmd y el punto de entrada al resto del ecosistema.

A diferencia de RMarkdown, el motor de ejecución se elige explícitamente (engine: knitr o engine: jupyter). El resto de la pipeline (knitr → markdown intermedio → pandoc → formato final) se mantiene idéntica.

Cuándo usarlo

Cualquier análisis exploratorio, informe puntual, nota técnica o memo que mezcle código y prosa y vaya a producir UN solo fichero de salida. Si el documento es la unidad de trabajo (no parte de una web o de un libro), arranca aquí.

Cuándo NO usarlo

Cuadernos puramente interactivos para ti mismo, sin intención de publicar: un .R con # %% en RStudio / VS Code, o un .ipynb directo, es más ágil.
Aplicaciones interactivas reactivas. Shiny o Streamlit están pensadas para eso. Quarto soporta interactive documents (con Shiny o Observable) pero no es su terreno natural.
Documentos sin código, donde no necesitas reproducibilidad: usar Markdown plano + pandoc, o LaTeX directamente, evita una dependencia.

Conceptos clave

El YAML del front matter controla título, autores, formato(s) de salida y opciones de ejecución. Las opciones de chunk se prefieren en formato #| key: value dentro del bloque, no en el header {r}.
format: html (u otro) puede recibir un sub-bloque con opciones específicas: toc, code-fold, theme, embed-resources…
execute: a nivel de YAML aplica defaults a todos los chunks (echo, warning, cache, freeze).
El engine se autodetecta (R si hay {r}, Jupyter si hay {python} / {julia}). Fíjalo con engine: knitr cuando quieras forzarlo.
Render desde R: quarto::quarto_render("informe.qmd"). Desde CLI: quarto render informe.qmd --to html.

Patrón mínimo

---
title: "Informe trimestral"
author: "A. Navas"
date: today
format:
  html:
    toc: true
    code-fold: true
    embed-resources: true
execute:
  echo: false
  warning: false
---

## Introducción

```r
#| label: fig-ventas
#| fig-cap: "Ventas mensuales"
library(ggplot2)
ggplot(economics, aes(date, unemploy)) + geom_line()
```

El gráfico @fig-ventas muestra...

Trampas habituales

Working directory. Por defecto los chunks se ejecutan con el directorio del .qmd como cwd. Cambia con execute-dir: project cuando trabajes dentro de un proyecto con here::here().
embed-resources: true engorda el HTML. Imprescindible si vas a enviar el fichero por correo o subirlo suelto. Perjudicial si forma parte de una web (duplica CSS/JS en cada página).
Doble fuente para opciones de chunk. {r, echo=FALSE} (estilo RMarkdown) sigue funcionando, pero el estilo #| echo: false es el canónico en Quarto. Mezclar los dos en el mismo documento es ilegible.

Enlaces

Relacionados en esta página

Proyecto Quarto, siguiente paso cuando crecen los documentos.
Freeze y caching, controla qué se re-ejecuta entre renders.

Proyecto Quarto

Un proyecto Quarto es un directorio con un fichero _quarto.yml en la raíz. Desde ese momento, Quarto trata todos los .qmd del árbol como parte de la misma unidad de publicación: comparten configuración por defecto, política de freeze, salida (_site/, _book/) y posibles perfiles (_quarto-prod.yml).

Es el modo de trabajo profesional. Cualquier salida que crezca por encima de uno o dos documentos debería estar en un proyecto.

Cuándo usarlo

Web estática, libro, blog, curso, documentación interna, cualquier output multi-fichero.
Un sólo documento pero con configuración compleja (paths absolutos, perfiles dev/prod, dependencias compartidas).
Equipos: el _quarto.yml versionado en git garantiza que quarto render produce lo mismo en todas las máquinas.

Cuándo NO usarlo

Un único .qmd autocontenido para enviar a un colega. Crear un proyecto añade _quarto.yml + _freeze/ + _site/ y complica el versionado para nada.

Conceptos clave

project: declara type (default, website, book, manuscript) y output-dir (_site por defecto en web, _book en libros).
format: en _quarto.yml se mergea con el del documento individual. El del documento gana en caso de conflicto. Esto permite definir el tema globalmente y permitir overrides locales.
Perfiles (profile:) habilitan combinaciones nombradas: quarto render --profile draft carga _quarto-draft.yml encima del base.
resources: lista ficheros extra (datos, imágenes, descargables) que deben copiarse al output.
quarto render sin argumentos renderiza todo el proyecto. quarto render archivo.qmd renderiza solo uno respetando la config global.

Patrón mínimo

# _quarto.yml
project:
  type: website
  output-dir: _site
  resources:
    - "data/*.csv"

website:
  title: "Notas de análisis"
  navbar:
    left:
      - href: index.qmd
        text: Inicio
      - href: about.qmd
        text: Sobre

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

execute:
  freeze: auto

Trampas habituales

output-dir fuera del proyecto. Si lo apuntas a ../public/, el resources: deja de funcionar como esperas y muchos paths relativos se rompen.
Conflictos entre YAML del proyecto y del documento. Cuando algo no se aplica, la primera comprobación es el merge: el documento puede estar sobrescribiendo silenciosamente. quarto inspect ayuda a verlo.
Renombrar el .qmd raíz. En proyectos book y manuscript el nombre del fichero principal está acoplado a la salida. Renombrar requiere actualizar _quarto.yml y a veces index.qmd se sigue esperando explícitamente.

Enlaces

Relacionados en esta página

Quarto Document, unidad básica que el proyecto agrega.
Website, Book, Manuscript, los tipos concretos de proyecto.

Freeze y caching

freeze y cache son los dos mecanismos que Quarto ofrece para evitar re-ejecutar código innecesariamente. Resuelven problemas distintos y se confunden con frecuencia:

cache (heredado de knitr) memoriza el resultado de un chunk concreto. Útil dentro de un mismo render iterativo.
freeze congela todo el output computacional de un documento entre renders del proyecto. La salida intermedia se guarda en _freeze/ y se versiona en git. Es lo que hace viable publicar una web con análisis pesados sin re-correrlos en cada quarto render.

Cuándo usarlo

freeze: auto por defecto en cualquier web o libro con computación no trivial. Sin esto, regenerar el sitio al cambiar una sola página tipográfica re-ejecuta todo el cómputo del proyecto.
freeze: true (siempre) cuando quieres garantizar que el HTML publicado refleja un análisis fechado y reproducible, útil para releases o entregables firmados.
cache: true por chunk en cómputos largos durante el desarrollo iterativo de un mismo documento.

Cuándo NO usarlo

Documentos pensados para correr en CI con datos actualizados (e.g. dashboards diarios): congelar el output convierte el render en una operación cosmética. Aquí prefiere render manual programado, no freeze.

Conceptos clave

freeze: auto re-ejecuta sólo si el .qmd ha cambiado. freeze: true no re-ejecuta nunca (hay que invalidar a mano borrando _freeze/).
El directorio _freeze/ debe versionarse en git si quieres reproducibilidad real entre máquinas. Excepción: si lo regeneras en CI antes de publicar.
cache: true en chunks requiere identificar dependencias con dependson cuando un chunk depende de otro. En la práctica, conviene mantener los chunks independientes y dejarse llevar.
Invalidar todo: quarto render --no-cache (no toca freeze) o rm -r _freeze/ (sí lo toca).

Patrón mínimo

# _quarto.yml
execute:
  freeze: auto    # re-ejecuta sólo si el .qmd cambió
  cache: false    # cache a nivel de chunk desactivado por defecto

#| label: simulacion-pesada
#| cache: true
#| eval: true
# Forzar cache de chunk pesado durante el desarrollo
res <- simulacion_montecarlo(n = 1e6)

Trampas habituales

_freeze/ no versionado. Lo más común: añadir _freeze/ a .gitignore “por higiene”. Resultado: el primer quarto render en otra máquina re-ejecuta semanas de cómputo.
freeze no captura cambios en datos externos. Si tu .qmd lee data.csv y el csv cambia pero el .qmd no, freeze: auto no detecta nada. Toca invalidar manualmente o cambiar a freeze: false para ese documento.
Cache + variables globales. cache: true no rastrea cambios en objetos creados fuera del chunk. Si el chunk depende de un df definido arriba y df cambia, el chunk cacheado seguirá devolviendo el resultado viejo.

Enlaces

Relacionados en esta página

Proyecto Quarto, freeze se configura habitualmente a nivel de proyecto.

HTML

El formato HTML es el output por defecto y el más completo de Quarto. Soporta callouts, cross-references, código plegable, tabsets, panel layouts, theming basado en Bootstrap 5 (vía bslib), búsqueda y todo el ecosistema de widgets HTML (htmlwidgets, observable, plotly).

Cuándo usarlo

Cualquier informe que vaya a leerse en pantalla (laptop, móvil).
Documentos con gráficos interactivos, tablas filtrables (DT, reactable) o mapas (leaflet).
Single source of truth del que después se puede derivar PDF para impresión.

Cuándo NO usarlo

Documento que va a un comité / journal / regulador que exige PDF. Empieza por PDF y haz HTML secundario.
Lectura offline a largo plazo en archivo institucional: el PDF tiene mejor garantía de fidelidad a 10 años vista.

Conceptos clave

embed-resources: true produce un HTML autocontenido (CSS, JS, imágenes inline). Imprescindible para envío por correo, prohibitivo en webs.
theme: acepta nombre de Bootswatch (cosmo, flatly, darkly) o un fichero .scss propio con variables bslib.
code-fold: true / code-tools: true añaden plegado y botón “ver código”.
toc: con toc-location: left|right|body, toc-depth: para controlar profundidad.
Callouts: ::: {.callout-note}, callout-warning, callout-tip, callout-important. Mejor que > Nota: en blockquotes.

Patrón mínimo

format:
  html:
    theme:
      light: cosmo
      dark: darkly
    toc: true
    toc-location: left
    toc-depth: 3
    code-fold: true
    code-tools: true
    fig-width: 8
    fig-height: 5
    embed-resources: false   # true sólo para envío suelto

Trampas habituales

embed-resources: true en proyecto web. Hace que cada página duplique todo el CSS/JS, el sitio multiplica su peso por N páginas.
Tema dark mode con plots que no lo respetan. ggplot2 no detecta el modo del navegador. Necesitas controlarlo desde el chunk o usar thematic.
Tablas que rompen el ancho. Tablas anchas de kable o gt desbordan el contenedor. Usar .column-page o .column-screen-inset antes que pelearse con CSS.

Enlaces

PDF

Quarto compila PDF a través de LaTeX, normalmente con TinyTeX (distribución mínima de TeX Live mantenida por Yihui Xie). El motor LaTeX por defecto es xelatex, con buen soporte de fuentes del sistema y UTF-8.

Cuándo usarlo

Documentos de archivo definitivo (informes regulados, tesis, papers).
Tipografía clásica y control fino de página, márgenes, headers y footers.
Salida que debe imprimirse con paginación predecible.

Cuándo NO usarlo (alternativas)

HTML siempre que sea lectura digital: hipervínculos vivos, código interactivo, búsqueda. PDF es peor en pantalla.
Documentos colaborativos en revisión activa: Word (format: docx) y posteriormente export-to-pdf desde Word suele funcionar mejor con revisores no técnicos.

Conceptos clave

TinyTeX se instala con quarto install tinytex o tinytex::install_tinytex() desde R. Resuelve la mayoría de instalaciones LaTeX en el portátil sin tocar MiKTeX / MacTeX completos.
pdf-engine: puede ser xelatex (default), lualatex o pdflatex. xelatex es el sensato para español, acentos y fuentes del sistema.
documentclass: acepta article, report, book, scrartcl, scrreprt (KOMA-Script) y cualquier clase personalizada con template:.
include-in-header: y include-before-body: insertan LaTeX bruto cuando el YAML no llega.
mainfont:, monofont:, sansfont: requieren xelatex o lualatex.

Patrón mínimo

format:
  pdf:
    documentclass: scrartcl
    pdf-engine: xelatex
    papersize: a4
    geometry:
      - margin=2.5cm
    fontsize: 11pt
    mainfont: "Source Serif Pro"
    monofont: "Fira Code"
    toc: true
    number-sections: true
    colorlinks: true

Trampas habituales

Paquetes LaTeX que faltan. TinyTeX los instala bajo demanda, pero la primera ejecución de un documento exótico puede tardar. En CI offline esto rompe builds.
Caracteres no soportados por la fuente. Si usas glifos chinos o griegos en mainfont latina, salen como caja. Configura una fallback font con fontfamilyoptions: o usa LuaLaTeX.
Imágenes en tiff o webp. LaTeX las rechaza. Conviértelas a png / pdf antes de incluirlas, o deja que knitr las genere directamente desde el chunk.
Cross-references rotas. @fig-foo requiere #| label: fig-foo y un caption (#| fig-cap: "..."). Sin el caption, el label no se registra.

Enlaces

reveal.js (slides HTML)

reveal.js es el formato de presentaciones HTML de Quarto. Soporta navegación por slides, speaker notes, fragmentos animados, columnas, chalkboard, y exportación a PDF para envío posterior. Cada slide es una sección Markdown nivel ##.

Cuándo usarlo

Charlas técnicas con código en vivo, gráficos interactivos o vídeos embebidos.
Slides que necesitan publicarse en una web (GitHub Pages, Netlify) con URL compartible.
Recibirás preguntas que requieren saltar a slides concretas: reveal.js tiene atajos (tecla o para overview, s para speaker notes) que PowerPoint no iguala.

Cuándo NO usarlo (alternativas)

Audiencia corporativa que va a editarlas en PowerPoint: usa format: pptx desde Quarto y acepta perder algo de control tipográfico.
Presentación con animaciones complejas o transiciones cinematográficas: PowerPoint o Keynote rinden mejor en ese terreno.
Posters académicos: Quarto tiene format: poster (basado en betterposter) o usa posterdown (RMarkdown). reveal.js no es la herramienta correcta.
Beamer (format: beamer) si el contexto académico exige LaTeX puro (proceedings que distribuyen .tex).

Conceptos clave

Cada ## arranca slide nueva. ### es sub-slide vertical (navegable con flecha abajo).
incremental: true revela bullets de uno en uno automáticamente. . . . (tres puntos en línea propia) inserta una pausa manual.
theme: admite los temas de reveal (simple, serif, solarized, dark) o un .scss propio.
Columnas con :::: {.columns} + ::: {.column width="50%"}.
Speaker notes: ::: {.notes}. Visible con s.
Exportar a PDF: añadir ?print-pdf al URL en navegador y guardar como PDF.

Patrón mínimo

Front matter del documento:

title: "Resultados Q4"
format:
  revealjs:
    theme: simple
    incremental: true
    slide-number: true
    chalkboard: true
    code-line-numbers: false

Cuerpo del documento:

## Introducción

- Punto 1
- Punto 2

. . .

Aparición manual tras pausa.

## Resultado principal

(chunk de código R con `#| echo: false` y un `plot(cars)`)

::: {.notes}
Comentar la pendiente positiva y la variabilidad en velocidades altas.
:::

Trampas habituales

Slides que desbordan en vertical. Reveal no auto-shrinkea. Las tablas y bloques largos quedan cortados. Usa ## Slide {.scrollable} o divide en sub-slides.
Imágenes que no caben. fig-width y fig-height controlan el chunk. El slide tiene width: 1050, height: 700 por defecto. Ajusta fig-width: 9 o out-width: "80%".
incremental: true global engorroso. Si solo quieres bullets animados en algunas slides, prefiere ::: {.incremental} puntual en lugar de activarlo global.

Enlaces

Relacionados en esta página

HTML, comparte motor de salida y theming.

Website

project: type: website produce una web estática multi-página con navegación, barra lateral, búsqueda integrada (lunr.js) y listings dinámicos. Es la herramienta natural para portfolios técnicos, documentación de paquetes, sitios de curso y wikis personales.

Cuándo usarlo

Portfolio, blog técnico, sitio de paquete R, documentación interna del equipo.
Cualquier colección de documentos que se beneficie de navegación común, búsqueda y listings.
Reemplazo natural de pkgdown cuando quieres más libertad de diseño.

Cuándo NO usarlo (alternativas)

pkgdown sigue siendo más automático para documentar paquetes R: parsea man/, vignettes y NEWS sin que tú configures nada.
Hugo / Astro / Eleventy si necesitas miles de páginas, taxonomías complejas o velocidad de build en sitios grandes. Quarto es perfectamente capaz hasta ~unos cientos de páginas. Más allá Hugo va más rápido.
MkDocs (con mkdocs-material) si tu output es documentación técnica de software puro sin computación: ecosistema Python más maduro para ese nicho.
Sphinx en entorno Python científico con cross-references densas tipo libro técnico (NumPy, SciPy, etc.).

Conceptos clave

website: define title, navbar, sidebar, page-footer, search.
navbar: con left: y right: para enlaces. sidebar: puede ser global o por sección (con style: docked|floating).
Listings: una página con listing: declara una colección que se popula desde un directorio (contents: posts/*.qmd). Genera índice paginado, ordenable, filtrable.
Búsqueda con search: true (lunr) o Algolia para sitios grandes.
Despliegue: GitHub Pages (quarto publish gh-pages), Netlify (quarto publish netlify), Quarto Pub.

Patrón mínimo

# _quarto.yml
project:
  type: website
  output-dir: _site

website:
  title: "mi-portfolio"
  navbar:
    left:
      - href: index.qmd
        text: Inicio
      - href: posts.qmd
        text: Blog
      - href: about.qmd
        text: Sobre
  page-footer:
    left: "© 2026 A. Navas"

format:
  html:
    theme: cosmo
    toc: true

# posts.qmd
---
title: "Blog"
listing:
  contents: posts
  type: default
  sort: "date desc"
  categories: true
  feed: true
---

Trampas habituales

Listing que no encuentra los posts. contents: es relativo al .qmd que declara el listing, no a la raíz del proyecto. Confundirlo es la causa #1 de listings vacíos.
href: posts/ sin index.qmd dentro: 404. Cada directorio que aparezca en navegación necesita un index.qmd.
embed-resources: true heredado del documento. En un proyecto web, esto multiplica el peso de la salida, desactívalo a nivel de _quarto.yml.

Enlaces

Relacionados en esta página

Proyecto Quarto, la web es un tipo de proyecto.
Blog, variante con énfasis en listings cronológicos.
Book, para colecciones lineales en lugar de en árbol.

Blog

Un blog Quarto es una website con un listing cronológico como página de entrada y posts en posts/. No es un tipo de proyecto separado, sino una variante de website con convenciones.

Cuándo usarlo

Bitácora técnica personal o de equipo, con posts fechados.
Cuando quieres RSS feed, categorías, etiquetas y archivos por año “gratis”.
Sucesor moderno de distill (Posit lo discontinuó tras el lanzamiento de Quarto).

Cuándo NO usarlo (alternativas)

blogdown (Hugo dentro de R) si necesitas un tema Hugo específico ya construido y miles de páginas.
Hashnode, Substack, Medium si lo que quieres es la audiencia, no controlar el render. Quarto produce HTML estático, la distribución es problema tuyo.

Conceptos clave

Posts en posts/<slug>/index.qmd (recomendado), facilita imágenes adjuntas al post.
listing.type: puede ser default, grid, table. grid con image: es el patrón visual típico.
categories: true en el listing genera filtros automáticos por categoría.
feed: true genera index.xml (RSS). feed: full incluye contenido completo, no solo resumen.
Drafts: añade draft: true al front matter del post. Quedan excluidos del render salvo --profile draft.

Patrón mínimo

# index.qmd (página principal del blog)
---
title: "Notas"
listing:
  contents: posts
  sort: "date desc"
  type: grid
  categories: true
  fields: [image, date, title, reading-time, categories]
  feed: true
page-layout: full
---

# posts/2026-05-quarto-tips/index.qmd
---
title: "Tres trucos de Quarto que uso a diario"
date: 2026-05-15
categories: [quarto, r, productividad]
image: thumbnail.png
---

Trampas habituales

date: today en posts: cambia cada vez que renderizas. Usa fecha literal 2026-05-15 para que el orden cronológico sea estable.
Imágenes por post pero ruta absoluta. Estructura recomendada: posts/<slug>/index.qmd con imágenes en la misma carpeta, paths relativos image.png funcionan tanto en preview como en build.
RSS sin URL canónica: el <link> del feed apunta al site-url definido en _quarto.yml. Sin site-url: el feed publicado tiene URLs rotas.

Enlaces

Relacionados en esta página

Website, base sobre la que se construye un blog.

Book

project: type: book compila un libro multi-capítulo a HTML, PDF y ePub desde la misma fuente. Es el sucesor directo de bookdown (RMarkdown), con TOC global, cross-references entre capítulos, numeración automática, índice analítico y descarga del libro completo en cada formato.

Cuándo usarlo

Libros técnicos, manuales internos largos, tesis, documentación de curso de varias semanas.
Cualquier output con jerarquía lineal de capítulos y secciones, donde la navegación es fundamentalmente prev/next.

Cuándo NO usarlo (alternativas)

Documentación de software con muchas páginas independientes y árbol de navegación complejo: website o mkdocs-material (Python) son más adecuados.
Wiki / Knowledge base no lineal: una website con sidebar pero sin orden estricto funciona mejor que un libro.
bookdown sigue siendo válido en proyectos vivos que ya están escritos en él. Migrar a Quarto es opcional. Para libros nuevos, Quarto es la apuesta.

Conceptos clave

book: declara title, author, date, chapters: (lista ordenada), appendices:.
Cada capítulo es un .qmd independiente. index.qmd es la portada/prefacio.
format: puede declarar HTML, PDF y ePub simultáneamente, quarto render genera los tres.
Cross-references entre capítulos: @sec-foo (con #| sec-id: sec-foo o ## Titulo {#sec-foo} + number-sections: true).
book.output-file: controla el nombre del PDF/ePub final.

Patrón mínimo

# _quarto.yml
project:
  type: book

book:
  title: "Manual de análisis"
  author: "A. Navas"
  date: "2026-05-18"
  chapters:
    - index.qmd
    - intro.qmd
    - metodos.qmd
    - resultados.qmd
    - references.qmd
  appendices:
    - apendice-a.qmd

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
    pdf-engine: xelatex

Trampas habituales

Cross-references con @sec-foo no resuelven. Necesitas number-sections: true Y crossref: configurado. Sin ambos, el render emite warnings silenciosos.
references.qmd no rinde como capítulo de bibliografía. Necesita bibliography: apuntando a un .bib y un ### References {.unnumbered} final donde se inyecta la lista.
Numeración rota tras añadir capítulo. El orden en chapters: manda. Si añades un fichero al directorio pero no a la lista, no aparece en el libro.

Enlaces

Relacionados en esta página

Proyecto Quarto, book es un tipo de proyecto.
PDF, el formato impreso del libro.

Informes parametrizados

Un informe parametrizado es un .qmd que declara parámetros en el YAML (params:) y se renderiza repetidamente con distintos valores, produciendo una salida distinta por combinación. Es la mecánica que reemplaza el patrón “for-loop que copia el .Rmd y cambia una variable”, pieza clave de cualquier sistema de reporting automatizado.

Cuándo usarlo

Informes mensuales por cliente / centro / región producidos en lote.
Plantilla única para distintas iteraciones (por trimestre, por experimento, por dataset).
Pipeline de reporte ejecutado en CI (GitHub Actions, Airflow) con parámetros pasados como variables.

Cuándo NO usarlo (alternativas)

Dashboard interactivo donde el usuario elige parámetros desde el navegador: usa Shiny o Streamlit, no Quarto parametrizado.
format: dashboard (Quarto >=1.4) si quieres una vista tipo BI estática con tarjetas y gráficos, parametrizada pero sin reactividad.

Conceptos clave

params: en el YAML declara nombre y default. Se accede en R como params$nombre.
Render con parámetros desde R: quarto::quarto_render("informe.qmd", execute_params = list(region = "Norte")).
Render desde CLI: quarto render informe.qmd -P region:Norte -P year:2026.
Para lotes: itera con purrr::walk() sobre una lista de combinaciones, pasando output_file único por combinación.
Caveat: el render con execute_params arranca una sesión R nueva por defecto. Objetos en tu workspace no se ven.

Patrón mínimo

---
title: "Informe regional"
params:
  region: "Norte"
  year: 2026
  threshold: 0.05
format: html
---

#| label: setup
library(dplyr)
datos <- readr::read_csv("ventas.csv") |>
  filter(region == params$region, year == params$year)

# scripts/render_lote.R
regiones <- c("Norte", "Sur", "Centro")
purrr::walk(regiones, function(r) {
  quarto::quarto_render(
    "informe.qmd",
    execute_params = list(region = r, year = 2026),
    output_file   = glue::glue("informe_{r}_2026.html")
  )
})

Trampas habituales

output_file con extensión equivocada. Quarto la respeta literalmente: si pides informe.pdf pero el formato es HTML, falla en silencio o genera el HTML con nombre .pdf.
params no aparece en la sesión interactiva. Cuando trabajas el .qmd en RStudio sin renderizar, params no existe. Patrón: if (!exists("params")) params <- list(region = "Norte", year = 2026) al inicio.
Render concurrente sobre el mismo .qmd. Quarto escribe ficheros intermedios al lado del fuente. Lanzar dos renders en paralelo desde el mismo directorio puede pisarse. Solución: copiar el .qmd a un working dir único, o usar quarto_render con output_dir distinto por proceso.

Enlaces

Relacionados en esta página

Quarto Document, el informe parametrizado es un documento con params.

Manuscript

project: type: manuscript (Quarto >=1.4) es un formato pensado para escribir papers académicos reproducibles. Produce simultáneamente la versión “journal-ready” (PDF con plantilla del journal, vía formatos como acm, elsevier, jasa) y una versión web navegable con código, datos y artefactos descargables, un companion site del paper.

Cuándo usarlo

Paper de revista donde se exige reproducibilidad y companion code.
Submission a journals que aceptan plantillas Quarto (creciendo: PLOS, BMJ, varios de Elsevier).
Pre-prints en arXiv / bioRxiv donde quieres además publicar una web con el análisis.

Cuándo NO usarlo (alternativas)

Revista que exige .docx con track changes para revisión: la realidad académica sigue siendo Word para muchos editores. Usa format: docx desde un .qmd simple.
Overleaf colaborativo con coautores que solo aceptan LaTeX puro: Quarto produce LaTeX intermedio pero el ciclo edición↔︎compilación en Overleaf es más fluido escribiendo .tex directo.
rticles (paquete RMarkdown) sigue siendo el ecosistema con más plantillas de journal. Quarto está cerrando el hueco pero no las cubre todas.

Conceptos clave

manuscript: declara article (el .qmd principal), notebooks (notebooks adjuntos cuyos outputs se publican en la versión web), resources.
Formatos típicos: jss-pdf, acm-pdf, elsevier-pdf (vía la extensión quarto-journals/<journal>).
La versión web incluye sidebar con “Notebooks”, cada uno renderizado individualmente y enlazado desde el paper principal.
freeze: true es prácticamente obligatorio: garantiza que el HTML/PDF publicado refleja exactamente el cómputo del análisis archivado.

Patrón mínimo

# _quarto.yml
project:
  type: manuscript

manuscript:
  article: index.qmd
  notebooks:
    - notebooks/01-eda.qmd
    - notebooks/02-modelo.qmd
  resources:
    - data/

format:
  html: default
  jss-pdf:
    keep-tex: true
  docx: default

execute:
  freeze: true

Trampas habituales

Plantilla de journal como extensión externa. quarto add quarto-journals/elsevier añade la extensión local. Commitea _extensions/ al repo o el build en otra máquina fallará.
bibliography: no encontrada en el PDF del journal. Las plantillas algunas veces sobrescriben dónde buscar .bib. Comprueba el template-partials específico.
Notebooks que tardan en re-ejecutar. Sin freeze: true, cada quarto render repite todo el análisis del paper.

Enlaces

Relacionados en esta página

Freeze y caching, freeze: true es el patrón canónico aquí.
PDF, el formato de submission.
Website, la versión navegable del manuscrito.

CheatSheets y referencia rápida

Posit mantiene un repositorio centralizado de cheatsheets de una página (PDF imprimible) para sus paquetes y para Quarto: ideal para tener pegado al monitor cuando estás aprendiendo y no recuerdas si la opción de chunk se llama echo o eval.

Cuándo usarlo

Repaso rápido de sintaxis YAML, opciones de chunk, layouts de slide.
Onboarding de personas nuevas al equipo: imprimir y dejar sobre la mesa.

Conceptos clave

Cheatsheet oficial de Quarto: una página con YAML, formatos, slides, cross-refs y publicación.
También hay cheatsheets de dplyr, tidyr, ggplot2, purrr, rmarkdown mantenidas en paralelo.
Las versiones traducidas (incluido español) están en el mismo índice, contribuidas por la comunidad.