Documento básico: front matter, secciones, output

quarto
reproducibilidad
Anatomía de un .qmd. Front matter YAML con las opciones que importan, formatos HTML/PDF/Word, callouts, tabsets, y los detalles tipográficos que distinguen un informe profesional.

Anatomía de un .qmd

Tres bloques:

---                          ← front matter YAML
title: "Mi informe"
author: "Ana López"
format: html
---

## Sección                   ← markdown

Texto con **énfasis** y `código inline`.

`​`​`{r}                       ← chunks de código
2 + 2
`​`​`

Front matter para configuración. Markdown para prosa. Chunks para código. Esa es la composición.

Front matter: lo que importa

El front matter va entre --- y --- al principio del archivo. Es YAML, sintaxis sensible a indentación, con clave: valor.

Lo mínimo:

---
title: "Mi documento"
format: html
---

Lo que conviene saber:

---
title: "Análisis de ventas Q1 2026"
subtitle: "Resumen ejecutivo y detalle por región"
author:
  - name: "Ana López"
    email: "ana@ejemplo.com"
    affiliation: "Departamento de Datos"
date: today                  # o "2026-05-19" o "now"
format:
  html:
    toc: true                # tabla de contenidos
    toc-depth: 3
    code-fold: show
    theme: cosmo
    fig-width: 8
    fig-height: 5
execute:
  echo: true                 # mostrar código
  warning: false             # ocultar warnings
  message: false             # ocultar messages
lang: es                     # localización para "Figura", "Tabla"
---

Argumentos más usados:

  • title / subtitle: texto del documento.
  • author: uno o varios. Forma extendida con email/affiliation o solo un string.
  • date: fecha. today se reemplaza al renderizar. O una fecha fija. O last-modified.
  • format: uno o varios formatos. Si pones varios, podrás renderizar cualquiera.
  • toc: tabla de contenidos lateral (HTML) o al principio (PDF).
  • execute: opciones globales para los chunks: echo, warning, message, eval.
  • lang: es para “Figura X”, “Tabla X”. Por defecto inglés.

Secciones y markdown

Sintaxis estándar Markdown:

# Título nivel 1
## Sección nivel 2
### Subsección nivel 3

Párrafo con **negrita**, *cursiva*, `código inline`, ~~tachado~~.

- Lista no ordenada
- Otro elemento
  - Anidado

1. Lista ordenada
2. Segundo elemento

> Cita en bloque.

