Configuració: llistes i matemàtiques

#Llistes no ordenades

La propietat unorderedLists controla com es renderitzen les llistes amb pics (-, *, +) i les llistes de tasques d'estil GFM (- [ ], - [x]). S'admeten fins a cinc nivells d'imbricació.

#Valors per defecte de les llistes no ordenades

#Extensions per a llistes de tasques

Els elements de tasca GFM (- [ ] …, - [x] …) es renderitzen com a elements de llista no ordenada amb una casella en lloc del pic. El motor dibuixa la casella ell mateix, un quadrat en contorn amb una marca quan la tasca està feta: no es demana a cap font, de manera que és igual a totes les màquines, al canvas, al PDF, a l'HTML i a l'EPUB, i les tecnologies de suport llegeixen ☐ o ☑. El costat fa 0,6 em de la mida del marcador (bulletFontSize, o el fontSize del nivell), i aquest és l'espai que ocupa abans del gap; a la mida del text es recolza sobre la línia de base de la primera línia de l'element. El traç segueix el fontWeight del marcador i el color, el color del marcador. Els camps següents només s'apliquen a les tasques:

#Sobreescriptures per nivell (llistes no ordenades)

Cada entrada de levels apunta a una profunditat (1–5) i pot sobreescriure qualsevol de les propietats següents:

Encadenament de sagnats. El nivell 1 arrenca sempre amb l'indent general (per defecte 0 em — els pics queden enganxats a la vora de la columna). Per als nivells 2–5, si deixes indent sense definir, el motor col·loca el pic a l'inici de text del nivell anterior (sagnat del pare + amplada del pic + gap). Defineix un indent explícit en un nivell per trencar l'encadenament i fixar aquesta profunditat on prefereixis.

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

#Llistes ordenades

La propietat orderedLists controla les llistes numerades (1., 2), etc.). S'admeten fins a cinc nivells d'imbricació i cada profunditat pot fer servir un format de numeració diferent.

#Valors per defecte de les llistes ordenades

#Sobreescriptures per nivell (llistes ordenades)

Cada entrada de levels pot sobreescriure numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset i l'estil del separador (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) — s'hi aplica el mateix encadenament de sagnats que a les llistes no ordenades. L'estil del separador d'un nivell hereta l'estil del seu propi número, tret que s'indiqui l'opció general del separador.

Alineació a la dreta. El pipeline mesura el número formatat més ample dins de cada tram i sagna tots els elements d'aquest tram perquè els marcadors quedin alineats per la vora dreta. Una llista de deu elements mostrada com 1. – 10. desplaça els números d'una xifra cap a la dreta perquè el separador caigui sempre a la mateixa columna.

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

Això produeix la clàssica combinació niada:

1. Primer element
   a. Subelement
      i) Nota profunda
   b. Subelement
2. Segon element

La jerarquia dels documents xinesos (GB/T 15834—2011, annex B.3) té cinc nivells: 一、, després （一）, després 1., després （1） i després ①:

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àtiques

La propietat math controla com s'analitzen i es mostren les fórmules LaTeX escrites entre delimitadors $...$ (en línia) i $$...$$ (en bloc). El motor subjacent és MathJax (el paquet mathjax-full) en mode de sortida SVG, rasteritzat al canvas i incrustat com a glifs escalables al PDF.

interface MathConfig {
  enabled?: boolean;        // Mostrar el LaTeX. Si és false, els spans surten com a TeX literal.
  fontSizeScale?: number;   // × la mida del text que envolta la fórmula (la del cos en les fórmules en bloc).
  color?: ColorValue;       // Color de la fórmula; hereta el del cos si s'omet.
  marginTop?: Dimension;    // Espai damunt de les fórmules en bloc.
  marginBottom?: Dimension; // Espai mínim a sota; l'ajust a la retícula el pot augmentar.
  indentAfterDisplay?: boolean; // Sagnar el paràgraf que segueix una fórmula en bloc.
  keepWithLeadIn?: boolean; // Mantenir una fórmula en bloc amb la línia que la introdueix.
  equationNumbering?: {      // Numerar les fórmules en bloc que porten un \label.
    enabled?: boolean;           // per defecte true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numera per capítol
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': el que imprimeixen la fórmula i \eqref
  };
}

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

Mida de les fórmules, canvia a postext 1.5. MathJax dona la caixa de cada fórmula en ex, i un ex de la seva font TeX mesura 0,442 em. Fins a postext 1.4 el motor el prenia per mig em, de manera que cada fórmula es componia al voltant d'un 13 % més gran que bodyText.fontSize × fontSizeScale. Ara les fórmules surten de la mida documentada, i les línies i pàgines amb matemàtiques es recomponen. Una configuració escrita en codi per a la 1.4 conserva la mida de les fórmules de la 1.4 si passa per pinLegacyMathSize, de postext/bundle, una sola vegada i tal com està escrita:

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // fórmules, i l'espai al voltant de les fórmules en bloc, com les componia la 1.4

