# Configuración: recuadros de aviso

> Estilos con nombre para los recuadros :::callout: marco, fondo, franja, título, icono y marcador, enunciados numerados, tipografía dentro del recuadro y recuadros partidos entre páginas

- Versión HTML: https://postext.dev/es/docs/configuration-callouts
- Última actualización: 2026-10-16
- Tiempo de lectura: 28 min
- Otros idiomas: [en](https://postext.dev/en/docs/configuration-callouts.md), [ca](https://postext.dev/ca/docs/configuration-callouts.md), [de](https://postext.dev/de/docs/configuration-callouts.md), [fr](https://postext.dev/fr/docs/configuration-callouts.md), [it](https://postext.dev/it/docs/configuration-callouts.md), [pt](https://postext.dev/pt/docs/configuration-callouts.md), [zh](https://postext.dev/zh/docs/configuration-callouts.md), [ja](https://postext.dev/ja/docs/configuration-callouts.md), [ar](https://postext.dev/ar/docs/configuration-callouts.md)

## En pocas palabras

Esta página explica los recuadros que separan del texto una nota, un consejo, una advertencia o una lista de objetivos. Das a cada clase de recuadro un nombre y un aspecto: su fondo, su borde, una franja de color, un título y un icono. Un recuadro puede llevar un número, como un teorema o un ejemplo en un libro de texto. Eliges las tipografías de dentro del recuadro. Cuando un recuadro largo sigue en la página siguiente, eliges qué marca el corte.

## Estilos de aviso

La propiedad `calloutStyles` declara los estilos de caja con nombre que el documento aplica mediante un contenedor `:::callout{type="…"}` — notas, consejos, advertencias, objetivos de aprendizaje, cualquier contenido separado del texto corrido en una caja tintada o con borde. Por defecto se incluye un estilo neutro, `note` (fondo gris claro, sin borde, sin franja, sin icono, sin título), de modo que `:::callout` funciona sin configuración alguna; declarar `calloutStyles` sustituye esa lista por defecto.

```ts
const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Nota' },
    {
      id: 'objectives',
      name: 'Objetivos de aprendizaje',
      title: 'Objetivos',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Advertencia',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};
```

```md
:::callout{type="objectives"}
- Describir las partes de la linterna.
- Recortar la mecha al anochecer.
:::

:::callout{type="warning" title="No toques la lente"}
El cristal sigue caliente una hora después de apagar la llama.
:::
```

| Propiedad | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `id` | `string` | — | Identificador que selecciona `:::callout{type="…"}`. Una valla con un `type` desconocido o ausente usa el primer estilo configurado (el sandbox avisa de los tipos desconocidos). |
| `name` | `string` | `id` | Nombre legible (solo para la interfaz del editor). |
| `title` | `string` | `''` | Texto de título por defecto; vacío significa sin título. El atributo `title` de la valla lo sobrescribe en cada instancia. |
| `span` | `'column' \| 'page' \| 'side'` | `'column'` | Extensión horizontal: la columna, el ancho completo del área de contenido o la columna lateral solo para flotantes de una disposición de columna y media (`layout.sideColumnRole: 'floats'`) — la caja sale entonces del flujo y se apila en esa columna junto al texto que interrumpe. Se puede sobrescribir por instancia con el atributo `span`. En disposiciones multicolumna una caja `'page'` se convierte en un *bloque a ancho de página*: divide la página en bandas de columnas y ocupa su propia columna a todo el ancho (ver la sección del contenedor más abajo). Una caja lateral que no cabe en la columna lateral de su página ocupa la de la página siguiente; si antes termina el capítulo (o el documento), cada caja que sigue esperando se compone en la columna lateral de una página posterior al texto, en el orden de sus vallas, y la composición lo avisa (`afterText`; hasta postext 1.24 las cajas posteriores a la primera de esas páginas se perdían). |
| `columns` | `number` | `1` | Cuántas columnas contiguas ocupa una caja flotante (`placement` `'auto'`, `'top'` o `'bottom'`, con `span: 'column'`), como hace `placement.columns` con una figura: el recuadro de una noticia sobre tres de las cinco columnas de un periódico. Tantas columnas como tiene la página, o más, la convierten en una caja a todo el ancho. Una caja compuesta en el flujo (`'here'`) se queda en su columna. Se puede sobrescribir en cada instancia con el atributo `columns`. Desde postext 1.18. |
| `placement` | `'here' \| 'auto' \| 'top' \| 'bottom' \| 'fixed'` | `'here'` | Dónde va la caja. `'here'` la deja en línea en el flujo; `'top'` / `'bottom'` la hacen **flotar** como un recurso (`'auto'` toma la primera banda que quede libre, la cabecera o el pie) — sale del flujo donde aparece y ocupa la primera banda libre en ese punto o después (el pie de la página actual, o la cabecera / el pie de la siguiente página que abre el flujo), y el texto que la sigue rellena la página a su alrededor; `'fixed'` la ancla a coordenadas de página mediante `fixed`, fuera del flujo de columnas. Ver la sección del contenedor para los detalles. Se puede sobrescribir por instancia con el atributo `placement`. |
| `sideAtColumnEnd` | `'before' \| 'after'` | `'before'` | Dónde se coloca un recuadro lateral (`span: 'side'`) cuando el texto que sigue a su valla no continúa en la misma columna: la columna ya no tiene sitio para él, o las reglas de corte lo llevan más allá (un párrafo que las reglas de viudas y huérfanas mueven entero, un encabezado que va con su texto). `'before'` lo deja en su valla, en esa página, junto al texto anterior, subiendo desde el pie de la columna si no cabe debajo de la valla: el sitio de una glosa escrita después del pasaje que explica. `'after'` lo pone a la altura de la primera línea del texto que sigue a la valla, en la columna lateral de la página donde continúa ese texto: el sitio de un número de línea o de un ladillo escrito antes de su línea. Cuando el texto continúa en la misma columna, los dos valores ponen el recuadro en su valla. Un recuadro al que no sigue nada en su capítulo se queda con el texto anterior en los dos casos, y los recuadros laterales con valla uno tras otro conservan su orden. Hasta postext 1.4 todos los recuadros laterales se comportaban como `'before'`, que sigue siendo el valor por defecto: un estilo para glosas mantiene sus recuadros en la página del pasaje que explican. |
| `fixed` | `{ anchor?, offset? }` | `{ anchor: { to: 'container', edge: 'bottom-left' } }` | Posición de una caja `'fixed'`: un `ElementAnchor` (`to`: `'container'` = el área de contenido de la página, reflejada en las páginas pares; `'page'` = la caja de corte; `'bleed'` = la caja de sangre; `edge`: uno de los nueve bordes del contenedor) más un `offset` opcional (dimensiones `x` / `y`). |
| `floatBarrier` | `boolean` | `false` | Convierte la caja en una barrera de flotantes: toda figura o tabla referenciada antes se coloca antes que ella — en los huecos libres de la página, o en páginas abiertas por delante de la caja —, de modo que ningún flotante escapa más allá de la caja que cierra el capítulo (normalmente un resumen de «puntos clave»). Las aperturas de capítulo, los `:::part` y el final del documento son siempre barreras. |
| Una caja `span: 'page'` en una página a varias columnas corta la banda bajo el texto que la precede; una figura a todo el ancho referenciada antes toma ese corte primero: el texto se nivela, la figura queda justo donde terminó y la caja sigue debajo (o pasa a la página siguiente cuando ya no cabe). Una figura demasiado alta para seguir al texto nivelado abre la página siguiente, con la caja tras ella, y la banda que deja sigue terminando nivelada. Una caja divisible (`keepTogether: false`) se abre bajo el texto y la figura con los elementos que caben, y el resto continúa en la página siguiente. |  |  |  |
| `width` | `'fill' \| 'auto'` | `'fill'` | `'fill'` ocupa todo el ancho disponible; `'auto'` se ajusta al título (uso como etiqueta) e ignora los hijos. |
| `backgroundEnabled` / `background` | `boolean` / `ColorValue` | `true` / `#f4f4f4` | Relleno de la caja. |
| `border` | `{ enabled, color, width }` | `false`, `#cccccc`, `0.5pt` | Contorno de la caja, trazado por dentro de su borde, como el de un elemento de caja (véase [Elementos de caja](https://postext.dev/es/docs/configuration-headers-footers.md#elementos-de-caja)). |
| `borderRadius` | `Dimension` | `0` | Radio de las esquinas del fondo / borde (limitado a la mitad del ancho y del alto de la caja). La franja lo sigue: en una caja redondeada se recorta al marco redondeado, como CSS recorta un `border-left` a `border-radius`. La pestaña `label` conserva las esquinas rectas. |
| `padding` | `{ top, right, bottom, left }` | `0.75em` cada uno | Margen interior entre el borde de la caja y su contenido. Los valores en `em` son relativos al tamaño del cuerpo del aviso. |
| `stripe` | `{ enabled, side, width, color }` | `false`, `'left'`, `1.5em`, color principal | Franja sólida a lo largo de un lado. Una franja `'left'` / `'right'` estrecha el contenido; una franja `'top'` lo desplaza hacia abajo. `'left'` y `'right'` son lados del flujo del texto (en un libro de derecha a izquierda `'left'` es la derecha del pliego); `'start'` y `'end'` siguen la dirección de la propia caja, de modo que un `:::callout{dir=ltr}` en un libro árabe pone a su izquierda una franja `'start'`. En una caja con `borderRadius` sus esquinas exteriores se redondean con las del marco (hasta postext 1.4 quedaban rectas y asomaban por fuera del redondeo). |
| `icon` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, width, color, align, position, cornerSide }` | `'none'`, fuente de encabezados, `400`, `1.5em`, color principal, `'top'` | Un glifo de texto (`kind: 'glyph'`) o un recurso bitmap / SVG (`kind: 'resource'` + `resourceId`) junto al contenido. Con franja lateral el icono se centra sobre la franja; si no, reserva su propia columna (`size` + `titleStyle.gap`). `align: 'center'` lo centra verticalmente sobre el contenido. Una imagen de recurso se ajusta dentro del cuadrado conservando su proporción; un icono más alto que el contenido agranda la caja para contenerlo (y, con `align: 'center'`, centra el contenido sobre él). Con `width` la imagen se ajusta a una caja de `width` × `size` (una tira ancha de iconos). `position: 'corner'` cuelga el icono de una esquina superior como una insignia, medio fuera del borde y sin ocupar sitio en el contenido; un icono ancho (`width`) se centra en la esquina según el ancho con que se dibuja, y en la esquina izquierda el título empieza pasada su mitad interior (hasta postext 1.4 se colocaba según su alto, de modo que una tira ancha sobresalía de la caja y tapaba el título); `cornerSide` elige la esquina: `'right'` / `'left'`, o `'outer'` / `'inner'`, que siguen la paridad de la página con márgenes simétricos (exterior = derecha en una página impar, izquierda en una par). |
| `marker` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, color, align, gap, rule }` | `'none'`, fuente de títulos, `400`, `1.5em`, color principal, `'center'`, `0.5em`, filete desactivado (`0.5pt`, color principal, longitud `0`) | Un segundo icono dibujado *fuera* de la caja, en una columna a su izquierda, con un `rule` (filete vertical) opcional entre él y la caja: la mano de «toca aquí» junto a un distintivo de autoevaluación. El marco pasa a ser `[marker][rule][gap][box]` y mide lo que el más alto de los tres; `align` los centra entre sí o los alinea arriba. `rule.length` es un mínimo: el filete abarca siempre al menos la altura de la caja. |
| `titleStyle` | `{ fontFamily, fontSize, fontWeight, italic, color, textTransform, gap, letterSpacing, indent, lineHeight }` | fuente de encabezados, tamaño del cuerpo, `700`, `false`, color principal, `'none'`, `0.5em`, `0`, `0`, `1.2em` | Tipografía del título. `gap` es el espacio entre el título y el primer hijo (y el hueco de la columna del icono). `lineHeight` es el interlineado de las líneas del título, y `em` cuenta el tamaño del propio título; la línea base queda a 0,8 de él dentro de cada línea, como en el texto corrido, así que un título con el interlineado del texto (`lineHeight: 12pt` sobre una rejilla de 12 pt) deja el recuadro en un número entero de líneas y su título en la rejilla, mientras que el 1,2 em por defecto añade una fracción de línea a cada recuadro. `textTransform: 'uppercase'` conserva la longitud del texto. `letterSpacing` aplica un tracking al título (canvas `letterSpacing` / PDF `Tc`); `indent` lo desplaza a la derecha del borde interior de la caja. Una insignia de esquina que cuelga del lado del título (la esquina izquierda) reserva antes su propio sitio — su mitad interior más `gap` — de modo que el título la libra caiga en la página que caiga; `indent` solo añade a partir de ahí. |
| `body` | `{ fontFamily, fontSize, lineHeight, color, boldColor, italicColor, fontWeight, boldFontWeight, italic, smallCaps, textAlign, hyphenation, paragraphSpacing, firstLineIndent, tabStops, tabInterval }` | hereda de `bodyText`; `italic` / `smallCaps` `false` | Tipografía de los párrafos y elementos de lista dentro de la caja. Cada campo hereda del texto de cuerpo cuando no se indica; `italicColor` fija el color de las cursivas (una cita destacada en cursiva con el color de la caja). `fontWeight` / `boldFontWeight` fijan el peso de los tramos normales y en negrita; `italic` compone la caja en cursiva, con los tramos `*…*` en redonda; `smallCaps`, en versalitas; `tabStops` y `tabInterval` sustituyen a los del cuerpo dentro de la caja (ver [Tabulaciones](https://postext.dev/es/docs/configuration-text.md#tabulaciones)). Ver [Tipografía dentro de un recuadro](https://postext.dev/es/docs/configuration-callouts.md#tipografía-dentro-de-un-recuadro) para lo demás que toma el texto de la caja. |
| `lists` | `{ bulletChar, color, indent, gap, itemSpacing, bulletFontSize, bulletFontWeight }` | hereda de `unorderedLists` | Tipografía de las listas dentro de la caja (`color`, `indent`, `gap` e `itemSpacing` se aplican también a las listas ordenadas). `bulletFontSize` / `bulletFontWeight` componen la viñeta en la fuente del cuerpo de la caja a ese tamaño y peso (una viñeta gruesa de color). |
| `label` | `{ fontFamily, fontSize, fontWeight, color, background, position, height, paddingX, offset, inset, icon, rule }` | sin definir (sin pestaña) | Una pestaña sobre el borde superior de la caja que imprime el atributo `label` de la valla —el número de un recuadro numerado («RECUADRO 1-1»)—. Se pega a la esquina `position` (`'top-right'` / `'top-left'`) con un retranqueo `inset`, sobresale `offset` por encima del borde (ese espacio forma parte del bloque, además de `marginTop`, y se conserva también en cabeza de columna), mide `height` de alto con `paddingX` a cada lado del texto, y puede llevar un recurso `icon` a su lado (`{ resourceId, width, gap }`, hacia el interior) y un filete `rule` (`{ enabled, color, width }`) a lo largo del borde superior desde la esquina opuesta hasta ella. Por defecto: fuente de encabezados, tamaño del cuerpo, `700`, blanco sobre el color principal, `1.4em` de alto, `0.6em` de relleno. La pestaña es una forma propia apoyada en el marco, así que conserva las esquinas rectas sea cual sea el `borderRadius` de la caja. |
| `columnGap` | `Dimension` | `1.5em` | Separación entre las columnas de un grupo `:::columns` dentro de la caja (véase la sección del contenedor). |
| `marginTop` / `marginBottom` | `Dimension` | `0.75em` / `0.75em` | Espacio sobre la caja (se funde con el margen del bloque anterior) y espacio mínimo bajo ella (el espacio exacto con `snapToGrid: false`). Una caja flotante (`placement: 'top'`, `'bottom'` o `'auto'`) deja entre su banda y el texto el hueco de los flotantes, una línea del cuerpo; un `marginBottom` mayor fija el espacio bajo una caja en una banda superior, y un `marginTop` mayor el espacio sobre una caja en una banda inferior, redondeados a la rejilla con la banda. Hasta postext 1.4 una caja flotante no hacía caso de sus márgenes. |
| `snapToGrid` | `boolean` | `true` | Con `true` el flujo vuelve a la rejilla base tras la caja, de modo que el espacio bajo ella es `marginBottom` redondeado hacia arriba a líneas enteras de la rejilla. Con `false` la caja conserva su `marginBottom` exacto, que se funde con el margen superior del bloque siguiente — dos cajas consecutivas de ese estilo quedan exactamente a `max(marginBottom, marginTop)` — y el texto que la sigue puede quedar fuera de la rejilla hasta el siguiente punto de ajuste (un encabezado, el final de una lista), como tras un encabezado con `headings.snapToGrid: false`. Pensado para documentos hechos de cajas apiladas (fichas, formularios). Se aplica a las cajas del flujo; las cajas a ancho de página en una maquetación de varias columnas, las flotantes, las fijas y las laterales conservan la rejilla, porque las bandas de columnas y las zonas de flotantes se disponen sobre ella. Las palancas de equilibrado de columnas no cambian: una caja que cierra una columna sigue bajando hasta la última línea de la rejilla de esa columna. |
| `keepTogether` | `boolean` | `true` | Con `true` la caja se mantiene entera: un aviso que no cabe en el espacio restante pasa entero a la columna o página siguiente. Solo una caja más alta que una columna completa y vacía — una página entera en una caja `span: 'page'` — no puede mantenerse entera: se parte con las reglas de `false` que siguen en lugar de desbordar, empezando donde aparece, y una continuación que cabe en una columna pasa entonces entera; una caja flotante (`placement: 'top' \| 'bottom' \| 'auto'`) así de alta no flota, sino que sigue en el flujo donde aparece. Con `false` cualquier caja puede partirse entre sus bloques hijos o entre las líneas de un párrafo o de un elemento de lista: el corte más profundo que cabe cierra la columna actual (o, en una caja `span: 'page'`, la página, a ras del pie de las columnas) y el resto continúa al inicio de la siguiente en una caja propia — mismo marco y franja, sin icono, y sin título salvo que `repeatTitle` lo repita —, partiéndose de nuevo si sigue siendo demasiado alta. El texto de cada fragmento conserva, vacía, la columna que ocupa en la cabeza un icono en línea, así que la caja tiene la misma medida en todas las páginas. Un corte dentro de un elemento de lista deja la viñeta con la cabeza. El marco de cada fragmento comparte el `contentIndex` / `containerId` de la valla y registra `callout.part` / `callout.continued`. Úsalo en una caja de «puntos clave» larga de cierre junto con `headings.balancing.beforeSpan`, o en un estilo de nota cuyas cajas nunca deban expulsar una figura de la página. Una caja anidada (un `:::callout` dentro de otro) es un hijo más de su madre: un corte puede caer antes o después de ella, y dentro solo si su propio estilo permite partirla (`keepTogether: false`, o más alta que una columna completa), según su propio `splitMinLines`. |
| `splitMinLines` | `number` | `2` | Mínimo de líneas de texto que un fragmento de una caja partida (`keepTogether: false`, o una caja unida más alta que una columna completa) conserva a cada lado del corte. Solo protege el texto: un lado con al menos una figura, tabla, fórmula en bloque o caja anidada es válido tenga las líneas que tenga, de modo que una caja de imágenes puede dejar una sola en una página. Un corte dentro de un párrafo o de un elemento de lista sigue contando todas las líneas de cada lado (una figura o fórmula, como una línea), y además deja al menos `layout.boxChildSplitMinLines` líneas de ese párrafo o elemento a cada lado (dos por defecto; este mínimo si es menor, así que con 1 basta una). Con los valores por defecto, un elemento de dos o tres líneas nunca se parte y uno de cuatro solo se parte en dos y dos. Con el valor por defecto ninguna caja se parte dejando una línea de texto sola al pie de una columna o al inicio de la siguiente; si ningún corte cumple el mínimo, la caja pasa entera. (Antes de postext 1.5, un corte dentro de un párrafo solo comprobaba las líneas de todo el lado, así que un elemento de dos líneas podía partirse en una y una si otras líneas de la caja completaban el mínimo). |
| `repeatTitle` | `boolean` | `false` | Repite el título al principio de cada continuación de una caja partida, seguido de `continuedSuffix` («Puntos clave (cont.)»). La repetición toma el estilo del título. Una caja sin título no repite nada. Ver [Marcas de un recuadro partido](https://postext.dev/es/docs/configuration-callouts.md#marcas-de-un-recuadro-partido). |
| `continuedSuffix` | `string` | `'(cont.)'` | Texto tras el título repetido, en el idioma del documento (`locale` o, si no, el de la separación silábica), como el de una tabla partida, y unido al título igual que en ella. |
| `continuesMarkerEnabled` | `boolean` | `false` | Pone `continuesMarker` bajo la última línea de cada parte de una caja partida que continúa, dentro de la caja. |
| `continuesMarker` | `string` | `'Continued'` / `'Continúa'` | Texto de ese indicador (el «(SIGUE)» de un guion), en la fuente y el cuerpo del texto de la caja, según el idioma del documento. |
| `continuesMarkerAlign` | `'left' \| 'center' \| 'right'` | `'right'` | Posición del indicador en el ancho interior de la caja. |
| `continuesMarkerItalic` | `boolean` | `true` | Compone el indicador en cursiva. |
| `numbering` | `{ label, counter, numberingTemplate, resetOn, counterFormat, placement, bold, italic, suffix }` | sin definir | Cuenta las cajas de este estilo como enunciados numerados: teoremas, lemas, definiciones. Ver [Enunciados numerados y demostraciones](https://postext.dev/es/docs/configuration-callouts.md#enunciados-numerados-y-demostraciones). |
| `endMark` | `string` | `''` | Una marca alineada a la derecha al final de la última línea de la caja, como el `'∎'` o el `'□'` con que termina una demostración: en esa línea si cabe tras un espacio y, si no, en una línea propia. Una caja que termina en una fórmula en bloque sin número la pone como etiqueta de la fórmula. Con las matemáticas activas, los cuadrados (∎ □ ■ ▪ ◻ ▫) se dibujan con los glifos de TeX, así que salen aunque la fuente no los tenga (los archivos latin de Fontsource); con las matemáticas desactivadas se componen en la fuente del cuerpo del recuadro. |

### El contenedor `:::callout`

Una línea `:::callout{type="<id>"}` abre la caja y una línea `:::` a solas la cierra. La valla admite cinco atributos — `type` (el id del estilo), `title` (sobrescribe el título del estilo), `span`, `placement` y `columns` (sobrescriben los valores del estilo) — y el contenido intermedio se compone dentro de la caja: un título opcional y después los párrafos, listas, citas, fórmulas o recursos incrustados, cada uno con la tipografía `body` / `lists` del estilo (los encabezados conservan sus estilos habituales). Los márgenes entre hijos se funden como en el texto corrido; el interior abandona la rejilla base y el flujo vuelve a ella tras la caja garantizando al menos `marginBottom` por debajo (la rejilla manda; el margen es un mínimo — la misma convención que siguen los recursos). Un estilo con `snapToGrid: false` conserva en cambio el `marginBottom` exacto, y el texto tras la caja queda fuera de la rejilla hasta el siguiente encabezado o final de lista. Un encabezado inmediatamente anterior a un aviso se mantiene unido a él.

Límites de esta versión:

- Un aviso se mantiene entero salvo que su estilo indique `keepTogether: false`. Cuando no cabe en el espacio restante de la columna pasa entero a la columna o página siguiente — también desde una columna vacía que las bandas de flotantes o un tope de banda han acortado, siempre que una columna completa lo alojara. Una caja más alta que una columna completa se parte en su lugar, como una divisible; solo la que ningún corte puede partir (una figura o tabla más alta que la columna, o un `splitMinLines` que ningún corte cumple) se coloca de todos modos y desborda; la maquetación registra entonces un aviso `calloutOverflow` (`VDTDocument.warnings`), que el sandbox lista. Un grupo `:::columns` se corta como la caja que lo rodea, entre sus subcolumnas (desde postext 1.25); solo se mantiene entero, y puede desbordar de la misma manera, con `layout.flowColumns: false` o dentro de una caja anidada. Una caja divisible deja atrás la parte que cabe — hijos enteros, o las líneas de un párrafo hasta `splitMinLines` a cada lado (basta una figura, tabla o fórmula en bloque en un lado) — y continúa en una caja sin icono en la columna o página siguiente, sin título salvo que el estilo lo repita y, si se quiere, con un indicador bajo la parte que deja (ver [Marcas de un recuadro partido](https://postext.dev/es/docs/configuration-callouts.md#marcas-de-un-recuadro-partido)).
- Los flotantes ceden ante una caja indivisible. Cuando el bloque que sigue a la referencia de una figura es un aviso `keepTogether`, no se toma un hueco que dejaría a la caja sin ninguna columna de la banda actual donde caer (la columna de la referencia o una vacía posterior, que antes del flotante la alojaba): la figura pasa a su siguiente hueco, normalmente la página siguiente, y la caja sigue en el flujo — como la compondría un cajista, en lugar de expulsar la caja de la página y dejar la columna con la figura sola.
- `span: 'page'` en una disposición multicolumna convierte la caja en un **bloque a ancho de página**: se compone al ancho completo del área de contenido y divide la página en bandas de columnas — las columnas de texto que hay encima se cierran en la línea de corte, la caja ocupa su propia columna a todo el ancho y debajo se abre una banda nueva de columnas de texto, de modo que el flujo continúa bajo la caja en todas las columnas. Donde las columnas están *niveladas* — al inicio de una página, justo debajo de un encabezado de apertura con `span: 'page'`, justo debajo de otro bloque a ancho de página o justo debajo de una banda de flotantes superior — la caja simplemente corta ahí. Si llega a mitad de página, con las columnas desiguales, se compone como lo haría un cajista: el texto que hay encima se corta nivelado en todas las columnas (el motor repite la colocación con las columnas de la banda acortadas al mismo número de líneas de rejilla, de modo que el texto desborda de columna en columna de forma natural y siguen aplicándose todas las reglas de huérfanas, viudas y encabezados unidos a su texto), la caja ocupa el ancho de la página y las columnas continúan debajo. El corte cuesta un par de pasadas de colocación adicionales; cuando la línea de corte no dejaría sitio para la caja más el mínimo de líneas viudas de cuerpo por debajo, o ninguna disposición encaja tras unos pocos intentos, la caja pasa al inicio de la página siguiente. El texto de encima respeta el corte: un párrafo que no puede empezar en las pocas líneas que le quedan a una columna bajo una figura pasa a la columna siguiente (la figura queda sola en su columna), y cuando un bloque aún pasaría del corte, el corte se baja una línea en lugar de quedarse donde termina ese bloque. Una caja partida que abre la banda también se corta ahí, de modo que su resto nunca pasa del corte. Con `headings.balancing.beforeSpan` (el valor por defecto) la banda que deja se corta nivelada tras ella — como la banda de cierre de un capítulo — y, cuando el estilo permite partirla (`keepTogether: false`), la parte de la caja que cabe bajo las columnas niveladas cierra la página y el resto abre la siguiente; con `beforeSpan: false` la página que deja simplemente se equilibra como siempre, sin forzar un salto de página. Un encabezado justo antes de un bloque a ancho de página no viaja con él. En disposiciones de una columna `span: 'page'` es simplemente en línea.
- `placement: 'fixed'` saca la caja del flujo: se compone (`width: 'auto'` se ajusta al título; `'fill'` toma el ancho de la columna de texto bajo el punto de anclaje) y se fija a la página en la que aparece en el flujo, en la posición que describen `fixed.anchor` / `fixed.offset` — por defecto la esquina inferior izquierda del área de contenido. Las columnas de texto que cubre ceden esa zona (recortada por abajo, o por arriba cuando la columna aún está vacía), exactamente como una banda de flotantes; cuando la zona ya contiene texto, un flotante o un bloque a ancho de página, la caja pasa a la página siguiente. Una caja fija que cierra el capítulo (el bloque siguiente es una apertura de capítulo, un `:::part`, una caja barrera de flotantes o el final del documento) nivela primero las columnas que quedan encima (`headings.balancing.trailing`), de modo que una página de cierre corta termina nivelada con el distintivo debajo. La caja y sus hijos viven en `page.floats` y se pintan fuera del recorte de columna en todos los backends.
- `placement: 'top' | 'bottom'` hace **flotar** la caja como un recurso: sale del flujo donde aparece y toma la primera banda libre a partir de ese punto — el pie de la página actual (`'bottom'`), o la cabeza / el pie de la siguiente página que abre el flujo — al ancho de la columna (`span: 'column'`) o al ancho completo del área de contenido (`span: 'page'`); el texto que la sigue rellena la página que dejó. Su marco y sus hijos van a `page.floats`, como los de una caja fija. Una caja flotante que encabeza una página nueva se coloca antes que las figuras que esperan esa página, y una figura citada en una página anterior que entonces cabe bajo ella toma el resto de esa página aunque quedaran menos de tres líneas de texto (una página galería: caja más figura, sin texto entre ambas). Una caja `span: 'side'` nunca flota: se apila junto al texto sea cual sea su `placement`. Con `columns` mayor que 1 (en el estilo o como atributo de la valla, desde postext 1.18), una caja `span: 'column'` ocupa ese número de columnas contiguas: la cabeza de una serie de columnas vacías que empiezan a la misma altura, o el pie de la columna en curso y de las vacías que la siguen, como en `:::callout{placement="top" columns="2"}`.
- `width: 'auto'` se ajusta solo al título; los hijos se ignoran.
- Un `:::callout` anidado dentro de otro aviso es una caja propia: se compone con su propio estilo (fondo, borde, radio, relleno, franja, título, icono, marcador, pestaña, tipografía) al ancho interior completo de su caja madre y se apila como un hijo más, con su `marginTop` / `marginBottom` colapsando con los vecinos. Su `span` y su `placement` (de la valla o del estilo) se ignoran —una caja anidada siempre fluye dentro de su madre—, igual que `floatBarrier` y `snapToGrid`. Las cajas se anidan a cualquier profundidad y pueden ir dentro de un grupo `:::columns` (cada una entera, en una columna). Cuando la caja madre se parte, el corte cae antes o después de una caja anidada, o dentro de ella si su estilo permite partirla; cada fragmento vuelve a dibujar los marcos que atraviesa el corte, y una caja anidada que continúa del fragmento anterior pierde su título y su icono, como una continuación de primer nivel.
- Un grupo `:::columns{count=N}` … `:::` entre los hijos compone esos hijos en `N` columnas de igual ancho, separadas por `columnGap`, dentro de la caja: la secuencia se corta por los límites de bloque o de línea que mejor nivelan las columnas (un párrafo o elemento de lista cortado a medias sigue en la cabeza de la columna siguiente sin su viñeta), cada columna empieza en la parte superior del grupo y el grupo mide lo que la columna más alta; los hijos posteriores recuperan el ancho completo. Una caja que se parte (`keepTogether: false`, o más alta que una columna) también corta dentro de un grupo, entre sus columnas: un grupo en serpentina llena sus columnas por turno y sigue en el fragmento siguiente, y uno paralelo (`breaks`) sigue corriente a corriente (desde postext 1.25; ver [Formato del documento › `:::columns`](https://postext.dev/es/docs/document-format-directives.md#columns)). Un `gap` en la valla sustituye a `columnGap` para ese grupo, y `rule` traza un filete a lo largo de cada medianil. Sirve para un resumen de puntos clave a dos columnas o para las tablas de un recuadro ancho puestas lado a lado.
- El sexto atributo de la valla, `label`, se imprime en la pestaña `label` del estilo (véase arriba): `:::callout{type="recuadro" label="RECUADRO 1-1" title="La regla del octeto"}`; sin estilo de pestaña el atributo se ignora.

En el VDT la caja es un bloque marco de `type: 'callout'` cuya decoración (fondo, franja, icono, título) vive en `designOverlay`, seguido de sus bloques hijos en la misma columna; el marco y cada hijo llevan el `containerId` de la valla. Una caja anidada es un marco `type: 'callout'` propio entre los hijos, seguido de sus bloques; conservan el `containerId` de la valla de primer nivel (la colocación y el equilibrado siguen viendo una sola unidad) y añaden `calloutPath`, los identificadores de contenedor de las vallas anidadas que los rodean, de la más externa a la más interna (el de un marco anidado es la última entrada). El PDF etiquetado da a cada caja anidada un `Div` dentro del de su madre. Las imágenes de icono se resuelven como las de los recursos: el registro de imágenes del canvas, la opción `resourceImageUrl` del HTML y el proveedor `resourceBytes` del PDF.

```ts
const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => cada campo heredado se rellena desde las secciones resueltas; el locale
//    opcional elige el idioma de las cadenas de continuación

const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined para el `note` por defecto; se eliminan los valores estáticos por defecto
```

### Enunciados numerados y demostraciones

Un estilo con `numbering` cuenta sus cajas, como el paquete `amsthm` de LaTeX cuenta los entornos de teorema (desde postext 1.19). Cada caja imprime su rótulo y su número —«**Teorema 2.**» al principio de su primer párrafo—, y el `title` de la valla sigue al número entre paréntesis: `:::callout{type="theorem" title="Bradley–Terry"}` empieza con «**Teorema 2** (Bradley–Terry)**.**». Una caja abierta con un identificador (`{#thm:main}`) es destino de referencias cruzadas, que imprimen «Teorema 2» (`:ref{id="thm:main"}`), y `\ref{thm:main}` o `style=number` imprimen 2.

| Propiedad | Tipo | Por defecto | Descripción |
| --- | --- | --- | --- |
| `label` | `string` | — | La palabra que precede al número: `'Teorema'`, `'Lema'`, `'Definition'`. |
| `counter` | `string \| false` | el `id` del estilo | El contador que hacen avanzar las cajas. Los estilos que nombran un mismo contador lo comparten, como hace `\newtheorem{lemma}[theorem]`: Teorema 1, Lema 2, Teorema 3. `'equation'` cuenta junto con las ecuaciones etiquetadas. `false` imprime el rótulo sin número (el «*Demostración.*» de una demostración). |
| `numberingTemplate` / `resetOn` / `counterFormat` | `string` / `ResourceCounterReset` / `ResourceCounterFormat` | `'{n}'` / `'never'` / `'decimal'` | Como los de un tipo de recurso: `'{h1}.{n}'` con `resetOn: 'h1'` numera Teorema 2.1, 2.2… por capítulo, y `'{h1}.{h2}.{n}'` con `'h2'`, por sección. Un contador que comparten varios estilos sigue la cuenta impriman lo que impriman sus plantillas. Un token admite un estilo tras dos puntos, como el de un tipo de recurso: `'{h1:A}.{n}'` imprime *Teorema A.1* en un apéndice con letra. |
| `placement` | `'runIn' \| 'title'` | `'runIn'` | `'runIn'` abre el primer párrafo de la caja con el rótulo (una caja que empieza con una lista, una fórmula u otra caja recibe un párrafo para él); `'title'` hace del rótulo el título de la caja, con su `titleStyle`: «Teorema 2 (Bradley–Terry)». |
| `bold` / `italic` | `boolean` | `true` / `false` | La letra del rótulo en línea y de su sufijo, sea cual sea la del cuerpo de la caja: con un cuerpo en cursiva (`body.italic`), un rótulo en redonda sigue en redonda. El título entre paréntesis se compone en redonda y con el peso normal. |
| `suffix` | `string` | `'.'` | Se compone tras el rótulo en línea y su título. |

Una demostración es un estilo con un rótulo sin número y una marca final:

```ts
calloutStyles: [
  { id: 'theorem', numbering: { label: 'Teorema' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lema', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definición' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Demostración', counter: false, bold: false, italic: true } },
]
```

En un libro compuesto capítulo a capítulo, los contadores siguen desde el capítulo anterior (`LayoutContinuation.statementCounters`, que rellena `continuationAfter`), y el esquema del libro da al ancla de cada caja numerada su rótulo (`OutlineEntry.numberLabel`), de modo que una referencia desde otro capítulo lo imprime.

### Tipografía dentro de un recuadro

Una caja de aviso —un *recuadro*, como la llaman el panel Estilos de recuadro del sandbox y el [formato del documento](https://postext.dev/es/docs/document-format.md)— compone su contenido con la tipografía `body` y `lists` de su estilo; todo lo demás conserva los estilos del documento:

- **Los párrafos** toman el `body` de la caja: fuente, cuerpo, interlineado, color, colores de énfasis, pesos, `italic`, `smallCaps`, alineación, separación silábica, sangría y espaciado entre párrafos. Un campo sin definir hereda de `bodyText`. Un color de énfasis heredado conserva su vínculo con la paleta, así que las negritas, las cursivas y las etiquetas de `:ref` de una caja cambian con `colorPalette` igual que fuera de ella. (Hasta postext 1.4 la negrita de una caja se quedaba en `#295AA3` fuera cual fuera el color principal).
- **Las listas de viñetas** toman el `lists` de la caja (carácter de viñeta, color, tamaño y peso del glifo, sangría, separación, espaciado entre elementos) sobre `unorderedLists`, y su texto es el del cuerpo de la caja. Un `lists.bulletChar` o un `lists.color` distinto del del documento (`unorderedLists`) sustituye la viñeta o el color de todos los niveles; uno que lo repite, o que no se define, deja a cada nivel los suyos (`unorderedLists.levels`), de modo que las rayas de los niveles anidados se conservan en la caja.
- **Las listas ordenadas** toman `lists.indent`, `gap` e `itemSpacing`, y `lists.color` siempre que el estilo lo define, también cuando coincide con el color de viñeta del documento; un estilo que no lo define deja los números en `orderedLists.color`. (Hasta postext 1.4 el color solo llegaba a los números si era distinto de `unorderedLists.color`, así que darle justo ese color no tenía efecto). El número —su fuente, su cuerpo y su separador— viene de los `orderedLists` globales, porque `lists` solo tiene campos de viñeta: es ahí donde se da estilo a los números de una caja.
- **Los `:::paragraphs` dentro de una caja** usan su estilo de párrafo, también en cajas anidadas. Los campos que el estilo no define heredan del `bodyText` del documento, no del `body` de la caja (ni de su cursiva ni de sus versalitas).
- **Los grupos `:::columns`** no tienen estilo propio: todas las columnas comparten la tipografía de cuerpo y de listas de la caja, y `columnGap` fija la separación entre ellas.
- **Las citas** toman la fuente, el cuerpo y los pesos del texto de la caja (en cursiva y en gris, como en el texto corrido) y sus versalitas. **Los encabezados** conservan sus estilos; **las fórmulas en bloque**, los ajustes de matemáticas.
- **Las figuras y las tablas** conservan los estilos de pie y de tabla del documento, al ancho interior de la caja; sus pesos normal y negrita siguen los pesos del `body` de la caja.
- **Los chips** conservan su estilo de chip; un tamaño en `em` se mide sobre el cuerpo del texto de la caja.
- **`:::space`** se mide en líneas del texto de la caja (ver [`:::space`](https://postext.dev/es/docs/document-format-directives.md#space) para saber dónde se descarta).
- **Una caja anidada** toma su propio estilo completo; su `span`, su `placement`, su `floatBarrier` y su `snapToGrid` se ignoran.

### Marcas de un recuadro partido

Cuando una caja se parte entre columnas o páginas (`keepTogether: false`, o una caja más alta que una columna), cada parte posterior a la primera empieza sin el título ni el icono y, por defecto, nada avisa al lector de que la caja continúa. Dos opciones añaden las marcas que usan un libro o un guion:

- **`repeatTitle: true`** repite el título al principio de cada continuación, seguido de `continuedSuffix` — «Puntos clave (cont.)» por defecto. La repetición toma el estilo del título, así que con `textTransform: 'uppercase'` da el «HAMLET (CONT.)» de un guion. El icono y la pestaña de etiqueta se quedan en la primera parte.
- **`continuesMarkerEnabled: true`** pone `continuesMarker` — «Continúa» en un documento en español, «Continued» en inglés — bajo la última línea de cada parte que continúa, dentro de la caja, en la fuente y el cuerpo del texto de la caja: en cursiva salvo que `continuesMarkerItalic` sea `false`, y alineado a la derecha salvo que `continuesMarkerAlign` diga `'left'` o `'center'`. El indicador ocupa sitio en la parte que cierra, y el corte se elige para que quepa.

```ts
calloutStyles: [{
  id: 'parlamento',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: '(CONT.)',
  continuesMarkerEnabled: true,
  continuesMarker: '(SIGUE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],
```

```md
:::callout{type="parlamento" title="Hamlet"}
Un parlamento lo bastante largo para pasar del pie de la página…
:::
```

La parte que cierra la página termina con «(SIGUE)» y la página siguiente empieza con «HAMLET (CONT.)». Las dos son elementos de paginación: en un PDF accesible son artefactos y en el HTML se ocultan a las tecnologías de apoyo, de modo que el título se lee una sola vez. En el VDT son bloques de texto de `designOverlay` marcados con `artifact: true`.