Configuración: estilos y partes

#Estilos de párrafo

La propiedad paragraphStyles declara estilos con nombre que el documento aplica a una serie de párrafos mediante un contenedor :::paragraphs{style="…"} — bibliografías, glosarios, notas, cualquier bloque de entradas que quiera su propia tipografía, peso, cursiva, tamaño, interlineado, mayúsculas, versalitas o un sangrado francés. Todos los campos tipográficos son opcionales y heredan del texto de cuerpo cuando no se indican, de modo que un estilo solo describe lo que difiere del texto corrido.

const config: PostextConfig = {
  paragraphStyles: [
    {
      id: 'bibliography',
      name: 'Bibliografía',
      fontSize: { value: 7, unit: 'pt' },
      lineHeight: { value: 1.2, unit: 'em' },
      hangingIndent: { value: 2, unit: 'em' },
      spaceBetween: { value: 0.25, unit: 'em' },
      marginTop: { value: 1, unit: 'em' },
      marginBottom: { value: 1, unit: 'em' },
    },
  ],
};

## Referencias
 
:::paragraphs{style="bibliography"}
Knuth, D. E. (1984). *The TeXbook*. Addison-Wesley.
 
Bringhurst, R. (2004). *The Elements of Typographic Style*. Hartley & Marks.
:::

Una obra de teatro compone sus acotaciones en cursiva y su reparto en versalitas:

paragraphStyles: [
  { id: 'acotacion', italic: true, fontSize: { value: 9, unit: 'pt' } },
  { id: 'reparto', smallCaps: true, textAlign: 'center', fontWeight: 600 },
],

:::paragraphs{style="acotacion"}
Elsinor. Una explanada ante el castillo. *Francisco* en su puesto.
:::

La acotación se imprime en cursiva y el nombre que contiene, en redonda; los pesos, italic y smallCaps de un estilo también se aplican dentro de las cajas de aviso.

Un libro de poemas sangra algunos versos y, cuando un verso no cabe en la medida, lleva lo que sobra más adentro que el propio verso. indent desplaza hacia dentro todas las líneas del párrafo, y la sangría francesa se cuenta desde ahí:

paragraphStyles: [
  { id: 'verso', textAlign: 'left', firstLineIndent: { value: 0, unit: 'em' }, hangingIndent: { value: 4, unit: 'em' } },
  { id: 'verso-sangrado', textAlign: 'left', indent: { value: 1.5, unit: 'em' }, hangingIndent: { value: 2.5, unit: 'em' } },
],

Un verso en verso-sangrado empieza a 1,5 em y su continuación a 4 em, a la altura de las continuaciones de los versos en verso. Sin indent, un estilo puede sangrar la primera línea o las demás, no las dos: firstLineIndent se ignora en cuanto hay hangingIndent.

Una carta de restaurante compone cada precio a ras del final de la medida, tras una línea de puntos:

paragraphStyles: [
  {
    id: 'carta',
    textAlign: 'left',
    firstLineIndent: { value: 0, unit: 'em' },
    tabStops: [{ position: 'end', align: 'end', leader: '. ' }],
  },
],

:::paragraphs{style="carta"}
Sopa de cebolla :tab 8,50
 
Dorada a la plancha con hinojo y limón :tab 21,00
:::

Los puntos de todas las líneas terminan medio cuadratín antes del precio (leaderGap). Un plato demasiado largo para su línea pasa a la siguiente, y su última línea conserva el relleno y el precio; cuando el precio no cabe junto a la última palabra, esa palabra baja con él.

#El contenedor :::paragraphs

Una línea :::paragraphs{style="<id>"} abre el contenedor y una línea ::: a solas lo cierra; todos los párrafos intermedios toman el estilo indicado, mientras que los encabezados, listas y otros bloques del interior conservan su estilo habitual. Los contenedores pueden anidarse dentro de otros contenedores. Un style desconocido no es un error: los párrafos se componen como texto de cuerpo normal.

La valla admite también align (start, end, left, right, center, justify), indent y endIndent (los números sin unidad son em), con estilo o sin él: con estilo, mandan sobre él; sin estilo, se aplican sobre el estilo del contenedor que lo rodea, o sobre el estilo de texto del lugar donde está la valla (el cuerpo, una parte, una sección con estilo o un recuadro). :::paragraphs{align=end} compone un bloque a ras del final de la línea (地付き) y :::paragraphs{align=end endIndent=1}, a un carácter de él. Desde postext 1.16.