[Enlace](https://ejemplo.com)

![Imagen con caption](path/a/imagen.png)

Para tablas, Markdown extendido:

| Columna A | Columna B | Columna C |
|----------:|:---------:|:----------|
| 1234      | foo       | derecha   |
| 5678      | bar       | izquierda |

: controla alineación: ---: derecha, :---: centro, :--- izquierda.

Múltiples formatos de salida

El mismo .qmd puede generar varios formatos. En el YAML:

format:
  html:
    toc: true
  pdf:
    documentclass: article
    geometry:
      - margin=1in
  docx:
    reference-doc: plantilla.docx

Renderiza:

quarto render documento.qmd                  # render del formato default (html en este caso)
quarto render documento.qmd --to pdf         # solo PDF
quarto render documento.qmd --to docx        # solo Word
quarto render documento.qmd --to all         # los tres

HTML: el formato principal

Es donde Quarto más brilla. Output limpio, themes integrados, JavaScript para tabsets, callouts plegables, búsqueda, código con copy button.

Themes built-in (basados en Bootstrap): cosmo, flatly, journal, litera, lumen, materia, minty, pulse, sandstone, simplex, sketchy, slate, solar, spacelab, superhero, united, yeti, zephyr. Más oscuros (darkly, cyborg, etc.) y custom con SCSS.

PDF: para imprimir

Necesita LaTeX. Si no lo tienes:

quarto install tinytex

TinyTeX es una distro ligera (~200 MB) suficiente para 99 % de los documentos. Mucho mejor que MiKTeX o TeX Live full.

Opciones útiles:

format:
  pdf:
    documentclass: article         # o "report", "book"
    classoption: [11pt, twoside]
    geometry:
      - margin=2.5cm
    fig-pos: H                     # figuras donde las pongas, no flotantes
    keep-tex: false                # útil para debug, normalmente false

Word: para colaborar con humanos

format:
  docx:
    reference-doc: plantilla.docx

reference-doc es clave en entornos corporativos: una plantilla Word con estilos definidos (titular, encabezados, párrafos, tablas). Quarto inserta tu contenido respetando esos estilos. Es lo que permite que el informe siga la línea gráfica del cliente sin maquetar a mano.

Callouts: bloques destacados

Cinco tipos:

::: {.callout-note}
Información de contexto. Azul.
:::

::: {.callout-tip}
Consejo práctico. Verde.
:::

::: {.callout-warning}
Atención. Amarillo.
:::

::: {.callout-important}
Crítico. Rojo claro.
:::

::: {.callout-caution}
Riesgo. Rojo.
:::

Atributos:

::: {.callout-note title="Nota especial" collapse="true"}
Plegable: el lector decide si abre.
:::

collapse="true" lo hace plegable. title="..." cambia el título.

Tabsets

Para mostrar varias versiones de algo (idiomas, formatos, ejemplos):

::: {.panel-tabset}

## R

`​`​`{r}
lm(mpg ~ wt, data = mtcars)
`​`​`

## Python

`​`​`{python}
import statsmodels.api as sm
model = sm.OLS(...).fit()
`​`​`

:::

En HTML produce pestañas. En PDF/Word, secuencia. Patrón ideal para documentación bilingüe (R y Python).

Figuras con caption

Las figuras de chunks de código se controlan desde las opciones del chunk (próximo tutorial). Para figuras estáticas:

![Distribución de ventas por región.](figura.png){#fig-ventas width=80%}

#fig-ventas es la referencia para cross-references (@fig-ventas desde otro sitio). width=80% controla el tamaño.

Notas al pie

Esto tiene una nota al pie.[^nota1]

[^nota1]: El contenido de la nota va aquí.

O inline:

Esto tiene una nota al pie.^[Inline footnote, sin clave separada.]

Texto inline con código

Para insertar un valor calculado en medio del texto:

La media es `​r mean(datos$ventas)`​ y la mediana `​r median(datos$ventas)`​.

En Quarto moderno también:

La media es `​{r} mean(datos$ventas)`​.

Útil para que el texto del informe se actualice automáticamente cuando cambian los datos.

Layout: columnas y márgenes

Para contenido a dos columnas:

::: {.columns}
::: {.column width="50%"}
Contenido izquierdo.
:::
::: {.column width="50%"}
Contenido derecho.
:::
:::

Para márgenes (texto en el margen izquierdo del HTML, como Tufte):

::: {.column-margin}
Nota al margen.
:::

Es uno de los detalles editoriales más distintivos de Quarto. Muy elegante.

Idioma y términos

lang: es

Cambia “Figure” → “Figura”, “Table” → “Tabla”, “Contents” → “Contenidos”. Detalle pequeño pero esencial para informes profesionales en español.

Trampas habituales

  • Sintaxis YAML estricta. Una indentación mal (espacios vs tabs, o impares) rompe el front matter. Si Quarto se queja del YAML, revisa indentación primero.
  • PDF sin LaTeX. Render falla con error críptico. quarto install tinytex resuelve.
  • Caracteres especiales en PDF. Algunos caracteres (emojis, símbolos raros) requieren xelatex o lualatex en lugar del pdflatex por defecto. Cambia con pdf-engine: xelatex.
  • echo: false global pero queriendo mostrar uno. Sí, override en el chunk individual con #| echo: true.
  • Doble format:. Es un mapa: dentro pones uno o varios formatos como sub-claves. No varios format: separados.

En la siguiente entrega

Tienes el documento. La siguiente entrega va a fondo en los chunks de código: opciones que importan, R y Python conviviendo en el mismo documento, control de salida y figuras. El núcleo de la parte ejecutable. Lo siguiente.