Configuración: listas y matemáticas

#Listas no ordenadas

La propiedad unorderedLists controla cómo se renderizan las listas con viñetas (-, *, +) y las listas de tareas estilo GFM (- [ ], - [x]). Se admiten hasta cinco niveles de anidamiento.

#Valores por defecto de listas no ordenadas

#Extensiones para listas de tareas

Los elementos de tarea GFM (- [ ] …, - [x] …) se renderizan como elementos de lista no ordenada con una casilla en lugar de la viñeta. El motor dibuja la casilla él mismo, un cuadrado en contorno con una marca cuando la tarea está hecha: no se pide a ninguna fuente, así que es igual en todas las máquinas, en el canvas, en el PDF, en el HTML y en el EPUB, y las tecnologías de apoyo leen ☐ o ☑. Su lado mide 0,6 em del tamaño del marcador (bulletFontSize, o el fontSize del nivel), y ese es el espacio que ocupa antes del gap; al tamaño del texto se apoya en la línea base de la primera línea del elemento. Su trazo sigue el fontWeight del marcador y su color, el color del marcador. Los siguientes campos solo aplican a las tareas:

#Sobrescrituras por nivel (listas no ordenadas)

Cada entrada de levels apunta a una profundidad (1–5) y puede sobrescribir cualquiera de las siguientes propiedades:

Encadenamiento de sangrías. El nivel 1 arranca siempre con el indent general (por defecto 0 em — las viñetas quedan pegadas al borde de la columna). Para los niveles 2–5, si dejas indent sin definir el motor coloca la viñeta en el inicio de texto del nivel anterior (sangría del padre + ancho de viñeta + gap). Define un indent explícito en un nivel para romper el encadenamiento y fijar esa profundidad donde prefieras.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Listas ordenadas

La propiedad orderedLists controla las listas numeradas (1., 2), etc.). Se admiten hasta cinco niveles de anidamiento y cada profundidad puede usar un formato de numeración distinto.

#Valores por defecto de listas ordenadas

#Sobrescrituras por nivel (listas ordenadas)

Cada entrada de levels puede sobrescribir numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset y el estilo del separador (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) — se aplica el mismo encadenamiento de sangrías que en las listas no ordenadas. El estilo del separador de un nivel hereda el estilo de su propio número salvo que se indique el ajuste general del separador.

Alineación a la derecha. El pipeline mide el número formateado más ancho dentro de cada recorrido e indenta todos los elementos de ese recorrido para que los marcadores queden alineados por su borde derecho. Una lista de diez elementos renderizada como 1. – 10. desplaza los números de un dígito a la derecha para que el separador caiga siempre en la misma columna.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

Esto produce la clásica combinación anidada:

1. Primer elemento
   a. Subelemento
      i) Nota profunda
   b. Subelemento
2. Segundo elemento

La jerarquía de los documentos chinos (GB/T 15834—2011, anexo B.3) tiene cinco niveles: 一、, luego （一）, luego 1., luego （1） y luego ①:

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#Matemáticas

La propiedad math controla cómo se analizan y se renderizan las fórmulas LaTeX escritas entre delimitadores $...$ (en línea) y $$...$$ (en bloque). El motor subyacente es MathJax (el paquete mathjax-full) en modo de salida SVG, rasterizado en el canvas e incrustado como glifos escalables en el PDF.