Dentro del contenedor el flujo abandona la rejilla base — una entrada de 7pt con interlineado 1.2em no puede asentarse en una rejilla de 8pt/1.5em — y el último párrafo devuelve el flujo a la rejilla (la rejilla manda; el espacio de debajo es un mínimo, la misma convención que siguen los encabezados). Las entradas se parten entre columnas y páginas como los párrafos del cuerpo, con la misma protección de viudas y huérfanas; un encabezado inmediatamente anterior al contenedor se mantiene unido a su primer párrafo.

El espacio bajo el contenedor es el mayor entre el spaceBetween y el marginBottom del estilo y la separación entre párrafos del texto que lo rodea (una línea cuando bodyText.paragraphSpacing está activado), y se funde con el espacio que el bloque siguiente deja sobre sí, como el espacio entre dos párrafos del cuerpo: un encabezado tras una bibliografía queda a su propio marginTop de la última entrada (o al espacio del estilo, si es mayor), y un párrafo tras un grupo de entradas más apretadas conserva la separación entre párrafos del texto. El flujo vuelve primero a la rejilla bajo el texto, y lo que el ajuste no cubrió se arrastra en líneas enteras de la rejilla, para que el texto que sigue al contenedor caiga en ella. Hasta postext 1.4, el espacio del estilo se ponía bajo la última línea antes del ajuste, el espacio del bloque siguiente se sumaba debajo y la separación entre párrafos no contaba; bodyText.paragraphContainerSpacing: 'add' mantiene esa regla, y las configuraciones guardadas antes se leen con ella. Un estilo con snapToGrid: false no se ajusta: el texto que sigue al contenedor queda al espacio exacto de él, fuera de la rejilla hasta el siguiente bloque que se ajuste. Un contenedor que se cierra con una lista se compone como en 1.4 con cualquiera de las dos reglas: la lista conserva su propio espacio debajo, y el marginBottom va a continuación de ese espacio y se funde con el del bloque siguiente.

Dentro de un :::callout el contenedor aplica los márgenes de su estilo del mismo modo: marginTop y marginBottom se funden con el espaciado de los bloques que lo rodean (uno negativo los acerca), y un contenedor que abre el recuadro no lleva margen superior, igual que en lo alto de una columna. El recuadro no tiene rejilla base a la que volver, así que el espacio bajo el último párrafo es el mayor de marginBottom, spaceBetween y la separación entre párrafos del propio recuadro (su body.paragraphSpacing, una línea de su texto; no cuenta con paragraphContainerSpacing: 'add'), o el margen superior del bloque siguiente, si es mayor aún; un marginBottom negativo acerca en cambio el bloque siguiente. (Hasta postext 1.4, un contenedor dentro de un recuadro no aplicaba ninguno de los dos márgenes.)

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => cada campo no indicado se rellena desde el texto de cuerpo resuelto
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => undefined cuando la lista está vacía; se eliminan los márgenes a cero y `name === id`

#Estilos de chip

La propiedad chipStyles declara los estilos con nombre del :chip[texto]{style="…"} en línea: las cajas redondeadas y tintadas de un banco de palabras, una tecla, una etiqueta (la sintaxis y sus reglas de corte de línea están en la referencia del formato de documento). Viene un estilo por defecto, chip (relleno azul pálido con un filete del color principal, esquinas algo redondeadas y el texto como las palabras que lo rodean), así que :chip[…] funciona sin configurar nada; declarar chipStyles sustituye esa lista. Un chip sin style, o con un id que ningún estilo declara, toma el primer estilo.

const config: PostextConfig = {
  chipStyles: [
    { id: 'chip', name: 'Banco de palabras' },
    {
      id: 'key',
      name: 'Tecla',
      background: { hex: '#fff4d6', model: 'hex' },
      borderColor: { hex: '#8a6d1f', model: 'hex' },
      borderRadius: { value: 2, unit: 'pt' },
      bold: true,
    },
  ],
};

Clasifica: :chip[pila] :chip[cable] :chip[interruptor]
 
Pulsa :chip[Ctrl]{style="key"} + :chip[C]{style="key"}.