Hi ha altres canvis de regles a la 1.5 que també poden moure les teves pàgines: els salts dels encapçalaments, l'espai al voltant d'una figura en línia (en el text corregut i en els requadres), les marques en línia dels encapçalaments, la mida de les caplletres, el lloc que es deixa sota una línia acabada en dos punts per a la llista que introdueix, les línies que el tall d'una caixa deixa d'un paràgraf o d'un element de llista, els salts de línia després d'un guió llarg, la composició del text en bandera, la divisió d'un paràgraf sota un encapçalament, els salts de línia després del guionet d'un compost i l'espai sota un contenidor :::paragraphs. migrateConfig, aplicada una sola vegada amb el markdown que compon la configuració, fixa els que aquest text necessita, també la mida de les fórmules (consulta Paquets escrits per postext 1.4 o anterior):

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // salts d'encapçalament, fórmules, espais en línia, marques dels encapçalaments, caplletres, dos punts, talls de les caixes, guions llargs, compostos, text en bandera, divisions sota un encapçalament i espai sota els contenidors com els componia la 1.4

Així s'evita el que moverien aquests canvis de regles, però no es conserven totes les pàgines de la 1.4. La 1.5 corregeix a més errors de composició, i una correcció no té fixació: una configuració antiga la rep igual que una de nova, de manera que una pàgina afectada encara es pot moure. Entre aquestes correccions: un encapçalament a tota la pàgina sense disseny propi es mesura a l'amplada de la pàgina i es compon amb l'interlineat del seu nivell; en un disseny d'encapçalament no es reserva res sota la línia de base d'una caplletra; una caplletra pren el color de la paleta de la secció i es compon també en un text de disseny el overflow del qual no és 'wrap', que llavors salta de línia; un paràgraf dins d'una caixa pinta el tracking amb què es va mesurar; una caixa partida conserva la columna de la icona a cada fragment; una línia d'una caixa que estiraria els espais més de 3× es compon en bandera, com en el text corregut; la palanca dels paràgrafs fluixos no deixa mai una línia justificada més ampla del que permet maxWordSpacing; una caixa flotant conserva un marginBottom (en una banda superior) o un marginTop (en una banda inferior) més gran que l'espai dels flotants; un text de disseny centrat o alineat a la dreta amb tracking (un titolet, el títol d'una obertura) es col·loca per les seves lletres, sense el tracking que segueix l'última; sota una obertura a tota la pàgina, el text que obre la segona columna comença on començaria el text just a sota de l'obertura, també quan l'obertura va seguida d'un encapçalament; la línia de punts de l'índex s'atura abans del número de pàgina en una font el kerning de la qual separa una sèrie de punts; un titolet llegeix l'encapçalament tal com està escrit, sense espai on una de les seves línies acaba després d'un guionet o un guió llarg o dins d'una paraula tallada per l'amplada (MEDIOAMBIENTALES, no MEDIOAMBIENTALE S), i el {titleText} del disseny d'un encapçalament el llegeix igual (thousand-colour, no thousand- colour); un text ancorat al peu o al centre de la franja d'un disseny d'encapçalament manté la franja prou alta per contenir-lo, de manera que ja no puja sobre el text que precedeix l'encapçalament; una paraula més ampla que la seva línia, tallada al costat d'un guionet que ja porta, es talla darrere d'aquest guionet i no en rep cap altre; l'element que segueix una llista niada dins d'una altra pren l'itemSpacing de la seva pròpia llista, no el de la niada; i la resta d'una paraula tallada per ser més ampla que la seva línia conserva els seus propis punts de tall, de manera que una adreça web continua tallant-se per les juntures i un compost pels guionets en lloc de per les síl·labes del diccionari.

pinLegacyMathSize multiplica l'escala per 1,1312 (0,5 ÷ 0,442) i divideix pel mateix factor els marges de les fórmules en bloc en em. Amb l'escala sola no n'hi ha prou en un llibre amb fórmules en bloc: els seus marges són mesures de la mida de la fórmula mateixa, de manera que creixerien el mateix 13 % i empènyerien cap avall el text que les segueix. Escrits per als marges per defecte, els tres valors són:

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // fórmules tan grans com les componia la 1.4, amb l'espai que els deixava al voltant

On la configuració estava desada, el motor ho pot saber i ho fa per tu: openBundle / readBundle amb un paquet .postext escrit abans de la 1.5 (consulta Paquets escrits per postext 1.4 o anterior), i el Sandbox amb els llibres, la configuració de treball i els fitxers postext-config.json que va desar llavors (consulta Sandbox → Persistència). Es llegeixen a través de migrateConfig, que fixa la mida (pinLegacyMathSize): fontSizeScale passa a ser l'escala desada (1 si no n'hi havia) × 1,1312, i un marge de les fórmules en bloc en em o rem — una mesura de la mida de la fórmula mateixa — es divideix pel mateix factor, de manera que l'espai al voltant d'una fórmula en bloc queda com el deixava la 1.4 (els 0,8 em per defecte passen a 0,7072 em). Un marge en una unitat de pàgina (pt, mm…) es queda com està, i també una configuració amb enabled: false o una el llibre de la qual no té cap $. Llavors el llibre antic es compon com el componia la 1.4, i la seva secció math mostra la mida amb què es compon. Per compondre aquell llibre a la mida actual, restableix aquests valors: Fórmules → Escala de mida, Marge superior de les fórmules en bloc i Marge inferior de les fórmules en bloc al Sandbox, o en codi:

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // mida i marges actuals