interface MathConfig {
  enabled?: boolean;        // Renderizar LaTeX. Si es false, los spans salen como TeX literal.
  fontSizeScale?: number;   // × el tamaño del texto que rodea la fórmula (el del cuerpo en las fórmulas en bloque).
  color?: ColorValue;       // Color de la fórmula; hereda del cuerpo si se omite.
  marginTop?: Dimension;    // Espacio encima de las fórmulas en bloque.
  marginBottom?: Dimension; // Espacio mínimo debajo; el snap a rejilla puede aumentarlo.
  indentAfterDisplay?: boolean; // Sangrar el párrafo que sigue a una fórmula en bloque.
  keepWithLeadIn?: boolean; // Mantener una fórmula en bloque con la línea que la introduce.
  equationNumbering?: {      // Numerar las fórmulas en bloque que llevan un \label.
    enabled?: boolean;           // por defecto true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numera por capítulo
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': lo que imprimen la fórmula y \eqref
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

Tamaño de las fórmulas, cambia en postext 1.5. MathJax da la caja de cada fórmula en ex, y un ex de su fuente TeX mide 0,442 em. Hasta postext 1.4 el motor lo tomaba por medio em, así que cada fórmula se componía en torno a un 13 % más grande que bodyText.fontSize × fontSizeScale. Ahora las fórmulas salen del tamaño documentado, y las líneas y páginas con matemáticas se recomponen. Una configuración escrita en código para la 1.4 conserva el tamaño de sus fórmulas de la 1.4 si pasa por pinLegacyMathSize, de postext/bundle, una sola vez y tal como está escrita:

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // fórmulas, y el espacio alrededor de las fórmulas en bloque, como las componía la 1.4

Hay otros cambios de reglas en la 1.5 que también pueden mover sus páginas: los saltos de los encabezados, el espacio en torno a una figura en línea (en el texto corrido y en los recuadros), las marcas en línea de sus encabezados, el tamaño de sus letras capitales, el sitio que se deja bajo una línea de dos puntos para la lista que introduce, las líneas que deja de un párrafo o de un elemento de lista el corte de una caja, los cortes de línea tras una raya, la composición del texto en bandera, la división de un párrafo bajo un encabezado, los cortes de línea tras el guion de un compuesto y el espacio bajo un contenedor :::paragraphs. migrateConfig, aplicada una sola vez con el markdown que compone la configuración, fija los que ese texto necesita, también el tamaño de las fórmulas (ver Paquetes escritos por postext 1.4 o anterior):

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // saltos de encabezado, fórmulas, huecos en línea, marcas de los encabezados, capitales, dos puntos, cortes de las cajas, rayas, compuestos, texto en bandera, divisiones bajo un encabezado y espacio bajo los contenedores como los componía la 1.4

Así se evita lo que moverían esos cambios de reglas, pero no se conservan todas las páginas de la 1.4. La 1.5 corrige además errores de composición, y una corrección no tiene fijación: una configuración antigua la recibe igual que una nueva, así que una página a la que afecte aún puede moverse. Entre ellas: un encabezado a toda la página sin diseño propio se mide a lo ancho de la página y se compone con el interlineado de su nivel; en un diseño de encabezado no se reserva nada bajo la línea base de una letra capital; una capital toma el color de la paleta de la sección y se compone también en un texto de diseño cuyo overflow no es 'wrap', que entonces pasa de línea; un párrafo dentro de una caja pinta el tracking con el que se midió; una caja partida conserva la columna del icono en cada fragmento; una línea de una caja que estiraría sus espacios más de 3× se compone en bandera, como en el texto corrido; la palanca de los párrafos flojos nunca deja una línea justificada más ancha de lo que permite maxWordSpacing; una caja flotante conserva un marginBottom (en una banda superior) o un marginTop (en una banda inferior) mayor que el hueco de los flotantes; un texto de diseño centrado o alineado a la derecha con tracking (un titulillo, el título de una apertura) se coloca por sus letras, sin el tracking que sigue a la última; bajo una apertura a toda la página, el texto que abre la segunda columna empieza donde empezaría el texto justo debajo de la apertura, también cuando a la apertura le sigue un encabezado; la línea de puntos del índice se detiene antes del número de página en una fuente cuyo kerning separa una serie de puntos; un titulillo lee el encabezado tal como está escrito, sin espacio donde una de sus líneas termina tras un guion o una raya o dentro de una palabra cortada por su ancho (MEDIOAMBIENTALES, no MEDIOAMBIENTALE S), y el {titleText} del diseño de un encabezado lo lee igual (thousand-colour, no thousand- colour); un texto anclado al pie o al centro de la franja de un diseño de encabezado mantiene la franja lo bastante alta para contenerlo, así que ya no sube sobre el texto que precede al encabezado; una palabra más ancha que su línea, cortada junto a un guion que ya lleva, se corta detrás de ese guion y no recibe otro; el elemento que sigue a una lista anidada en otra toma el itemSpacing de su propia lista, no el de la anidada; y el resto de una palabra cortada por ser más ancha que su línea conserva sus propios puntos de corte, de modo que una dirección web sigue cortándose por sus junturas y un compuesto por sus guiones en lugar de por las sílabas del diccionario.

pinLegacyMathSize multiplica la escala por 1,1312 (0,5 ÷ 0,442) y divide por el mismo factor los márgenes de las fórmulas en bloque en em. La escala sola no basta en un libro con fórmulas en bloque: sus márgenes son medidas del tamaño de la propia fórmula, así que crecerían el mismo 13 % y empujarían hacia abajo el texto que las sigue. Escritos para los márgenes por defecto, los tres valores son:

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // fórmulas tan grandes como las componía la 1.4, con el espacio que les dejaba alrededor

Donde la configuración estaba guardada, el motor puede saberlo y lo hace por ti: openBundle / readBundle con un paquete .postext escrito antes de la 1.5 (ver Paquetes escritos por postext 1.4 o anterior), y el Sandbox con los libros, la configuración de trabajo y los archivos postext-config.json que guardó entonces (ver Sandbox → Persistencia). Se leen a través de migrateConfig, que fija el tamaño (pinLegacyMathSize): fontSizeScale pasa a ser la escala guardada (1 si no había) × 1,1312, y un margen de las fórmulas en bloque en em o rem — una medida del tamaño de la propia fórmula — se divide por el mismo factor, de modo que el espacio alrededor de una fórmula en bloque queda como lo dejaba la 1.4 (los 0,8 em por defecto pasan a 0,7072 em). Un margen en una unidad de página (pt, mm…) se queda como está, y también una configuración con enabled: false o una cuyo libro no tiene ningún $. El libro antiguo se compone entonces como lo componía la 1.4, y su sección math muestra el tamaño con el que se compone. Para componer ese libro al tamaño actual, restablece esos valores: Fórmulas → Escala de tamaño, Margen superior de las fórmulas en bloque y Margen inferior de las fórmulas en bloque en el Sandbox, o en código:

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // tamaño y márgenes actuales

Ecuaciones numeradas. Una fórmula en bloque con número ocupa toda su medida (la columna, o el ancho interior del recuadro que la contiene): la ecuación va centrada y su número alineado a la derecha, en la línea de la ecuación, en cada fila numerada de un align. El número sale de un \label{eq:x} (desde postext 1.19): las fórmulas con etiqueta, y las filas con etiqueta de un align, gather, alignat, flalign o eqnarray, se numeran en orden de lectura según equationNumbering, salvo que una fila diga \nonumber o \notag. Entornos como equation no se numeran por sí solos: una fórmula sin etiqueta no lleva número. \tag{…} imprime el texto que le des, entre paréntesis, y \tag*{…}, tal cual; ninguno de los dos cuenta, y un \label a su lado le da nombre. Una ecuación numerada más ancha que su medida desborda por la derecha, como cualquier fórmula en bloque. (Hasta postext 1.4, una fórmula con \tag no llegaba a dibujarse; hasta la 1.18, solo \tag numeraba una fórmula.)

\eqref{eq:x} en el texto imprime el número en su format, (3), y \ref{eq:x}, el número solo; lo mismo hacen :ref{id="eq:x"} y @eq:x (ver Referencias cruzadas), y dentro de una fórmula \eqref lo imprime como texto. En un libro compuesto capítulo a capítulo, el contador sigue desde el capítulo anterior: continuationAfter lo lleva en LayoutContinuation.statementCounters (equation), y el esquema del libro da a cada etiqueta su número (OutlineEntry.numberLabel), de modo que una referencia a una ecuación de otro capítulo lo imprime.

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1), (1.2)… (2.1)
}