Las longitudes en em de la caja (paddingX, paddingY, borderRadius, borderWidth, gap) son relativas al cuerpo del propio chip. La caja es una banda de 0,8 em por encima y 0,25 em por debajo de la línea base, que crece con paddingY y el contorno; se pinta fuera de la caja de línea y nunca cambia el interlineado, así que la retícula se mantiene. Cuando la caja resulta más alta que el interlineado, un chip puede invadir un chip de la línea de encima o de debajo: el sandbox muestra el aviso «Los chips tocan la línea siguiente» cuando dos chips de líneas distintas se solapan, con el solapamiento en puntos, para reducir paddingY, el contorno o fontSize. Un chip alto sin ningún chip encima ni debajo no se señala.

En el VDT un chip es un segmento de línea de kind: 'chip' cuyo campo chip lleva los tramos de texto (cada uno con su cadena de fuente y su ancho), la geometría de la caja (boxWidth, ascent, descent, paddingX, borderWidth, borderRadius, los márgenes del gap) y sus colores; el text del segmento es un marcador de un carácter, de modo que los desplazamientos de texto plano y los mapas de fuente cuentan un chip como un carácter.

const resolved = resolveChipStylesConfig(config.chipStyles);
// => el estilo `chip` integrado si no se declara; todos los campos rellenos
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => undefined para el valor integrado; se eliminan los valores por defecto
 
const style = pickChipStyle(resolved, 'key');
// => el estilo `key`, o el primero

#Listados de código

