>` | una tavolozza discreta | L’aspetto di ogni tipo di token, fuso tipo per tipo con i valori predefiniti (vedi sotto). Un colore collegato alla tavolozza segue `colorPalette` e la tavolozza di una parte. |
| `inline` | `InlineCodeStyleConfig` | non impostato | Codice in linea in un carattere da codice (vedi sotto). Se non è impostato, il codice in linea si compone nel carattere del testo, come prima della 1.23. |
### Colorazione della sintassi
Un piccolo tokenizzatore incorporato nel motore riconosce i token di `js` e `ts` (`javascript`, `jsx`, `typescript`, `tsx`), `json`, `python`, `bash` (`sh`, `zsh`, `shell`), `console` (una sessione di shell), `css`, `html` e `xml` (`svg`), `markdown` e `sql`; un listato in qualunque altro linguaggio, o senza linguaggio, si compone in `color`. Legge l’intero listato, quindi un commento o una stringa che prosegue su più righe resta un solo token. In un listato `console`, una riga che si apre con un prompt (`$ `, `% `, `# `, `> `, `>>> `, `PS …> `) è ciò che l’utente ha digitato (`prompt`) e ogni altra riga è ciò che hanno stampato i programmi (`output`).
| Tipo | Predefinito | Che cosa indica |
| --- | --- | --- |
| `keyword` | `#8b2c8f` | Parole riservate: `const`, `def`, `if`, `SELECT`, il nome di un tag HTML, una at-rule CSS. |
| `string` | `#3d7a2a` | Stringhe, template literal, valori degli attributi. |
| `number` | `#985f00` | Numeri e costanti (`true`, `None`, `null`), colori, entità. |
| `comment` | `#7a7f87`, corsivo | Commenti. |
| `function` | `#2b5fb4` | Un nome seguito da una parentesi; i comandi incorporati della shell. |
| `type` | `#99540a` | Tipi e nomi di classe con l’iniziale maiuscola, selettori CSS. |
| `operator` | il colore del codice | Operatori, pipe e redirezioni della shell. |
| `punctuation` | il colore del codice | Parentesi, separatori. |
| `variable` | `#b23b2e` | Variabili della shell, chiavi JSON, proprietà CSS, attributi HTML, `self`. |
| `meta` | `#985f00` | Decoratori, opzioni da riga di comando (`-l`, `--all`), un doctype. |
| `prompt` | il colore del codice, grassetto | La riga digitata di una sessione di shell. |
| `output` | `#5c6168` | Ciò che hanno stampato i programmi. |
Un’applicazione ospite collega il proprio evidenziatore (Shiki, Prism, highlight.js) con `registerCodeHighlighter`. Le configurazioni sono dati serializzabili, quindi la funzione si registra presso il motore, non si scrive in `codeStyle`:
```ts
import { registerCodeHighlighter } from 'postext';
// fn(code, lang) returns the listing's lines, each as runs whose texts join into the line.
registerCodeHighlighter('rust', (code) => code.split('\n').map((line) => [
{ text: line, token: line.trimStart().startsWith('//') ? 'comment' : undefined },
]));
registerCodeHighlighter('*', null); // remove the one registered for every language
```
Un evidenziatore registrato per un linguaggio ha la precedenza su uno registrato per `'*'`, che a sua volta ha la precedenza sul tokenizzatore incorporato. Un tratto indica un tipo di `token` (colorato da `tokens`) o un proprio `color` (un esadecimale CSS). Un evidenziatore che restituisce `undefined`, solleva un’eccezione o restituisce righe che, unite, non danno quelle del listato viene scavalcato. L’impaginazione legge il registro quando compone un listato: registra prima di comporre e, in un web worker (la Sandbox impagina in uno), registra dentro il worker.
### Codice in linea
`codeStyle.inline` compone il testo tra apici inversi in un carattere da codice: come un’unica unità, al modo di un chip, dentro la quale una riga non va mai a capo. Se non è impostato, il codice in linea mantiene il carattere del testo.
| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `fontFamily` | `string` | `codeStyle.fontFamily` | Il carattere. |
| `fontSize` | `Dimension` | `0.9em` | `em` è il corpo del testo attorno. |
| `color` | `ColorValue` | quello del testo | |
| `bold` / `italic` | `boolean` | `false` | In aggiunta alle marcature proprie del testo (il codice dentro un grassetto è in grassetto). |
| `background` | `ColorValue` | nessuno | Un riempimento dietro il tratto. |
| `borderColor` / `borderWidth` | `ColorValue` / `Dimension` | nessuno / `0.5pt` | Un contorno. |
| `borderRadius` | `Dimension` | `0.2em` | `em` è il corpo del tratto. |
| `paddingX` / `paddingY` | `Dimension` | `0.2em` con un riempimento o un contorno, altrimenti `0` / `0.1em` | Spazio dentro il riempimento; il padding verticale si dipinge fuori dal riquadro della riga. |
### Come si compone un listato
- **Una riga per ogni riga del sorgente.** Le righe si costruiscono con gli avanzamenti propri del carattere da codice, non con l’algoritmo di divisione dei paragrafi: gli spazi mantengono la loro larghezza, una serie di spazi viene conservata, gli spazi iniziali fanno da rientro. Un listato in un libro da destra a sinistra si legge da sinistra a destra, con le righe composte dal lato opposto del riquadro come una citazione da sinistra a destra, e i numeri nella colonna alla loro sinistra. In un libro verticale un listato segue il flusso verticale (con il latino ruotato su un fianco, come lo compone il testo verticale) e non prende numeri di riga.
- **Divisione.** Un listato più alto dello spazio rimasto si divide tra le righe attraverso colonne e pagine, ogni parte incorniciata come un riquadro a sé, senza mai lasciare meno di `splitMinLines` righe su un lato; il resto di una riga andata a capo resta con essa quando c’è un altro taglio possibile.
- **Output.** Il canvas, il visualizzatore HTML e il PDF dipingono le righe e il riquadro così come sono impaginati. Il visualizzatore HTML mantiene gli spazi (`white-space: pre`), così una selezione copia il listato con il suo rientro e un a capo dopo ogni riga del sorgente, senza numeri né segni di ritorno a capo. Un PDF marcato compone ogni listato come un paragrafo che contiene un elemento `Code`, con veri glifi di spazio, e i numeri e i segni di ritorno a capo come artefatti. L’EPUB a layout fluido scrive `` con i colori dei token e un foglio di stile ricavato da `codeStyle`; l’EPUB a layout fisso è la versione di stampa.
- **Font.** La Sandbox e `configFontFamilies` caricano il carattere del codice quando il testo contiene una recinzione (o la configurazione ha una sezione `codeStyle`), nei pesi normale e grassetto, in tondo e in corsivo; il PDF incorpora i caratteri usati dalle righe.
## Stili dei riquadri
La proprietà `calloutStyles` dichiara gli stili di riquadro con nome che un documento applica con un contenitore `:::callout{type="…"}`: note, suggerimenti, avvertenze, obiettivi di apprendimento, qualsiasi contenuto separato dal testo corrente in un riquadro colorato o bordato. Per impostazione predefinita è incluso uno stile neutro, `note` (sfondo grigio chiaro, nessun bordo, nessuna fascia, nessuna icona, nessun titolo), così `:::callout` funziona senza alcuna configurazione; dichiarare `calloutStyles` sostituisce questo elenco predefinito.
```ts
const config: PostextConfig = {
calloutStyles: [
{ id: 'note', name: 'Note' },
{
id: 'objectives',
name: 'Learning objectives',
title: 'Objectives',
stripe: { enabled: true, side: 'left' },
icon: { kind: 'glyph', glyph: '✓' },
titleStyle: { textTransform: 'uppercase' },
lists: { bulletChar: '–' },
},
{
id: 'warning',
title: 'Warning',
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"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::
```
| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `id` | `string` | — | Identificatore selezionato da `:::callout{type="…"}`. Un recinto con un `type` sconosciuto o assente usa il primo stile configurato (la Sandbox segnala i tipi sconosciuti). |
| `name` | `string` | `id` | Nome leggibile (solo nell’interfaccia dell’editor). |
| `title` | `string` | `''` | Testo predefinito del titolo; vuoto significa nessun titolo. L’attributo `title` del recinto lo sostituisce caso per caso. |
| `span` | `'column' \| 'page' \| 'side'` | `'column'` | Estensione orizzontale: la colonna, l’intera larghezza del contenuto, o la colonna laterale riservata agli elementi flottanti di un’impaginazione a colonna e mezza (`layout.sideColumnRole: 'floats'`); in quest’ultimo caso il riquadro esce dal flusso e si impila in quella colonna accanto al testo che interrompe. Si può sostituire caso per caso con l’attributo `span`. Nelle impaginazioni a più colonne un riquadro `'page'` diventa un *blocco a tutta larghezza*: divide la pagina in fasce di colonne e sta in una propria colonna a tutta larghezza (vedi più avanti la sezione sul contenitore). Un riquadro laterale che la colonna laterale della sua pagina non può contenere prende la colonna laterale della pagina successiva; dove il capitolo (o il documento) finisce prima, ogni riquadro ancora in attesa si compone nella colonna laterale di una pagina dopo il testo, nell’ordine dei suoi recinti, e la build lo segnala (`afterText`; fino a postext 1.24 i riquadri dopo la prima pagina del genere venivano scartati). |
| `columns` | `number` | `1` | Quante colonne adiacenti occupa un riquadro flottante (`placement` `'auto'`, `'top'` o `'bottom'`, con `span: 'column'`), come fa `placement.columns` per una figura: il riquadro di un articolo su tre delle cinque colonne di un giornale. Tante colonne quante ne ha la pagina, o di più, ne fanno un riquadro a tutta larghezza. Un riquadro composto nel flusso (`'here'`) resta nella sua colonna. Si può sostituire caso per caso con l’attributo `columns`. Da postext 1.18. |
| `placement` | `'here' \| 'auto' \| 'top' \| 'bottom' \| 'fixed'` | `'here'` | Dove va il riquadro. `'here'` lo compone in linea nel flusso; `'top'` / `'bottom'` lo **fanno flottare** come una risorsa (`'auto'` prende la prima fascia libera, di testa o di piede): esce dal flusso nel punto in cui compare e prende la prima fascia libera in quel punto o dopo (il piede della pagina corrente, o la testa / il piede della pagina successiva che il flusso apre), e il testo che lo segue riempie la pagina attorno a esso; `'fixed'` lo ancora a coordinate della pagina tramite `fixed` qui sotto, fuori dal flusso delle colonne. Vedi la sezione sul contenitore per i dettagli. Si può sostituire caso per caso con l’attributo `placement`. |
| `sideAtColumnEnd` | `'before' \| 'after'` | `'before'` | Dove sta un riquadro laterale (`span: 'side'`) quando il testo dopo il suo recinto non prosegue nella stessa colonna: la colonna non ha più spazio per esso, oppure le regole di interruzione lo mandano avanti (un paragrafo che le regole su vedove e orfane spostano intero, un titolo tenuto con il suo testo). `'before'` lo tiene al suo recinto, in quella pagina, accanto al testo che lo precede, risalendo dal piede della colonna quando non ci sta sotto il recinto: il posto per una glossa scritta dopo il passo che spiega. `'after'` lo allinea alla prima riga del testo dopo il recinto, nella colonna laterale della pagina in cui quel testo prosegue: il posto per un numero di riga o un titolo marginale scritto prima della sua riga. Quando il testo prosegue nella stessa colonna, entrambi compongono il riquadro al suo recinto. Un riquadro che nel suo capitolo non è seguito da nulla resta comunque con il testo che lo precede, e i riquadri laterali con recinti consecutivi mantengono il loro ordine. Fino a postext 1.4 ogni riquadro laterale si comportava come `'before'`, che resta il valore predefinito: uno stile per le glosse tiene i suoi riquadri nella pagina del passo che spiegano. |
| `fixed` | `{ anchor?, offset? }` | `{ anchor: { to: 'container', edge: 'bottom-left' } }` | Posizione di un riquadro `'fixed'`: un `ElementAnchor` (`to`: `'container'` = l’area del contenuto della pagina, specchiata sulle pagine pari; `'page'` = il formato rifilato; `'bleed'` = l’area con l’abbondanza; `edge`: uno dei nove bordi del contenitore) più un `offset` facoltativo (dimensioni `x` / `y`). |
| `floatBarrier` | `boolean` | `false` | Fa del riquadro una barriera per gli elementi flottanti: ogni figura o tabella richiamata prima di esso viene collocata prima di esso (negli spazi liberi della pagina, altrimenti in pagine aperte prima del riquadro), così nessun elemento flottante scavalca il riquadro di chiusura di un capitolo (tipicamente un riepilogo dei «punti chiave»). Le aperture di capitolo, `:::part` e la fine del documento sono sempre barriere. |
| Un riquadro `span: 'page'` su una pagina a più colonne taglia la fascia sotto il testo che segue; una figura a tutta larghezza richiamata prima di esso prende per prima quel taglio: il testo viene livellato, la figura si colloca proprio dove esso è finito, e il riquadro prosegue sotto di essa (o alla pagina successiva quando non ci sta più). Una figura troppo alta per seguire il testo livellato apre invece la pagina successiva, con il riquadro dopo di essa, e la fascia che ha lasciato termina comunque livellata. Un riquadro divisibile (`keepTogether: false`) si apre sotto il testo e la figura con tutti gli elementi che ci stanno, e il resto prosegue nella pagina successiva. | | | |
| `width` | `'fill' \| 'auto'` | `'fill'` | `'fill'` occupa la larghezza disponibile; `'auto'` si adatta al titolo (uso come etichetta) e ignora i figli. |
| `backgroundEnabled` / `background` | `boolean` / `ColorValue` | `true` / `#f4f4f4` | Riempimento del riquadro. |
| `border` | `{ enabled, color, width }` | `false`, `#cccccc`, `0.5pt` | Contorno del riquadro, tracciato all’interno del bordo del riquadro come il bordo di un elemento riquadro (vedi [Elementi riquadro](https://postext.dev/it/docs/configuration-page-layout.md#elementi-riquadro)). |
| `borderRadius` | `Dimension` | `0` | Raggio degli angoli dello sfondo / del bordo (limitato a metà della larghezza e dell’altezza del riquadro). La fascia lo segue: su un riquadro arrotondato la fascia è ritagliata dalla cornice arrotondata, come CSS ritaglia un `border-left` con `border-radius`. La linguetta `label` mantiene gli angoli vivi. |
| `padding` | `{ top, right, bottom, left }` | `0.75em` ciascuno | Distanza tra il bordo del riquadro e il suo contenuto. I valori in `em` sono relativi al corpo del testo del riquadro. |
| `stripe` | `{ enabled, side, width, color }` | `false`, `'left'`, `1.5em`, colore principale | Fascia piena lungo un bordo. Una fascia `'left'` / `'right'` restringe il contenuto; una fascia `'top'` lo spinge in basso. `'left'` e `'right'` sono lati del flusso del testo (in un libro da destra a sinistra `'left'` è la destra del foglio); `'start'` e `'end'` seguono la direzione propria del riquadro, quindi un `:::callout{dir=ltr}` in un libro arabo mette a sinistra una fascia `'start'`. Su un riquadro con `borderRadius` i suoi angoli esterni si arrotondano come quelli della cornice (fino a postext 1.4 restavano vivi e sporgevano oltre l’arrotondamento). |
| `icon` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, width, color, align, position, cornerSide }` | `'none'`, font dei titoli, `400`, `1.5em`, colore principale, `'top'`, `'inline'`, `'right'` | Un glifo di testo (`kind: 'glyph'`) o una risorsa bitmap / SVG (`kind: 'resource'` + `resourceId`) accanto al contenuto. Con una fascia laterale l’icona si centra sulla fascia; altrimenti riserva una propria colonna (`size` + `titleStyle.gap`). `align: 'center'` la centra verticalmente sul contenuto. Un’immagine di risorsa si adatta al quadrato mantenendo le proporzioni, oppure a un riquadro `width` × `size` quando è impostato `width` (una larga striscia di icone); un’icona più alta del contenuto fa crescere il riquadro per contenerla (e, con `align: 'center'`, centra il contenuto su di essa). `position: 'corner'` appende l’icona a un angolo superiore come un’etichetta, per metà oltre il bordo, senza togliere spazio al contenuto; un’icona larga (`width`) si centra sull’angolo in base alla larghezza a cui è disegnata, e sull’angolo sinistro il titolo inizia oltre la sua metà interna (fino a postext 1.4 si collocava in base all’altezza, quindi una striscia larga sporgeva dal riquadro e sopra il titolo); `cornerSide` sceglie l’angolo: `'right'` / `'left'`, oppure `'outer'` / `'inner'`, che seguono la parità della pagina dei margini speculari (esterno = destra su un recto, sinistra su un verso). |
| `marker` | `{ kind, glyph, resourceId, fontFamily, fontWeight, size, color, align, gap, rule }` | `'none'`, font dei titoli, `400`, `1.5em`, colore principale, `'center'`, `0.5em`, filetto disattivato (`0.5pt`, colore principale, lunghezza `0`) | Una seconda icona disegnata *fuori* dal riquadro, in una colonna alla sua sinistra, con un `rule` verticale facoltativo tra essa e il riquadro: la mano «tocca qui» accanto a un’etichetta di autovalutazione. La cornice diventa `[marker][rule][gap][box]` e alta quanto il più alto dei tre; `align` li centra l’uno sull’altro o li allinea in alto. `rule.length` è un minimo: il filetto copre sempre almeno l’altezza del riquadro. |
| `titleStyle` | `{ fontFamily, fontSize, fontWeight, italic, color, textTransform, gap, letterSpacing, indent, lineHeight }` | font dei titoli, corpo del testo corrente, `700`, `false`, colore principale, `'none'`, `0.5em`, `0`, `0`, `1.2em` | Tipografia del titolo. `gap` è lo spazio tra il titolo e il primo figlio (e lo spazio della colonna dell’icona). `lineHeight` è l’interlinea delle righe del titolo, con `em` riferito alla dimensione propria del titolo; la linea di base sta a 0,8 di essa dall’alto di ogni riga, come nel testo corrente, quindi un titolo sull’interlinea del testo corrente (`lineHeight: 12pt` su una griglia di 12 pt) mantiene un riquadro di un numero intero di righe e il suo titolo sulla griglia, mentre l’1,2 em predefinito aggiunge una frazione di riga a ogni riquadro. `textTransform: 'uppercase'` conserva la lunghezza. `letterSpacing` applica la spaziatura tra lettere al titolo (`letterSpacing` del canvas / `Tc` del PDF); `indent` lo sposta a destra del bordo interno del riquadro. Un’etichetta d’angolo appesa sul lato del titolo (l’angolo sinistro) riserva prima il proprio spazio (la metà interna dell’etichetta più `gap`), così il titolo la evita su qualunque pagina capiti; `indent` aggiunge soltanto oltre quello. |
| `body` | `{ fontFamily, fontSize, lineHeight, color, boldColor, italicColor, fontWeight, boldFontWeight, italic, smallCaps, textAlign, hyphenation, paragraphSpacing, firstLineIndent, tabStops, tabInterval }` | eredita da `bodyText`; `italic` / `smallCaps` `false` | Tipografia dei paragrafi e degli elementi di elenco dentro il riquadro. Ogni campo non impostato eredita dal testo corrente; `italicColor` imposta il colore dei tratti in corsivo (una citazione in evidenza in corsivo nel colore del riquadro). `fontWeight` / `boldFontWeight` impostano i pesi dei tratti normali e in grassetto; `italic` compone il riquadro in corsivo, con i tratti `*…*` che passano in tondo; `smallCaps` lo compone in maiuscoletto; `tabStops` e `tabInterval` sostituiscono quelli del testo corrente dentro il riquadro (vedi [Stop di tabulazione](https://postext.dev/it/docs/configuration-text.md#punti-di-tabulazione)). Vedi [Tipografia dentro un riquadro](https://postext.dev/it/docs/configuration-styles.md#tipografia-dentro-un-riquadro) per che cos’altro prende il testo del riquadro. |
| `lists` | `{ bulletChar, color, indent, gap, itemSpacing, bulletFontSize, bulletFontWeight }` | eredita da `unorderedLists` | Tipografia degli elenchi dentro il riquadro (`color`, `indent`, `gap` e `itemSpacing` si applicano anche agli elenchi ordinati). `bulletFontSize` / `bulletFontWeight` compongono il glifo del punto elenco nel carattere del testo del riquadro con quella dimensione e quel peso (un punto elenco pesante e colorato). |
| `label` | `{ fontFamily, fontSize, fontWeight, color, background, position, height, paddingX, offset, inset, icon, rule }` | non impostato (nessuna linguetta) | Una linguetta sul bordo superiore del riquadro che stampa l’attributo `label` del recinto: il numero di un riquadro numerato («BOX 1-1»). Aderisce all’angolo `position` (`'top-right'` / `'top-left'`), rientrata di `inset`, sporge di `offset` sopra la sommità del riquadro (quello spazio fa parte del blocco, in aggiunta a `marginTop`, così la linguetta lo conserva anche in testa a una colonna), è alta `height` con `paddingX` su ogni lato del testo, e può portare accanto una risorsa `icon` (`{ resourceId, width, gap }`, sul lato opposto all’angolo) e un `rule` (`{ enabled, color, width }`) lungo il bordo superiore dall’angolo opposto fino a essa. Valori predefiniti: font dei titoli, corpo del testo corrente, `700`, bianco sul colore principale, alta `1.4em`, spaziatura interna `0.6em`. La linguetta è una forma a sé appoggiata sulla cornice, quindi mantiene gli angoli vivi qualunque sia il `borderRadius` del riquadro. |
| `columnGap` | `Dimension` | `1.5em` | Spazio tra le colonne di un gruppo `:::columns` dentro il riquadro (vedi più avanti la sezione sul contenitore). |
| `marginTop` / `marginBottom` | `Dimension` | `0.75em` / `0.75em` | Spazio sopra il riquadro (si fonde con il margine del blocco precedente) e spazio minimo sotto di esso (lo spazio esatto con `snapToGrid: false`). Un riquadro flottante (`placement: 'top'`, `'bottom'` o `'auto'`) mantiene lo spazio degli elementi flottanti, una riga di testo, tra la sua fascia e il testo; un `marginBottom` più ampio imposta lo spazio sotto un riquadro in una fascia di testa, e un `marginTop` più ampio lo spazio sopra un riquadro in una fascia di piede, arrotondato alla griglia insieme alla fascia. Fino a postext 1.4 un riquadro flottante ignorava i suoi margini. |
| `snapToGrid` | `boolean` | `true` | Con `true` il flusso dopo il riquadro torna ad agganciarsi alla griglia della linea di base, quindi lo spazio sotto di esso è `marginBottom` arrotondato a righe intere della griglia. Con `false` il riquadro mantiene il suo `marginBottom` esatto, che si fonde con il margine superiore del blocco successivo (due riquadri consecutivi di uno stile del genere stanno esattamente a `max(marginBottom, marginTop)` di distanza), e il testo che lo segue può stare fuori griglia fino al punto di aggancio successivo (un titolo, la fine di un elenco), come dopo un titolo con `headings.snapToGrid: false`. Pensato per documenti fatti di riquadri impilati (schede di esercizi, moduli). Si applica ai riquadri nel flusso; i riquadri a tutta larghezza in un’impaginazione a più colonne, i riquadri flottanti, fissi e laterali mantengono la griglia, perché le fasce di colonne e le zone degli elementi flottanti sono impaginate su di essa. Le leve del bilanciamento delle colonne non cambiano: un riquadro che chiude una colonna viene comunque spinto fino all’ultimo slot della griglia della colonna. |
| `keepTogether` | `boolean` | `true` | Con `true` il riquadro resta intero: un riquadro che non sta nello spazio rimanente passa intero alla colonna o alla pagina successiva. Solo un riquadro più alto di una colonna vuota e completa (un’intera pagina per un riquadro `span: 'page'`) non può restare intero: si divide secondo le regole di `false` descritte sotto invece di eccedere, a partire dal punto in cui compare, e una continuazione che sta in una colonna passa poi avanti intera; un riquadro flottante (`placement: 'top' \| 'bottom' \| 'auto'`) così alto non flotta ma resta nel flusso dove compare. Con `false` qualsiasi riquadro può dividersi tra i suoi blocchi figli o tra le righe di un paragrafo o di un elemento di elenco: il taglio più profondo che ci sta chiude la colonna corrente (o, per un riquadro `span: 'page'`, la pagina, a filo del fondo delle colonne) e il resto prosegue in cima alla successiva in un riquadro proprio (stessa cornice e stessa fascia, nessuna icona, e nessun titolo a meno che `repeatTitle` non lo ripeta), dividendosi di nuovo se è ancora troppo alto. Il testo di ogni frammento conserva, vuota, la colonna che un’icona in linea occupa nella parte iniziale, così il riquadro ha una sola giustezza su ogni pagina. Un taglio dentro un elemento di elenco lascia il suo punto elenco con la parte iniziale. La cornice di ogni frammento condivide `contentIndex` / `containerId` del recinto e registra `callout.part` / `callout.continued`. Usalo su un lungo riquadro di chiusura con i «punti chiave» insieme a `headings.balancing.beforeSpan`, o su uno stile di nota i cui riquadri non devono mai spingere una figura fuori dalla pagina. Un riquadro annidato (un `:::callout` dentro un altro) è un figlio del suo genitore: un taglio può cadere prima o dopo di esso, e al suo interno solo quando il suo stile consente la divisione (`keepTogether: false`, o più alto di una colonna intera), secondo il suo `splitMinLines`. |
| `splitMinLines` | `number` | `2` | Numero minimo di righe di testo che un frammento di un riquadro diviso (`keepTogether: false`, o un riquadro da tenere unito più alto di una colonna intera) conserva su ciascun lato del taglio. Protegge solo il testo: un lato che contiene almeno una figura, una tabella, una formula in evidenza o un riquadro annidato è accettabile qualunque sia il suo numero di righe, quindi un riquadro di immagini può lasciarne una sola su una pagina. Un taglio dentro un paragrafo o un elemento di elenco conta comunque tutte le righe di ciascun lato (una figura o una formula lì come una riga), e lascia anche almeno `layout.boxChildSplitMinLines` righe di quel paragrafo o elemento su ciascun lato (due per impostazione predefinita; questo minimo quando è inferiore, quindi 1 consente una riga). Con i valori predefiniti un elemento di due o tre righe non si divide mai e uno di quattro si divide solo due e due. Con il valore predefinito nessun riquadro si divide lasciando una riga di testo isolata al piede di una colonna o in testa alla successiva; quando nessun taglio soddisfa il minimo il riquadro passa avanti intero. (Prima di postext 1.5 un taglio dentro un paragrafo controllava solo le righe dell’intero lato, quindi un elemento di due righe poteva dividersi una e una quando altre righe del riquadro raggiungevano il minimo.) |
| `repeatTitle` | `boolean` | `false` | Ripete il titolo in testa a ogni continuazione di un riquadro diviso, seguito da `continuedSuffix` («Punti chiave (segue)»). La ripetizione prende lo stile del titolo. Un riquadro senza titolo non ripete nulla. Vedi [Segni su un riquadro diviso](https://postext.dev/it/docs/configuration-styles.md#segni-su-un-riquadro-diviso). |
| `continuedSuffix` | `string` | `'(cont.)'` | Testo dopo il titolo ripetuto, nella lingua del documento (`locale`, altrimenti la lingua di sillabazione), come quello di una tabella divisa, e unito al titolo come lo è quello di una tabella. |
| `continuesMarkerEnabled` | `boolean` | `false` | Colloca `continuesMarker` sotto l’ultima riga di ogni parte di un riquadro diviso che prosegue, all’interno del riquadro. |
| `continuesMarker` | `string` | `'Continued'` / `'Continúa'` | Testo di quel segno (il «(MORE)» di una sceneggiatura), nel carattere e nel corpo del testo del riquadro, secondo la lingua del documento. |
| `continuesMarkerAlign` | `'left' \| 'center' \| 'right'` | `'right'` | Dove sta il segno nella larghezza interna del riquadro. |
| `continuesMarkerItalic` | `boolean` | `true` | Compone il segno in corsivo. |
| `numbering` | `{ label, counter, numberingTemplate, resetOn, counterFormat, placement, bold, italic, suffix }` | non impostato | Conta i riquadri di questo stile come enunciati numerati: teoremi, lemmi, definizioni. Vedi [Enunciati numerati e dimostrazioni](https://postext.dev/it/docs/configuration-styles.md#enunciati-numerati-e-dimostrazioni). |
| `endMark` | `string` | `''` | Un segno allineato a destra alla fine dell’ultima riga del riquadro, come una dimostrazione termina con `'∎'` o `'□'`: sull’ultima riga quando ci sta dopo uno spazio, altrimenti su una riga propria. Un riquadro che termina con una formula in evidenza senza numero lo prende come etichetta della formula. Con le formule attive, i quadrati (∎ □ ■ ▪ ◻ ▫) si disegnano dai glifi propri di TeX, quindi un carattere che non li ha (i file latini di Fontsource) li stampa comunque; con le formule disattivate si compongono nel carattere del testo del riquadro. |
### Il contenitore `:::callout`
Una riga `:::callout{type=""}` apre il riquadro e una riga `:::` da sola lo chiude. Il recinto accetta cinque attributi, `type` (l’id dello stile), `title` (sostituisce il titolo dello stile), `span`, `placement` e `columns` (sostituiscono i valori dello stile), e il contenuto tra le due righe si impagina dentro il riquadro: un titolo facoltativo, poi i paragrafi, gli elenchi, le citazioni in blocco, le formule o le risorse incorporate, ciascuno composto con la tipografia `body` / `lists` dello stile (i titoli mantengono i loro stili consueti). I margini tra i figli si fondono come nel testo corrente; l’interno esce dalla griglia della linea di base, e il flusso vi si riaggancia dopo il riquadro con almeno `marginBottom` sotto (vince la griglia; il margine è un minimo, la stessa convenzione seguita dalle risorse). Uno stile con `snapToGrid: false` mantiene invece il `marginBottom` esatto, e il testo dopo il riquadro resta fuori griglia fino al titolo successivo o alla fine di un elenco. Un titolo subito prima di un riquadro resta unito a esso.
Limiti di questa versione:
- Un riquadro resta intero a meno che il suo stile non imposti `keepTogether: false`. Quando non sta nello spazio rimanente della colonna passa intero alla colonna o alla pagina successiva, anche uscendo da una colonna vuota che fasce di elementi flottanti o un limite di fascia hanno accorciato, purché una colonna intera possa contenerlo. Un riquadro più alto di una colonna intera si divide invece, come uno divisibile; solo uno che nessun taglio può dividere (una figura o una tabella più alta della colonna, o uno `splitMinLines` che nessun taglio soddisfa) viene collocato comunque ed eccede; l’impaginazione registra allora un avviso `calloutOverflow` (`VDTDocument.warnings`), che la Sandbox elenca. Un gruppo `:::columns` si taglia come il riquadro che lo contiene, tra le sue sottocolonne (da postext 1.25); resta intero, e può eccedere allo stesso modo, solo con `layout.flowColumns: false` o dentro un riquadro annidato. Un riquadro divisibile lascia indietro la parte che ci sta (figli interi, o le righe di un paragrafo fino a `splitMinLines` su ciascun lato; una figura, una tabella o una formula in evidenza da sola basta per un lato) e prosegue in un riquadro senza icona nella colonna o pagina successiva, senza il titolo a meno che lo stile non lo ripeta, e facoltativamente con un segno sotto la parte che lascia (vedi [Segni su un riquadro diviso](https://postext.dev/it/docs/configuration-styles.md#segni-su-un-riquadro-diviso)).
- Gli elementi flottanti cedono il passo a un riquadro indivisibile. Quando il blocco subito dopo il richiamo di una figura è un riquadro `keepTogether`, uno slot che non lascerebbe al riquadro alcuna colonna della fascia corrente in cui finire (la colonna del richiamo o una vuota dopo di essa, che lo conteneva prima dell’elemento flottante) non viene preso: la figura passa al suo slot successivo, di solito la pagina successiva, e il riquadro resta nel flusso, come lo comporrebbe un compositore, invece di spingere il riquadro fuori dalla pagina lasciando la colonna con la sola figura.
- `span: 'page'` in un’impaginazione a più colonne fa del riquadro un **blocco a tutta larghezza**: si impagina all’intera larghezza del contenuto e divide la pagina in fasce di colonne; le colonne di testo sopra di esso si chiudono alla linea di taglio, il riquadro prende una propria colonna a tutta larghezza, e sotto di esso si apre una nuova fascia di colonne di testo, così il flusso prosegue sotto il riquadro in ogni colonna. Dove le colonne sono *livellate* (in cima a una pagina, subito sotto un titolo di apertura `span: 'page'`, subito sotto un altro blocco a tutta larghezza, o subito sotto una fascia di elementi flottanti in testa) il riquadro taglia semplicemente lì. Quando arriva a metà pagina, con le colonne disuguali, si compone come farebbe un compositore: il testo sopra di esso viene tagliato alla stessa altezza in tutte le colonne (il motore ripete il posizionamento con le colonne della fascia accorciate allo stesso numero di righe della griglia, così il testo trabocca naturalmente da una colonna all’altra e tutte le regole su orfane, vedove e tieni con il successivo continuano ad applicarsi), il riquadro occupa tutta la larghezza della pagina, e le colonne riprendono sotto di esso. Il taglio richiede un paio di passaggi di posizionamento in più; quando la linea di taglio non lascerebbe spazio per il riquadro più il minimo di righe di testo per le vedove sotto di esso, o nessuna disposizione funziona dopo alcuni tentativi, il riquadro passa in cima alla pagina successiva. Il testo sopra rispetta il taglio: un paragrafo che non può iniziare nelle poche righe che una colonna sotto una figura conserva sopra di esso passa alla colonna successiva (la figura resta allora sola nella sua colonna), e quando un blocco supererebbe comunque il taglio, il taglio si prende una riga più in basso invece che dove termina quel blocco. Anche un riquadro diviso che apre la fascia viene tagliato lì, così il suo resto non supera mai il taglio. Con `headings.balancing.beforeSpan` (il valore predefinito) la fascia che lascia viene tagliata livellata dietro di esso, come la fascia di chiusura di un capitolo, e, quando lo stile consente la divisione (`keepTogether: false`), la parte del riquadro che sta sotto le colonne livellate chiude la pagina e il resto apre la successiva; con `beforeSpan: false` la pagina che lascia viene semplicemente bilanciata come al solito, senza forzare un’interruzione di pagina. Un titolo subito prima di un blocco a tutta larghezza non viaggia con esso. Nelle impaginazioni a una colonna `span: 'page'` è semplicemente in linea.
- `placement: 'fixed'` toglie il riquadro dal flusso: viene impaginato (`width: 'auto'` si adatta al titolo; `'fill'` prende la larghezza della colonna di testo sotto il punto di ancoraggio) e fissato alla pagina in cui compare nel flusso, nella posizione descritta da `fixed.anchor` / `fixed.offset` (per impostazione predefinita l’angolo inferiore sinistro dell’area del contenuto). Le colonne di testo che copre cedono quella zona (tagliate dal basso, o dall’alto quando la colonna è ancora vuota), esattamente come una fascia di elementi flottanti; quando la zona contiene già testo, un elemento flottante o un blocco a tutta larghezza, il riquadro passa alla pagina successiva. Un riquadro fisso che chiude il capitolo (il blocco successivo è un’apertura di capitolo, un `:::part`, un riquadro barriera o la fine del documento) livella prima le colonne sopra di esso (`headings.balancing.trailing`), così una breve pagina di chiusura termina livellata con l’etichetta sottostante. La cornice e i figli vivono in `page.floats` e si disegnano fuori dal ritaglio delle colonne in ogni backend.
- `placement: 'top' | 'bottom'` **fa flottare** il riquadro come una risorsa: esce dal flusso nel punto in cui compare e prende la prima fascia libera dopo quel punto (il piede della pagina corrente, con `'bottom'`, o la testa / il piede della pagina successiva che il flusso apre) alla larghezza della colonna (`span: 'column'`) o all’intera larghezza del contenuto (`span: 'page'`); il testo che lo segue riempie la pagina che ha lasciato. La sua cornice e i suoi figli vanno in `page.floats`, come per un riquadro fisso. Un riquadro flottante in testa a una pagina nuova si colloca prima delle figure in attesa di quella pagina, e una figura citata in una pagina precedente che ci sta poi sotto di esso prende il resto di quella pagina anche quando resterebbero meno di tre righe di testo (una pagina da galleria: riquadro più figura, senza testo in mezzo). Un riquadro `span: 'side'` non flotta mai: si impila accanto al testo qualunque sia il suo posizionamento. Con `columns` superiore a 1 (nello stile o come attributo del recinto, da postext 1.18) un riquadro `span: 'column'` occupa altrettante colonne adiacenti: la testa di una serie di colonne vuote che iniziano alla stessa altezza, o il piede della colonna corrente e di quelle vuote che la seguono, come in `:::callout{placement="top" columns="2"}`.
- `width: 'auto'` si adatta solo al titolo; i figli vengono ignorati.
- Un `:::callout` annidato dentro un altro riquadro è un riquadro a sé: si impagina con il proprio stile (sfondo, bordo, raggio, spaziatura interna, fascia, titolo, icona, segno, linguetta, tipografia) all’intera larghezza interna del genitore e si impila come uno dei suoi figli, con `marginTop` / `marginBottom` che si fondono con quelli dei vicini. I suoi `span` e `placement` (del recinto o dello stile) vengono ignorati, perché un riquadro annidato scorre sempre dentro il genitore, e così `floatBarrier` e `snapToGrid`. I riquadri si annidano a qualsiasi profondità e possono stare dentro un gruppo `:::columns` (ciascuno intero, in una colonna). Quando il genitore si divide, il taglio cade prima o dopo un riquadro annidato, o al suo interno quando lo stile annidato consente la divisione; ogni frammento ridisegna le cornici che attraversa, e un riquadro annidato che continua dal frammento precedente perde il titolo e l’icona, come una continuazione di primo livello.
- Un gruppo `:::columns{count=N}` … `:::` tra i figli impagina quei figli in `N` colonne di uguale larghezza, a distanza `columnGap`, dentro il riquadro: la sequenza si taglia ai confini di blocco o di riga che livellano meglio le colonne (un paragrafo o un elemento di elenco tagliato a metà prosegue in testa alla colonna successiva senza il suo punto elenco), ogni colonna inizia alla sommità del gruppo e il gruppo è alto quanto la sua colonna più alta; i figli successivi tornano all’intera larghezza. Un riquadro che si divide (`keepTogether: false`, o più alto di una colonna) taglia anche dentro un gruppo, tra le sue colonne: un gruppo a serpentina riempie a turno le sue colonne e prosegue nel frammento successivo, uno parallelo (`breaks`) prosegue flusso per flusso (da postext 1.25; vedi [Formato del documento › `:::columns`](https://postext.dev/it/docs/document-format.md#columns)). Un `gap` sul recinto sostituisce `columnGap` per quel gruppo, e `rule` traccia un filetto lungo ogni intercolonna. Usalo per un riepilogo dei punti chiave su due colonne, o per affiancare le tabelle di un riquadro largo.
- Il sesto attributo del recinto, `label`, si stampa sulla linguetta dello stile (vedi `label` sopra): `:::callout{type="box" label="BOX 1-1" title="The octet rule"}`; senza uno stile `label` l’attributo viene ignorato.
Nel VDT il riquadro è un blocco cornice `type: 'callout'` la cui decorazione (sfondo, fascia, icona, titolo) vive in `designOverlay`, seguito dai suoi blocchi figli nella stessa colonna; la cornice e ogni figlio portano il `containerId` del recinto. Un riquadro annidato è una cornice `type: 'callout'` a sé tra i figli, seguita dai suoi blocchi; questi mantengono il `containerId` del recinto di primo livello (il posizionamento e il bilanciamento continuano a vedere un’unica unità) e aggiungono `calloutPath`, gli id dei contenitori dei recinti annidati che li circondano, dal più esterno (l’id proprio di una cornice annidata è l’ultima voce). Il PDF con tag dà a ogni riquadro annidato un `Div` dentro quello del genitore. Le immagini delle icone si risolvono come le immagini delle risorse: il registro delle immagini del canvas, l’opzione HTML `resourceImageUrl` e il provider PDF `resourceBytes`.
```ts
const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
// locale picks the language of the continuation strings
const minimal = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped
```
### Enunciati numerati e dimostrazioni
Uno stile con `numbering` conta i suoi riquadri, come `amsthm` di LaTeX conta gli ambienti teorema (da postext 1.19). Ogni riquadro stampa la sua etichetta e il suo numero («**Theorem 2.**» in apertura del suo primo paragrafo) e il `title` del recinto segue il numero tra parentesi: `:::callout{type="theorem" title="Bradley–Terry"}` si apre con «**Theorem 2** (Bradley–Terry)**.**». Un riquadro aperto con un identificatore (`{#thm:main}`) è una destinazione dei rimandi, che stampano «Theorem 2» (`:ref{id="thm:main"}`), e `\ref{thm:main}` o `style=number` stampa 2.
| Campo | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `label` | `string` | — | La parola prima del numero: `'Theorem'`, `'Lemma'`, `'Definición'`. |
| `counter` | `string \| false` | l’`id` dello stile | Il contatore che i riquadri fanno avanzare. Gli stili che indicano uno stesso contatore lo condividono, come fa `\newtheorem{lemma}[theorem]`: Theorem 1, Lemma 2, Theorem 3. `'equation'` conta insieme alle equazioni etichettate. `false` stampa l’etichetta senza numero (il «*Proof.*» di una dimostrazione). |
| `numberingTemplate` / `resetOn` / `counterFormat` | `string` / `ResourceCounterReset` / `ResourceCounterFormat` | `'{n}'` / `'never'` / `'decimal'` | Come quello di un tipo di risorsa: `'{h1}.{n}'` con `resetOn: 'h1'` numera Theorem 2.1, 2.2… per capitolo; `'{h1}.{h2}.{n}'` con `'h2'` per sezione. Un contatore condiviso da più stili conta su ciò che stampano i loro modelli. Un token prende uno stile dopo i due punti, come quello di un tipo di risorsa: `'{h1:A}.{n}'` stampa *Theorem A.1* in un’appendice indicata da una lettera. |
| `placement` | `'runIn' \| 'title'` | `'runIn'` | `'runIn'` apre il primo paragrafo del riquadro con l’etichetta (un riquadro che si apre con un elenco, una formula o un altro riquadro riceve un paragrafo apposito); `'title'` fa dell’etichetta il titolo del riquadro, nel suo `titleStyle`: «Theorem 2 (Bradley–Terry)». |
| `bold` / `italic` | `boolean` | `true` / `false` | Il carattere dell’etichetta in linea e del suo suffisso, qualunque sia il testo del riquadro: un testo in corsivo (`body.italic`) mantiene in tondo un’etichetta in tondo. Il titolo tra parentesi si compone in tondo e nel peso normale. |
| `suffix` | `string` | `'.'` | Collocato dopo l’etichetta in linea e il suo titolo. |
Una dimostrazione è uno stile con un’etichetta non numerata e un segno finale:
```ts
calloutStyles: [
{ id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
{ id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
{ id: 'definition', numbering: { label: 'Definition' } },
{ id: 'proof', backgroundEnabled: false, endMark: '□',
numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]
```
In un libro impaginato capitolo per capitolo i contatori proseguono dal capitolo precedente (`LayoutContinuation.statementCounters`, che `continuationAfter` compila), e la struttura del libro assegna all’ancora di ogni riquadro numerato la sua etichetta (`OutlineEntry.numberLabel`), così un rimando da un altro capitolo la stampa.
### Tipografia dentro un riquadro
Un riquadro compone il suo contenuto con la propria tipografia `body` e `lists`; tutto il resto mantiene gli stili del documento:
- **I paragrafi** prendono il `body` del riquadro: carattere, dimensione, interlinea, colore, colori dell’enfasi, pesi, `italic`, `smallCaps`, allineamento, sillabazione, rientro e spaziatura tra paragrafi. Un campo non impostato eredita da `bodyText`. Un colore dell’enfasi ereditato mantiene il suo collegamento alla tavolozza, quindi grassetto, corsivo ed etichette `:ref` in un riquadro cambiano con `colorPalette` come fanno fuori da esso. (Fino a postext 1.4 il grassetto in un riquadro restava `#295AA3` qualunque fosse il colore principale.)
- **Gli elenchi puntati** prendono il `lists` del riquadro (carattere del punto elenco, colore, dimensione e peso del glifo, rientro, spazio, spaziatura tra gli elementi) al posto di `unorderedLists`, e il loro testo è il testo del riquadro. Un `lists.bulletChar` o `lists.color` diverso da quello del documento (`unorderedLists`) sostituisce il punto elenco o il colore di ogni livello; uno che lo ripete, o che resta non impostato, lascia a ogni livello il proprio (`unorderedLists.levels`), così i trattini annidati sopravvivono nel riquadro.
- **Gli elenchi ordinati** prendono `lists.indent`, `gap` e `itemSpacing`, e `lists.color` ogni volta che lo stile lo imposta, anche quando è il colore del punto elenco del documento; uno stile che lo lascia non impostato mantiene i numeri in `orderedLists.color`. (Fino a postext 1.4 il colore arrivava ai numeri solo quando era diverso da `unorderedLists.color`, quindi impostarlo proprio su quel colore non faceva nulla.) Il numero stesso (il suo carattere, la sua dimensione e il suo separatore) viene dall’`orderedLists` globale, perché `lists` ha solo campi per i punti elenco: definisci lì lo stile dei numeri di un riquadro.
- **I `:::paragraphs` dentro un riquadro** usano il loro stile di paragrafo, anche nei riquadri annidati. I campi che lo stile lascia non impostati ereditano dal `bodyText` del documento, non dal `body` del riquadro (né dal suo corsivo o dal suo maiuscoletto).
- **I gruppi `:::columns`** non hanno uno stile proprio: ogni colonna condivide la tipografia del testo e degli elenchi del riquadro, e `columnGap` imposta lo spazio tra di esse.
- **Le citazioni in blocco** prendono il carattere, la dimensione e i pesi del testo del riquadro (corsivo e grigio, come nel testo corrente), e il suo maiuscoletto. **I titoli** mantengono gli stili dei titoli; **le formule in evidenza** le impostazioni delle formule.
- **Le figure e le tabelle** mantengono gli stili delle didascalie e delle tabelle del documento, alla larghezza interna del riquadro; i loro pesi normale e grassetto seguono i pesi del `body` del riquadro.
- **I chip** mantengono il loro stile di chip; una dimensione in `em` si legge rispetto al corpo del testo del riquadro.
- **`:::space`** si misura in righe del testo del riquadro (vedi [`:::space`](https://postext.dev/it/docs/document-format.md#space) per i casi in cui viene scartato).
- **Un riquadro annidato** prende per intero il proprio stile; i suoi `span`, `placement`, `floatBarrier` e `snapToGrid` vengono ignorati.
### Segni su un riquadro diviso
Quando un riquadro si divide tra colonne o pagine (`keepTogether: false`, o un riquadro più alto di una colonna), ogni parte dopo la prima si apre senza il titolo e l’icona, e per impostazione predefinita nulla dice al lettore che il riquadro prosegue. Due opzioni aggiungono i segni che usano un libro o una sceneggiatura:
- **`repeatTitle: true`** ripete il titolo in testa a ogni continuazione, seguito da `continuedSuffix`, per impostazione predefinita «Key points (cont.)». La ripetizione prende lo stile del titolo, quindi con `textTransform: 'uppercase'` dà il «HAMLET (CONT'D)» di una sceneggiatura. L’icona e la linguetta restano sulla prima parte.
- **`continuesMarkerEnabled: true`** colloca `continuesMarker` («Continued», o «Continúa» in un documento spagnolo) sotto l’ultima riga di ogni parte che prosegue, dentro il riquadro, nel carattere e nel corpo del testo del riquadro: in corsivo a meno che `continuesMarkerItalic` non sia `false`, allineato a destra a meno che `continuesMarkerAlign` non indichi `'left'` o `'center'`. Il segno occupa spazio nella parte che chiude, e il taglio viene scelto in modo che ci stia.
```ts
calloutStyles: [{
id: 'speech',
keepTogether: false,
titleStyle: { textTransform: 'uppercase' },
repeatTitle: true,
continuedSuffix: "(CONT'D)",
continuesMarkerEnabled: true,
continuesMarker: '(MORE)',
continuesMarkerAlign: 'center',
continuesMarkerItalic: false,
}],
```
```md
:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::
```
La parte che chiude la pagina termina con «(MORE)», e la pagina successiva si apre con «HAMLET (CONT'D)». Entrambi sono elementi di servizio dell’impaginazione: in un PDF accessibile sono artefatti e nell’HTML sono nascosti alle tecnologie assistive, così il titolo si legge una sola volta. Nel VDT sono blocchi di testo `designOverlay` contrassegnati `artifact: true`.
## Parti
La proprietà `parts` configura le pagine di parte che un documento apre con un contenitore `:::part{number="…" title="…"}`: la pagina «Parte I — Fondamenti» che raggruppa una serie di capitoli. Una parte occupa sempre una pagina propria: il contenitore passa a una pagina nuova della parità configurata, la converte in una pagina a una colonna la cui area del testo viene da `parts.margins`, stende il design di apertura sull’intera pagina, e interrompe di nuovo dopo il recinto di chiusura così il capitolo successivo (con il proprio `breakBefore.parity`) inizia pulito: con le impostazioni predefinite dell’H1 si ottiene la classica pagina di parte su recto, verso bianco, capitolo sul recto successivo.
```ts
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: 'Part {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' } },
},
};
```
```md
:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
3. Reading the weather
:::
# The lantern and its parts
```
| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `page` | `boolean` | `true` | Se un `:::part` apre una pagina di parte. Con `false` non si apre alcuna pagina e il corpo del recinto non si compone: il numero, il titolo e la tavolozza della parte hanno effetto dal contenuto successivo in poi, senza un’interruzione propria. Uso tipico: `htmlViewer.overrides.parts.page: false`, un’edizione per lo schermo senza pagine di sezione. |
| `breakBefore.parity` | `HeadingBreakParity` | `'odd'` | Parità della pagina su cui si apre la parte. Stessi valori e stesse regole di appartenenza delle pagine bianche del [breakBefore](https://postext.dev/it/docs/configuration-text.md#interruzione-prima-del-titolo) dei titoli: una pagina bianca inserita per raggiungere la parità appartiene alla parte (il suo `{partTitle}` si risolve già nella nuova parte); il separatore obbligatorio di `'always-*'` appartiene al contenuto precedente. |
| `breakAfter.enabled` | `boolean` | `true` | Sposta il contenuto dopo il recinto di chiusura su una pagina nuova. Con `false` prosegue nell’unica colonna della pagina di parte. |
| `breakAfter.parity` | `HeadingBreakParity` | `'any'` | Parità di quella pagina nuova. Lasciala su `'any'` e lascia che il `breakBefore.parity` del capitolo successivo decida se segue un verso bianco. L’interruzione si applica quando si colloca il blocco successivo, quindi una parte che chiude il documento non lascia una pagina vuota in coda. |
| `margins` | `PageMargins` | margini della pagina | Area del testo della pagina di parte: l’unica colonna in cui scorrono i blocchi dentro il recinto. Ogni lato non impostato eredita il margine della pagina; `mirror` scambia interno ed esterno sulle pagine pari esattamente come i margini della pagina. |
| `design` | `DesignSlot` | vuoto | Design di apertura. Il suo contenitore è il **formato rifilato** della pagina, quindi gli ancoraggi al contenitore e gli ancoraggi `'page'` coincidono e `'bleed'` arriva fino all’abbondanza quando i segni di taglio sono attivi. Puramente decorativo: non riserva mai spazio al testo; aumenta `margins.top` per tenere il testo lontano da esso. Quando è vuoto, si genera un testo predefinito `{number} {titleText}` nella tipografia dell’H1 in alto a sinistra dell’area del testo, con il `numberSeparator` dell’H1 tra numero e titolo. |
| `versoDesign` | `DesignSlot` | vuoto | Design del verso bianco che segue una pagina di parte (il retro del foglio di parte): stesso contenitore e stessi segnaposto di `design`. Lascialo vuoto per un verso semplice. Si disegna solo quando la pagina dopo la pagina di parte resta bianca, il che richiede un’interruzione con una parità: vedi più avanti [Il design del verso](https://postext.dev/it/docs/configuration-styles.md#il-design-del-verso). |
| `bodyStyle.fontFamily`, `fontSize`, `lineHeight`, `color`, `textAlign` | come in `bodyText` | eredita da `bodyText` | Tipografia dei paragrafi, delle citazioni in blocco e degli elementi di elenco dentro il recinto. Pesi, colori dell’enfasi e sillabazione vengono dal testo corrente. |
| `bodyStyle.bulletColor` | `ColorValue` | `unorderedLists.color` | Colore dei punti elenco degli elenchi non ordinati dentro la parte. |
| `bodyStyle.numberColor` | `ColorValue` | `orderedLists.color` | Colore dei numeri degli elenchi ordinati dentro la parte. I numeri si compongono sempre nel peso grassetto del testo corrente, così un elenco di capitoli si legge come un indice. |
| `bodyStyle.unorderedLists` | `UnorderedListsConfig` | — | Sostituzioni parziali applicate sopra l’`unorderedLists` del documento dentro la parte, dopo `bulletColor`. I valori validi per tutto l’elenco si propagano ai livelli che li ereditavano; le voci di `levels` si applicano solo al loro livello. |
| `bodyStyle.orderedLists` | `OrderedListsConfig` | — | Sostituzioni parziali applicate sopra l’`orderedLists` del documento dentro la parte, dopo `numberColor` e il peso grassetto: per esempio un `separator` `'•'` con i propri `separatorFontFamily` e `separatorColor` per l’elenco dei capitoli di un’apertura di parte. |
### Segnaposto del design di parte
Lo slot di design risolve l’insieme dei segnaposto dei titoli con i valori propri della parte: `{titleText}` è il `title` del recinto; `{number}` il `number` esattamente come è scritto; `{numberDecimal}`, `{numberRoman}`, `{numberRomanLower}`, `{numberAlpha}`, `{numberAlphaLower}` lo riformattano (il numero si interpreta come decimale, numero romano o numerali cinesi, con o senza le parole che li incorniciano: `"IV"`, `"iv"`, `"4"`, `"４"`, `"四"`, `"卷四"` e `"第四卷"` danno tutti `{numberDecimal}` = `4`), e si risolvono in `''` per qualsiasi altra cosa. Sono disponibili anche `{partTitle}` / `{partNumber}`, `{chapterTitle}` / `{chapterNumber}` (il capitolo prima della parte), `{pageNumber}`, `{totalPages}`, `{bookTotalPages}` e i segnaposto dei metadati. `{attr.}` legge gli attributi dell’H1 del capitolo corrente.
### Il design del verso
`versoDesign` decora la pagina subito dopo una pagina di parte quando quella pagina non contiene nulla: il retro del foglio di parte. La parte di per sé non lascia mai bianca quella pagina. `breakAfter.parity` vale `'any'` per impostazione predefinita, quindi il contenuto dopo il recinto inizia proprio nella pagina successiva a meno che qualcosa non chieda una parità:
- **Il titolo del capitolo successivo.** Il `breakBefore` predefinito dell’H1 è `'always-odd'`, e `'odd'` fa lo stesso dopo una pagina di parte su recto: il capitolo passa al recto successivo e il verso resta bianco. Il design del verso si disegna.
- **`parts.breakAfter: { enabled: true, parity: 'odd' }`.** È la parte stessa a chiedere il recto successivo, qualunque cosa faccia il titolo successivo. Usalo quando i capitoli possono aprirsi su entrambi i lati (`breakBefore.parity: 'any'`, o `breakBefore.enabled: false`).
Senza nessuno dei due, il capitolo si apre sul verso e non si disegna alcun design del verso. Con `breakAfter.enabled: false` il contenuto prosegue sulla pagina di parte stessa. Il verso prende la tavolozza della parte, quindi un `palette="band=#…"` sul recinto ricolora anche lui.
```ts
parts: {
breakBefore: { parity: 'odd' },
breakAfter: { enabled: true, parity: 'odd' }, // always a blank verso to paint
versoDesign: {
elements: [{
kind: 'box', id: 'field',
style: { backgroundColor: { hex: '#b07d2b', model: 'hex', paletteId: 'band' } },
placement: { anchor: { to: 'page', edge: 'top-left' }, size: { width: 'fill', height: 'fill' } },
}],
},
}
```
**Una parte che chiude il suo capitolo.** In un libro impaginato capitolo per capitolo (la Sandbox, `buildBundle`), un recinto `:::part` può essere un capitolo a sé, o la fine di uno. La sua pagina di parte è allora l’ultima pagina del capitolo, e il capitolo successivo si fa carico di ciò che la parte deve ancora: applica `breakAfter` prima del suo primo blocco e disegna `versoDesign` sulla sua prima pagina quando quella pagina resta bianca. Le pagine escono come uscirebbero con l’intero libro in un unico documento. Solo le direttive che non collocano nulla (`:::numbering`, `:::space`) possono seguire il recinto; qualsiasi altra cosa è contenuto del capitolo, che allora prende su di sé l’interruzione. Un capitolo vuoto subito dopo la parte è una pagina a sé: quella pagina è il verso. Un host che impagina da sé i capitoli ottiene questo da `continuationAfter()`, che riporta `afterPartPage: true` per un capitolo che termina con una parte; passalo nella `continuation` del capitolo successivo.
### Il contenitore `:::part`
Una riga `:::part{number="…" title="…"}` apre la parte e una riga `:::` da sola la chiude; entrambi gli attributi sono facoltativi (predefiniti a `''`). I blocchi tra le due righe (di solito l’elenco dei capitoli) scorrono nell’unica colonna della pagina di parte con `bodyStyle`, a partire da `margins.top`; un corpo più lungo della pagina prosegue su pagine ordinarie. La pagina è classificata `role: 'part'` (`VDTPage.partInfo` porta il numero e il titolo), così gli elementi di intestazione e piè di pagina possono indirizzarla o saltarla con `pages: 'part'` / `pages: 'body'`; il backend PDF aggiunge la parte ai segnalibri sopra i suoi capitoli. Un corpo vuoto (`:::part{…}` seguito direttamente da `:::`) è il caso comune e produce comunque la pagina: parti consecutive non ne condividono mai una. Un `:::part` annidato in un’altra parte viene appiattito in quella esterna.
Un terzo attributo, `palette="=[, =…]"`, dà alla parte colori propri: sulla pagina di parte e su ogni pagina che la segue, fino alla parte successiva, ogni colore di design (intestazione, piè di pagina, fascia di apertura, design di parte e del verso) collegato a uno di quegli id della tavolozza prende il valore della parte invece di quello della tavolozza del documento. È così che le sezioni di un libro ricolorano la linguetta d’angolo, il punto della testatina e la fascia di apertura dei capitoli senza un secondo design: `:::part{number="II" title="…" palette="band=#f6c297"}`. Anche il flusso del testo si adegua: sulle stesse pagine, ogni colore del flusso uguale al valore di base di una voce della tavolozza sostituita (colori dei titoli, del grassetto, del corsivo e dei rimandi, punti elenco e numeri degli elenchi, etichette e barre delle didascalie, testo, filetti e riempimenti delle tabelle, cioè intestazione, corpo, righe alternate e riempimento proprio di una cella, riquadri, cioè sfondo, bordo, fascia e titolo, e chip, cioè riempimento, contorno e testo) prende il valore della parte, quindi `headings.levels[1].color` collegato a `band` compone i titoli di ogni sezione nel suo colore. I campioni di colore in linea mantengono il colore scritto in essi. Le coppie si separano con virgole, punti e virgola o spazi, `=` o `:` uniscono id e colore, il `#` è facoltativo. Una parte resta in vigore dopo la chiusura del suo recinto: `{partTitle}`, `{partNumber}` e la tavolozza seguono il flusso nei capitoli successivi e, tramite `continuation.part`, che `continuationAfter()` riporta, nei capitoli impaginati separatamente, così il secondo capitolo di una sezione mostra la sezione nelle testatine esattamente come il primo.
Due voci della tavolozza possono condividere un valore di base e prendere comunque valori diversi in una parte, quando la parte ne sostituisce una e non l’altra o assegna loro colori diversi. Il solo valore non dice da quale voce provenga un colore del flusso, quindi ogni colore del flusso si abbina alle impostazioni da cui può provenire, e prende il valore a cui quelle impostazioni sono collegate. Si distinguono questi casi:
- i colori del testo di un blocco: il colore del testo, i colori del grassetto, del corsivo e dei rimandi, il segno dell’elenco (un punto elenco o un numero) e il separatore dopo un numero. Con `bodyText.color` collegato a `ink` e `bodyText.boldColor` collegato a `accent`, entrambi `#1a1a1a`, una parte con `palette="accent=#b8413d"` ricolora i tratti in grassetto e lascia il testo; con `unorderedLists.color` collegato invece a `accent`, ricolora i punti elenco e lascia il testo degli elementi;
- ogni livello di titolo, e ogni stile di titolo che imposta un colore;
- il testo di una riga del sommario, il suo numero, e il suo numero di pagina e il suo sottotitolo;
- in ogni stile di riquadro, i riempimenti (sfondo, fascia, linguetta), il bordo, i filetti (segno e linguetta) e il testo (titolo, icona, glifo del segno, linguetta);
- ogni colore di ogni stile di tabella, di chip e di didascalia. Uno stile di tabella con nome è distinto da `tableStyle`, e lo stile di didascalia di un tipo di risorsa da `captionStyle`. Il riempimento proprio di una cella segue il proprio collegamento.
Un caso si decide ancora in base al valore: impostazioni in posti diversi che impostano lo stesso colore di un blocco. `bodyText.color`, `bodyText.blockquote.color`, il `color` di uno stile di paragrafo e il `body.color` di uno stile di riquadro impostano tutti il colore del testo di un blocco, per esempio. Quando due di essi sono collegati a voci che condividono un valore di base e la parte le distingue, il colore prende la sostituzione (l’ultima scritta, quando sono sostituite entrambe). Assegna a tali voci valori di base propri.
```ts
const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => margins filled from the page, bodyStyle from the body / list configs
const minimal = stripPartsDefaults(config.parts);
// => undefined when only static defaults remain
```
## Stili dei titoli
La proprietà `headingStyles` dichiara stili con nome che un documento applica a un titolo con `# Title {style=""}`. Uno stile fa due cose. Sostituisce la tipografia, il progetto grafico e la numerazione del livello del titolo (ogni campo di una voce di livello tranne `level`: font, dimensione, colore, `breakBefore`, `span`, `advancedDesign`, `textTransform`, `hidden`, `numberingTemplate`…) e governa la **sezione** che il titolo apre: le sue pagine, fino al titolo successivo di livello uguale o superiore, prendono le testatine, la geometria della pagina, la tipografia del corpo e la palette dello stile. È così che le pagine preliminari di un libro (una prefazione in un’unica colonna larga con folio romani e bande blu) trovano posto in un manuale a due colonne con numerazione decimale senza una seconda configurazione.
```ts
const config: PostextConfig = {
headingStyles: [
{
id: 'front-matter',
numbered: false,
breakBefore: { enabled: true, parity: 'odd' },
span: 'page',
advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bands, `{titleText}` */] } },
header: { elements: [/* folio | rule | `{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' },
},
],
};
```
```md
# Preface {style="front-matter"}
```
| Proprietà | Tipo | Predefinito | Descrizione |
| --- | --- | --- | --- |
| `id` | `string` | — | Identificatore richiamato da `{style="…"}` su una riga di titolo. Un id sconosciuto lascia il titolo com’è. |
| `name` | `string` | `id` | Nome leggibile (solo per l’interfaccia dell’editor). |
| `numbered` | `boolean` | `true` | Se il titolo viene contato: fa avanzare il contatore del suo livello (i numeri di `numberingTemplate`, l’`{h1}` dei numeri delle risorse), l’ordinale di capitolo dietro `{chapterNumber}` e il numero stampato nell’indice. `false` per una prefazione, un elenco di autori, un indice: il primo capitolo numerato che segue resta il capitolo 1, e `{chapterNumber}` è vuoto nelle loro pagine. |
| `toc` | `boolean` | `true` | Se `:::toc` elenca il titolo. Un titolo lo sovrascrive con `{toc="false"}` / `{toc="true"}`. |
| `runningChapter` | `boolean` | `true` | Se un titolo di livello 1 con questo stile diventa il capitolo corrente: quello che `{chapterTitle}`, `{chapterNumber}`, `{attr.}` e le loro forme `…AtTop` nominano nella sua pagina e in quelle successive. `false` per una tavola, una carta geografica o una copertina composta come H1 dentro un capitolo: le testatine la scavalcano, anche nella sua stessa pagina, e continuano a nominare il capitolo che interrompe; non imposta nemmeno una parola guida `h1`. Il titolo viene comunque contato quando `numbered` (il suo progetto grafico legge il proprio `{chapterNumber}`) e resta elencato da `:::toc` quando `toc`. Con anche `toc: false` non riceve un segnalibro PDF: la tavola di un capitolo nella pagina che precede l’apertura lascia i segnalibri ai capitoli. I titoli degli altri livelli lo ignorano. Con il valore predefinito, le pagine dopo una tavola stampano il titolo della tavola. Una prefazione o un prologo con `numbered: false` resta un capitolo a sé e mantiene il valore predefinito. L’opzione cambia solo il capitolo che i segnaposto nominano: lo stile apre comunque una sezione propria, come ogni stile di titolo, quindi fino al titolo di livello 1 successivo le pagine prendono gli slot delle testatine, i margini, le colonne, lo stile del corpo e la palette dello stile della tavola (quelli del documento dove lo stile non li imposta), non quelli di una sezione con stile aperta dal capitolo interrotto. In un libro impaginato capitolo per capitolo, le testatine non passano da un file di capitolo al successivo, quindi una tavola che apre un file mostra segnaposto di capitolo vuoti fino al primo titolo di capitolo del file. |
| campi del livello | come in `headings.levels[]` | i valori del livello | `fontFamily`, `fontSize`, `lineHeight`, `fontWeight`, `italic`, `color`, `marginTop`, `marginBottom`, `snapToGrid`, `breakBefore`, `span`, `advancedDesign`, `textTransform`, `letterSpacing`, `lineSpan`, `indent`, `firstLineIndent`, `jidori`, `dropCap`, `hidden`: ognuno di quelli impostati sostituisce il valore del livello per i titoli con questo stile (`dropCap: false` toglie il capolettera del livello). `breakBefore` si fonde campo per campo con quello del livello: uno stile che imposta solo `parity` mantiene l’`enabled` del livello, e uno che imposta solo `enabled: true` ne mantiene la parità (fino a postext 1.4, il campo mancante veniva invece dal valore predefinito senza interruzione). |
| `numberingTemplate` | `string` | quello del livello | Modello con cui vengono numerati i titoli dello stile, al posto di quello del loro livello (stessi token di [`levels[].numberingTemplate`](https://postext.dev/it/docs/configuration-text.md#sovrascritture-per-livello)). Il contatore resta quello del livello: uno stile per le appendici con `'Appendix {1:A}'` dopo cinque capitoli stamperebbe *Appendix F*, quindi fai ripartire il conteggio con `{startAt=1}` sulla prima appendice. `''` non stampa alcun numero mentre il titolo viene comunque contato: nemmeno l’ordinale di capitolo che l’indice e `{chapterNumber}` mostrano per un titolo di livello 1 senza modello. Il numero compare nel flusso, nel `{number}` del progetto grafico dello stile, nell’indice e in `{chapterNumber}`. |
| `header`, `footer` | `DesignSlot` | quelli del documento | Testatine delle pagine della sezione, che sostituiscono lì `header` / `footer` (i filtri `parity` e `pages` degli elementi restano validi). Uno slot vuoto le rimuove. |
| `margins` | `PageMargins` | margini della pagina | Area del corpo delle pagine della sezione; ogni lato non impostato eredita il margine della pagina, `mirror` compreso. Ha effetto sulle pagine che la sezione apre: abbinalo a `breakBefore`. |
| `layout` | `LayoutConfig` | `layout` | Disposizione in colonne delle pagine della sezione (`layoutType`, `gutterWidth`…): un’unica colonna larga per una prefazione in un libro a due colonne. Il suo `columnRule` viene disegnato nelle pagine della sezione, e ogni campo che lascia non impostato prende il valore di `layout.columnRule` del documento, quindi una sezione che cambia solo le colonne mantiene il filetto del documento (vedi [Filetto tra le colonne](https://postext.dev/it/docs/configuration-page-layout.md#filetto-tra-le-colonne)). |
| `bodyStyle` | `PartsBodyStyleConfig` | eredita `bodyText` | Tipografia dei paragrafi, delle citazioni e degli elenchi della sezione: gli stessi campi di [parts.bodyStyle](https://postext.dev/it/docs/configuration-styles.md#parti). |
| `palette` | `Record` | `{}` | Sostituzioni della palette (id → esadecimale) per le pagine della sezione, sopra quelle della parte corrente: lo stesso meccanismo dell’attributo `palette` di una parte, e con la stessa portata. Non solo gli slot di progetto grafico impaginati in quelle pagine (testatine, la banda dell’apertura: ogni colore collegato a un id sostituito), ma anche il flusso del testo, per valore: ogni colore del flusso uguale al valore di base di una voce sostituita (colori di titoli, grassetto, corsivo e rimandi, punti elenco e numeri degli elenchi, etichette e barre delle didascalie, testo, filetti e riempimenti delle tabelle, riquadri (sfondo, bordo, banda, titolo) e chip (riempimento, contorno e testo)) prende il valore della sezione, come accade sotto una parte, compresa la regola per due voci che condividono un valore di base (vedi [Il contenitore `:::part`](https://postext.dev/it/docs/configuration-styles.md#il-contenitore-part)). I campioni di colore in linea mantengono il colore scritto al loro interno. Lo segue anche il colore della pagina: quando `page.backgroundColor` è collegato a una voce sostituita (o, non collegato, ha il suo valore di base), le pagine della sezione vengono dipinte con il valore della sezione, così le pagine economiche di un quotidiano escono color salmone mentre le altre restano bianche. Da postext 1.18. |
Una sezione si chiude al titolo successivo di livello uguale o superiore: un `#` senza stile dopo uno con stile torna alle testatine e alla geometria del documento; uno con stile apre una sezione propria. Le pagine che la sezione ha lasciato bianche per la parità le appartengono, come accade per i titoli di capitolo.
**Un’interruzione di pagina non sostituisce l’interruzione propria del titolo.** Uno stile eredita il `breakBefore` del suo livello (il valore predefinito del livello 1 è `{ enabled: true, parity: 'always-odd' }`), e un titolo lo applica ovunque si trovi, anche subito dopo un `:::pagebreak`. L’interruzione di pagina apre una pagina nuova, e il titolo chiede comunque il suo lato della doppia pagina. Con `parity: 'odd'`, un’interruzione che cade su un verso è seguita da una pagina bianca, così il titolo si apre sul recto successivo. Con `'always-odd'` arriva anche la pagina bianca di separazione, e l’interruzione di pagina non cambia nulla, perché il titolo avrebbe aperto quella pagina comunque. Uno stile pensato per cominciare nella pagina aperta da un’interruzione manuale, come una pagina di indice dopo il frontespizio, disattiva la propria interruzione:
```ts
headingStyles: [
// Starts where the text puts it: on the page the `:::pagebreak` before it opened.
{ id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],
```
Per avere una pagina propria senza scegliere un lato, imposta invece `breakBefore: { parity: 'any' }` e togli il `:::pagebreak`.
**A quale sezione appartiene una pagina.** Testatine e palette si scelgono per pagina, non per titolo. Una pagina prende la sezione in vigore dopo l’ultimo cambio di sezione che contiene: dove una sezione finisce e un’altra comincia nella stessa pagina (due lettere brevi di un dizionario, per esempio) la pagina porta le testatine e la palette della seconda; dove una sezione con stile finisce a metà pagina con un titolo senza stile, la pagina torna a quelle del documento. `{chapterTitle}` segue la stessa regola: una pagina in cui si incontrano due capitoli mostra il titolo del secondo. Le pagine bianche seguono la regola dei [titoli di capitolo](https://postext.dev/it/docs/configuration-text.md#a-chi-appartengono-le-pagine-bianche): una pagina bianca di parità (`blankForParity`) appartiene alla sezione che si apre dopo di essa, e quella di separazione che aggiunge un’interruzione `'always-odd'` / `'always-even'` (`blankForForce`) alla sezione precedente. Una pagina di parte chiude la sezione aperta.
```md
# A {style="letter"}
Aardvark, abacus.
# B {style="letter"}
Babble, badger… (runs on to the next page)
```
Entrambe le lettere cominciano a pagina 1, quindi la pagina 1 prende le testatine della sezione `B`: un’unghiatura posta nell’intestazione dello stile mostra lì «B», e nessuna pagina porta l’unghiatura di «A». Dai a ogni sezione una pagina propria (`breakBefore`) quando ognuna ha bisogno della sua unghiatura.
Appendici con lettere dopo capitoli numerati, e una pagina di dedica che l’indice e i segnalibri PDF elencano ma che nella pagina non mostra il titolo:
```ts
headingStyles: [
{ id: 'appendix', numberingTemplate: 'Appendix {1:A}' },
{ id: 'silent', hidden: true, numbered: false },
],
```
```md
# Dedication {style="silent"}
For M., who read every draft.
# Method
…
# Survey instrument {style="appendix" startAt=1}
# Raw data {style="appendix"}
```
Con `numberingTemplate: '{1}.'` al livello 1, i capitoli stampano *1.*, *2.*…, le appendici *Appendix A* e *Appendix B*. La dedica apre la sua pagina (il `breakBefore` del suo livello), stampa solo il suo paragrafo, e compare comunque come *Dedication* in `:::toc`, nelle testatine `{chapterTitle}` e nella struttura del PDF: aggiungi `toc: false` allo stile per escluderla dall’indice. Una tavola o una carta geografica composta come H1 a metà di un capitolo vuole il contrario della dedica: uno stile con `runningChapter: false` (di solito con `numbered: false` e `toc: false`) mantiene le testatine sul capitolo che interrompe.
```ts
const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => level overrides normalised, margins filled from the page, bodyStyle from the body
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined when no style remains
```