Equacions numerades. Una fórmula en bloc amb número ocupa tota la seva mesura (la columna, o l'amplada interior del requadre que la conté): l'equació va centrada i el seu número alineat a la dreta, a la línia de l'equació, a cada fila numerada d'un align. El número surt d'un \label{eq:x} (des de postext 1.19): les fórmules amb etiqueta, i les files amb etiqueta d'un align, gather, alignat, flalign o eqnarray, es numeren en ordre de lectura segons equationNumbering, tret que una fila digui \nonumber o \notag. Entorns com equation no es numeren per si sols: una fórmula sense etiqueta no porta número. \tag{…} imprimeix el text que li donis, entre parèntesis, i \tag*{…}, tal qual; cap dels dos no compta, i un \label al seu costat li dona nom. Una equació numerada més ampla que la seva mesura desborda per la dreta, com qualsevol fórmula en bloc. (Fins a postext 1.4, una fórmula amb \tag no s'arribava a dibuixar; fins a la 1.18, només \tag numerava una fórmula.)

\eqref{eq:x} al text imprimeix el número en el seu format, (3), i \ref{eq:x}, el número sol; el mateix fan :ref{id="eq:x"} i @eq:x (vegeu Referències creuades), i dins d'una fórmula \eqref l'imprimeix com a text. En un llibre compost capítol a capítol, el comptador continua des del capítol anterior: continuationAfter el porta a LayoutContinuation.statementCounters (equation), i l'esquema del llibre dona a cada etiqueta el seu número (OutlineEntry.numberLabel), de manera que una referència a una equació d'un altre capítol l'imprimeix.

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

El resolver i l'stripper segueixen el mateix patró que les altres seccions:

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

#Arrencar el motor de fórmules

MathJax es carrega a demanda, no amb la resta del motor. Quan compons al fil principal, arrenca'l abans de construir un document amb fórmules:

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // carrega MathJax una vegada; les crides següents es resolen a l'instant
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Fins que el motor arrenca, les fórmules són provisionals. Cadascuna es compon com una caixa grisa de mida estimada. Si un document amb fórmules es compon sense haver cridat mai initMathEngine(), la consola mostra un avís, una sola vegada.
• El worker de composició l'arrenca per tu. Un build a postext/worker crida initMathEngine() pel seu compte quan el markdown conté un $.
• Compondre ja, i un altre cop quan estigui a punt. isMathReady() indica si el motor està en marxa. onMathReady(fn) crida fn tan bon punt ho està (a l'instant si ja ho estava) i retorna una funció que cancel·la la crida. Un editor pot mostrar les caixes provisionals de seguida i tornar a compondre quan arriba MathJax; mentre initMathEngine() està en curs no s'imprimeix cap avís.
• Errors. initMathEngine() es rebutja si MathJax no es pot carregar, i una crida posterior ho torna a intentar.
• Amb qualsevol bundler, a Node o des d'una CDN. MathJax viatja dins del paquet com un únic mòdul preempaquetat (uns 1,8 MB sense comprimir, que només baixa initMathEngine). L'import { initMathEngine } from 'https://esm.sh/postext' de sempre funciona; no cal ?bundle. El paquet mathjax-full només cal per compilar postext, de manera que instal·lar postext no l'instal·la. MathJax i l'analitzador mhchem que inclou tenen llicència Apache-2.0: els seus avisos i el text de la llicència viatgen al costat del mòdul, a dist/math/THIRD_PARTY_LICENSES.txt.
• Un motor per pàgina. El motor i la seva memòria cau de fórmules representades són compartits per tot el que importa postext en el mateix context de JavaScript (consulta Estat global compartit en una pàgina).

Per a la gramàtica del document ($...$, $$...$$, com escapar un dòlar literal), consulta Format del document.