La propiedad codeStyle fija el aspecto de los listados de código: las vallas ``` y ~~~ del texto (ver Formato del documento › Bloques de código), y el código en línea cuando pide una letra de código. Un listado se compone línea a línea tal como está escrito, en una letra monoespaciada y dentro de una caja: ninguna línea se divide ni se justifica, cada espacio conserva su ancho y un tabulador avanza hasta la siguiente tabulación. La caja sale del mismo mecanismo que un :::callout, así que un listado se parte entre líneas a través de columnas y páginas, cada parte en su propia caja, y una valla dentro de un aviso es una caja anidada en él. Todas las propiedades son opcionales. Desde postext 1.23.

const config: PostextConfig = {
  codeStyle: {
    fontFamily: 'JetBrains Mono',
    fontSize: { value: 0.8, unit: 'em' },
    background: { hex: '#0e1116', model: 'hex' },
    color: { hex: '#d3d9df', model: 'hex' },
    padding: { top: { value: 4, unit: 'mm' }, right: { value: 5, unit: 'mm' }, bottom: { value: 4, unit: 'mm' }, left: { value: 5, unit: 'mm' } },
    borderRadius: { value: 2, unit: 'pt' },
    lineNumbers: true,
    tokens: {
      keyword: { color: { hex: '#f2b134', model: 'hex' }, bold: true },
      string: { color: { hex: '#3ddc84', model: 'hex' } },
      comment: { color: { hex: '#8a939d', model: 'hex' }, italic: true },
    },
    inline: { background: { hex: '#eef1f4', model: 'hex' } },
  },
};

#Coloreado de sintaxis

Un pequeño analizador integrado en el motor reconoce los elementos de js y ts (javascript, jsx, typescript, tsx), json, python, bash (sh, zsh, shell), console (una sesión de terminal), css, html y xml (svg), markdown y sql; un listado en cualquier otro lenguaje, o sin lenguaje, se compone en color. Lee el listado entero, así que un comentario o una cadena que ocupa varias líneas sigue siendo un solo elemento. En un listado console, una línea que empieza por un indicador ($ , % , # , > , >>> , PS …> ) es lo que escribió el usuario (prompt), y cualquier otra línea es lo que imprimieron los programas (output).

Una aplicación conecta su propio resaltador (Shiki, Prism, highlight.js) con registerCodeHighlighter. Las configuraciones son datos serializables, así que la función se registra en el motor, no se escribe en codeStyle:

import { registerCodeHighlighter } from 'postext';
 
// fn(code, lang) devuelve las líneas del listado, cada una como tramos cuyos textos, unidos, forman la línea.
registerCodeHighlighter('rust', (code) => code.split('\n').map((line) => [
  { text: line, token: line.trimStart().startsWith('//') ? 'comment' : undefined },
]));
registerCodeHighlighter('*', null); // quita el registrado para todos los lenguajes

Un resaltador registrado para un lenguaje tiene prioridad sobre uno registrado para '*', que a su vez la tiene sobre el analizador integrado. Un tramo nombra una clase de elemento en token (coloreada por tokens) o un color propio (un hex de CSS). Un resaltador que devuelve undefined, lanza una excepción o devuelve líneas que, unidas, no forman las del listado se pasa por alto. La composición lee el registro al componer un listado: registra antes de construir, y en un web worker (el Sandbox compone en uno) registra dentro del worker.

#Código en línea

codeStyle.inline compone el texto entre comillas invertidas en una letra de código: como una unidad, igual que un chip, que una línea nunca parte. Sin fijar, el código en línea conserva la letra del texto.

#Cómo se compone un listado

• Una línea por cada línea del fuente. Las líneas se construyen con los avances de la propia letra del código, no con el algoritmo de corte de párrafos: los espacios conservan su ancho, una serie de ellos se mantiene y los espacios del principio sangran. Un listado en un libro de derecha a izquierda se lee de izquierda a derecha, con sus líneas compuestas desde el lado opuesto de la caja, como una cita de izquierda a derecha, y sus números en el margen, a su izquierda. En un libro vertical, un listado sigue el flujo vertical (con su texto latino tumbado, como lo compone el texto vertical) y no lleva números de línea.
• Partición. Un listado más alto que el espacio que queda se parte entre líneas a través de columnas y páginas, cada parte enmarcada como una caja propia, sin dejar nunca menos de splitMinLines líneas a un lado; el resto de una línea partida se queda con ella si cabe otro corte.
• Salidas. El canvas, el visor HTML y el PDF pintan las líneas y la caja tal como se compusieron. El visor HTML conserva los espacios (white-space: pre), así que una selección copia el listado con su sangría y un salto de línea tras cada línea del fuente, sin números ni marcas de continuación. Un PDF etiquetado compone cada listado como un párrafo que contiene un elemento Code, con glifos de espacio reales y sus números y marcas de continuación como artefactos. El EPUB de maquetación fluida escribe <pre><code class="language-…"> con los colores de los elementos y una hoja de estilo sacada de codeStyle; el EPUB de maquetación fija es la versión impresa.
• Fuentes. El Sandbox y configFontFamilies cargan la letra del código cuando el texto tiene una valla (o la configuración tiene una sección codeStyle), en sus pesos normal y negrita, redonda y cursiva; el PDF incrusta las letras que usan las líneas.

#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.

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' } },
    },
  ],
};

:::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.
:::

#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, tabla o grupo :::columns más alto 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. 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).
• 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). 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.

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.

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

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— 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 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.

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

:::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.

#Partes

La propiedad parts configura las páginas separadoras de parte que un documento abre con un contenedor :::part{number="…" title="…"} — la página «Parte I — Fundamentos» que agrupa una serie de capítulos. Una parte ocupa siempre una página propia: el contenedor salta a una página nueva con la paridad configurada, la convierte en una página de una sola columna cuya área de cuerpo sale de parts.margins, compone el diseño de apertura sobre la página entera y vuelve a saltar tras la valla de cierre para que el siguiente capítulo (con su propio breakBefore.parity) empiece limpio — con los valores por defecto de H1 eso produce la secuencia clásica: página de parte en recto, verso en blanco, capítulo en el siguiente recto.

const config: PostextConfig = {
  parts: {
    breakBefore: { parity: 'odd' },
    breakAfter: { enabled: true, parity: 'any' },
    margins: { top: { value: 9, unit: 'cm' }, left: { value: 3, unit: 'cm' }, right: { value: 3, unit: 'cm' } },
    design: {
      elements: [
        {
          kind: 'text', id: 'number', content: 'Parte {numberRoman}',
          fontSize: { value: 12, unit: 'pt' }, fontWeight: 600, align: 'left',
          placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 3, unit: 'cm' }, y: { value: 5, unit: 'cm' } }, size: { width: 'auto', height: 'auto' } },
        },
        {
          kind: 'text', id: 'title', content: '{titleText}',
          fontSize: { value: 28, unit: 'pt' }, fontWeight: 700, align: 'left', overflow: 'wrap',
          placement: { anchor: { to: '#number', edge: 'below' }, size: { width: { value: 15, unit: 'cm' }, height: 'auto' } },
        },
      ],
    },
    bodyStyle: { fontSize: { value: 11, unit: 'pt' }, numberColor: { hex: '#AA0000', model: 'hex' } },
  },
};

:::part{number="I" title="Fundamentos"}
1. El farol y sus partes
2. Recortar la mecha
3. Leer el tiempo
:::
 
# El farol y sus partes

#Marcadores del diseño de parte

El diseño resuelve el conjunto de marcadores de encabezado con los valores propios de la parte: {titleText} es el title de la valla; {number} el number tal como se escribió; {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} lo reformatean — el número se interpreta como decimal, como numeral romano o como numerales chinos, con o sin las palabras que los rodean ("IV", "iv", "4", "４", "四", "卷四" y "第四卷" dan {numberDecimal} = 4) y resuelven a '' para cualquier otra cosa. También están disponibles {partTitle} / {partNumber}, {chapterTitle} / {chapterNumber} (el capítulo anterior a la parte), {pageNumber}, {totalPages}, {bookTotalPages} y los marcadores de metadatos. {attr.<key>} lee los atributos del H1 del capítulo actual.

#El diseño del verso

versoDesign decora la página que sigue a la de parte cuando esa página no tiene contenido: el reverso de la hoja separadora. La parte por sí sola nunca deja esa página en blanco. breakAfter.parity vale 'any' por defecto, así que el contenido tras la valla empieza en la página siguiente salvo que algo pida una paridad:

• El título del capítulo siguiente. El breakBefore por defecto del H1 es 'always-odd', y 'odd' hace lo mismo tras una página de parte en recto: el capítulo pasa al recto siguiente y el verso queda en blanco. El diseño del verso se pinta.
• parts.breakAfter: { enabled: true, parity: 'odd' }. La propia parte pide el recto siguiente, haga lo que haga el título siguiente. Úsalo cuando los capítulos puedan abrir en cualquier cara (breakBefore.parity: 'any', o breakBefore.enabled: false).

Sin ninguno de los dos, el capítulo abre en el verso y no se dibuja diseño de verso. Con breakAfter.enabled: false el contenido continúa en la propia página de parte. El verso toma la paleta de la parte, así que un palette="band=#…" en la valla también lo recolorea.

parts: {
  breakBefore: { parity: 'odd' },
  breakAfter: { enabled: true, parity: 'odd' },   // siempre queda un verso en blanco que pintar
  versoDesign: {
    elements: [{
      kind: 'box', id: 'campo',
      style: { backgroundColor: { hex: '#b07d2b', model: 'hex', paletteId: 'band' } },
      placement: { anchor: { to: 'page', edge: 'top-left' }, size: { width: 'fill', height: 'fill' } },
    }],
  },
}

Una parte que cierra su capítulo. En un libro maquetado capítulo a capítulo (el Sandbox, buildBundle), una valla :::part puede ser un capítulo por sí sola, o el final de uno. Su página de parte es entonces la última del capítulo, y el capítulo siguiente asume lo que la parte aún debe: aplica breakAfter antes de su primer bloque y pinta versoDesign en su primera página cuando esta queda en blanco. Las páginas salen como saldrían con el libro entero en un solo documento. Tras la valla solo pueden venir directivas que no colocan nada (:::numbering, :::space); cualquier otra cosa es contenido del capítulo, que entonces hace el salto por sí mismo. Un capítulo vacío justo después de la parte es una página propia: esa página es el verso. Un anfitrión que maqueta los capítulos por su cuenta lo obtiene de continuationAfter(), que devuelve afterPartPage: true para un capítulo que termina con una parte; pásalo en la continuation del capítulo siguiente.

#El contenedor :::part

Una línea :::part{number="…" title="…"} abre la parte y un ::: a solas la cierra; los dos atributos son opcionales (por defecto ''). Los bloques intermedios — normalmente la lista de capítulos — fluyen en la columna única de la página de parte con bodyStyle, empezando en margins.top; un cuerpo más largo que la página continúa en páginas normales. La página se clasifica como role: 'part' (VDTPage.partInfo lleva el número y el título), de modo que los elementos de encabezado y pie pueden dirigirse a ella o saltársela con pages: 'part' / pages: 'body'; el backend PDF añade la parte al esquema por encima de sus capítulos. Un cuerpo vacío (:::part{…} seguido directamente de :::) es el caso habitual y también produce la página — dos partes consecutivas nunca comparten una. Un :::part anidado dentro de otra parte se aplana en la exterior.

Un tercer atributo, palette="<id>=<hex>[, <id>=<hex>…]", da a la parte sus propios colores: en la página de parte y en todas las que la siguen — hasta la siguiente parte — cada color de diseño (cabecera, pie, banda de apertura, diseños de parte y de su verso) vinculado a uno de esos ids de paleta toma el valor de la parte en lugar del de la paleta del documento. Así recolorean las secciones de un libro la pestaña de la esquina, el punto de la cabecera y la banda de apertura de capítulo sin un segundo diseño: :::part{number="II" title="…" palette="band=#f6c297"}. El flujo de texto también lo sigue: en esas mismas páginas, todo color del flujo igual al valor base de una entrada de paleta sustituida —títulos, colores de negrita, cursiva y referencias, viñetas y números de lista, etiquetas y barras de pie, texto, filetes y rellenos de tablas (cabecera, cuerpo, filas alternas y el relleno propio de una celda), recuadros (fondo, borde, franja y título) y chips (relleno, contorno y texto)— toma el valor de la parte, de modo que un headings.levels[1].color vinculado a band compone los títulos de cada sección en su propio color. Las muestras de color en línea conservan el color escrito en ellas. Los pares se separan con comas, puntos y comas o espacios, = o : une id y color, y la # es opcional. Una parte sigue vigente después de cerrarse su valla: {partTitle}, {partNumber} y la paleta acompañan al flujo hasta los capítulos posteriores y — mediante continuation.part, que devuelve continuationAfter() — hasta los capítulos compuestos por separado, de modo que el segundo capítulo de una sección muestra la sección en sus cabeceras exactamente igual que el primero.

Dos entradas de la paleta pueden compartir valor base y aun así tomar valores distintos en una parte, cuando la parte sustituye una y no la otra o les da colores distintos. El valor por sí solo no indica de qué entrada viene un color del flujo, así que cada color del flujo se empareja con los ajustes de los que puede venir y toma el valor al que enlazan esos ajustes. Se distinguen:

• los colores del texto de un bloque: el color del texto, los de negrita, cursiva y referencias, la viñeta o el número de lista y el separador que sigue al número. Con bodyText.color vinculado a ink y bodyText.boldColor vinculado a accent, ambos #1a1a1a, una parte con palette="accent=#b8413d" recolorea las negritas y deja el texto; si lo que se vincula a accent es unorderedLists.color, recolorea las viñetas y deja el texto de los elementos;
• cada nivel de encabezado, y cada estilo de encabezado que fija un color;
• el texto de una fila del índice, su número, y su número de página y su subtítulo;
• en cada estilo de recuadro, los rellenos (fondo, franja, pestaña de la etiqueta), el borde, los filetes (del marcador y de la etiqueta) y el texto (título, icono, glifo del marcador, etiqueta);
• cada color de cada estilo de tabla, de chip y de pie. Un estilo de tabla con nombre se distingue de tableStyle, y el estilo de pie de un tipo de recurso de captionStyle. El relleno propio de una celda sigue su propio enlace.

Queda un caso que se resuelve por valor: ajustes de sitios distintos que fijan el mismo color de un bloque. Por ejemplo, bodyText.color, bodyText.blockquote.color, el color de un estilo de párrafo y el body.color de un estilo de recuadro fijan todos el color del texto de un bloque. Cuando dos de ellos enlazan a entradas que comparten valor base y la parte las separa, el color toma la sustitución (la última escrita, si se sustituyen las dos). Da a esas entradas valores base propios.

const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => márgenes rellenados desde la página, bodyStyle desde el cuerpo / las listas
 
const minimal = stripPartsDefaults(config.parts);
// => undefined cuando solo quedan valores estáticos por defecto

#Estilos de encabezado

La propiedad headingStyles declara estilos con nombre que un documento aplica a un encabezado con # Título {style="<id>"}. Un estilo hace dos cosas. Sobrescribe la tipografía, el diseño y la numeración del nivel del encabezado — cualquier campo de una entrada de nivel salvo level (fuente, cuerpo, color, breakBefore, span, advancedDesign, textTransform, hidden, numberingTemplate…) — y gobierna la sección que el encabezado abre: sus páginas, hasta el siguiente encabezado del mismo nivel o superior, toman las cabeceras, la geometría de página, la tipografía de cuerpo y la paleta del estilo. Así los preliminares de un libro (un prólogo a una sola columna ancha, con folios en romanos y bandas azules) conviven en un manual a dos columnas y numeración decimal sin una segunda configuración.

const config: PostextConfig = {
  headingStyles: [
    {
      id: 'preliminar',
      numbered: false,
      breakBefore: { enabled: true, parity: 'odd' },
      span: 'page',
      advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bandas, `{titleText}` */] } },
      header: { elements: [/* folio | filete | `{title}. {subtitle}` */] },
      margins: { left: { value: 50, unit: 'mm' }, right: { value: 17, unit: 'mm' } },
      layout: { layoutType: 'single' },
      bodyStyle: { fontSize: { value: 10.5, unit: 'pt' }, textAlign: 'justify' },
      palette: { band: '#547396' },
    },
  ],
};

# Prólogo {style="preliminar"}

Una sección se cierra en el siguiente encabezado del mismo nivel o superior: un # sin estilo tras uno con estilo vuelve a las cabeceras y la geometría del documento; uno con estilo abre su propia sección. Las páginas que la sección deja en blanco por paridad le pertenecen, como ocurre con los títulos de capítulo.

Un salto de página no sustituye al salto del propio encabezado. Un estilo hereda el breakBefore de su nivel (el del nivel 1 es, por defecto, { enabled: true, parity: 'always-odd' }), y el encabezado lo aplica esté donde esté, también justo después de un :::pagebreak. El salto de página abre una página nueva, y el encabezado pide después, igualmente, su lado del pliego. Con parity: 'odd', un salto que cae en una página par va seguido de una página en blanco, de modo que el encabezado abre en la siguiente impar. Con 'always-odd' se añade además la página separadora, y el salto de página no cambia nada, porque el encabezado habría abierto esa página de todos modos. Un estilo que debe empezar en la página que abre un salto manual, como un índice detrás de la portada, desactiva su propio salto:

headingStyles: [
  // Empieza donde lo deja el texto: en la página que abrió el `:::pagebreak` anterior.
  { id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],

Para conservar una página propia sin elegir lado, usa en su lugar breakBefore: { parity: 'any' } y prescinde del :::pagebreak.

A qué sección pertenece una página. Las cabeceras y la paleta se eligen por página, no por encabezado. Una página toma la sección vigente tras el último cambio de sección que hay en ella: cuando una sección termina y otra empieza en la misma página — dos letras cortas de un diccionario, por ejemplo —, la página lleva las cabeceras y la paleta de la segunda; cuando una sección con estilo termina a mitad de página en un encabezado sin estilo, la página vuelve a las del documento. {chapterTitle} sigue la misma regla: una página donde se encuentran dos capítulos muestra el título del segundo. Las páginas en blanco siguen la regla de los títulos de capítulo: una página en blanco de paridad (blankForParity) pertenece a la sección que se abre tras ella, y la separadora que añade un salto 'always-odd' / 'always-even' (blankForForce), a la sección anterior. Una página divisoria de parte cierra la sección abierta.

# A {style="letra"}
 
Aardvark, ábaco.
 
# B {style="letra"}
 
Babel, babero… (sigue en la página siguiente)

Las dos letras empiezan en la página 1, así que la página 1 toma las cabeceras de la sección B: una pestaña de uñero puesta en la cabecera del estilo dice «B» ahí, y ninguna página lleva la pestaña de la «A». Da a cada sección una página propia (breakBefore) cuando todas necesitan su pestaña. Apéndices con letra tras capítulos numerados, y una página de dedicatoria que el índice y los marcadores del PDF incluyen pero que la página no titula:

headingStyles: [
  { id: 'apendice', numberingTemplate: 'Apéndice {1:A}' },
  { id: 'silencioso', hidden: true, numbered: false },
],

# Dedicatoria {style="silencioso"}
 
Para M., que leyó todos los borradores.
 
# Método
 
…
 
# Cuestionario {style="apendice" startAt=1}
 
# Datos en bruto {style="apendice"}

Con numberingTemplate: '{1}.' en el nivel 1, los capítulos imprimen 1., 2.…, y los apéndices Apéndice A y Apéndice B. La dedicatoria abre su página (el breakBefore de su nivel), imprime solo su párrafo y sigue apareciendo como Dedicatoria en :::toc, en las cabeceras con {chapterTitle} y en los marcadores del PDF; añade toc: false al estilo para dejarla fuera del índice. Una lámina o un mapa que se compone como H1 en mitad de un capítulo pide lo contrario que la dedicatoria: un estilo con runningChapter: false (normalmente con numbered: false y toc: false) mantiene las cabeceras en el capítulo que interrumpe.

const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => sobrescrituras de nivel normalizadas, márgenes tomados de la página, bodyStyle del cuerpo
 
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined cuando no queda ningún estilo