El resolver y el stripper siguen el mismo patrón que las otras secciones:

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#Arrancar el motor de fórmulas

MathJax se carga bajo demanda, no con el resto del motor. Cuando compones en el hilo principal, arráncalo antes de construir un documento con fórmulas:

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // carga MathJax una vez; las llamadas siguientes se resuelven al instante
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Hasta que el motor arranca, las fórmulas son provisionales. Cada una se compone como una caja gris de tamaño estimado. Si un documento con fórmulas se compone sin haber llamado nunca a initMathEngine(), la consola muestra un aviso, una sola vez.
• El worker de composición lo arranca por ti. Un build en postext/worker llama a initMathEngine() por su cuenta cuando el markdown contiene un $.
• Componer ya, y otra vez cuando esté listo. isMathReady() indica si el motor está en marcha. onMathReady(fn) llama a fn en cuanto lo está (al instante si ya lo estaba) y devuelve una función que cancela la llamada. Un editor puede mostrar las cajas provisionales enseguida y volver a componer cuando llega MathJax; mientras initMathEngine() está en curso no se imprime ningún aviso.
• Fallos. initMathEngine() se rechaza si MathJax no puede cargarse, y una llamada posterior lo vuelve a intentar.
• Con cualquier bundler, en Node o desde una CDN. MathJax viaja dentro del paquete como un único módulo preempaquetado (unos 1,8 MB sin comprimir, que solo descarga initMathEngine). El import { initMathEngine } from 'https://esm.sh/postext' de siempre funciona; no hace falta ?bundle. El paquete mathjax-full solo hace falta para compilar postext, así que instalar postext no lo instala. MathJax y el analizador mhchem que incluye tienen licencia Apache-2.0: sus avisos y el texto de la licencia viajan junto al módulo, en dist/math/THIRD_PARTY_LICENSES.txt.
• Un motor por página. El motor y su caché de fórmulas renderizadas son compartidos por todo lo que importa postext en el mismo contexto de JavaScript (consulta Estado global compartido en una página).

Para la gramática del documento ($...$, $$...$$, cómo escapar un dólar literal), consulta Formato del documento.