# Pagine composte > Il Markdown delle pagine composte: il recinto di pagina a quattro due punti che indica un modello di pagina, le cornici e l’attributo slot che mandano il contenuto nelle cornici del modello, le figure con le etichette sulle ancore di un’immagine, e gli avvisi che confrontano il contenuto con il modello - Versione HTML: https://postext.dev/it/docs/composed-pages - Ultimo aggiornamento: 2026-10-16 - Tempo di lettura: 9 min - Altre lingue: [en](https://postext.dev/en/docs/composed-pages.md), [es](https://postext.dev/es/docs/composed-pages.md), [ca](https://postext.dev/ca/docs/composed-pages.md), [de](https://postext.dev/de/docs/composed-pages.md), [fr](https://postext.dev/fr/docs/composed-pages.md), [pt](https://postext.dev/pt/docs/composed-pages.md), [zh](https://postext.dev/zh/docs/composed-pages.md), [ja](https://postext.dev/ja/docs/composed-pages.md), [ar](https://postext.dev/ar/docs/composed-pages.md) ## In breve Alcune pagine non sono una sola colonna di testo corrente ma un insieme di riquadri, come la pagina di un libro di scuola con una fascia per il titolo, un testo e tre riquadri colorati con le loro foto. Postext le chiama pagine composte. La forma della pagina è un modello nella configurazione, e il Markdown dice soltanto quale pezzo di testo va in quale riquadro. Questa pagina spiega come scrivere quel Markdown: il recinto della pagina, le cornici, i nomi degli slot e le immagini con etichette, come i nomi su una carta geografica. Elenca anche gli avvisi che Postext dà quando il testo e il modello non combaciano. **Il modello porta la forma della pagina; il Markdown porta il contenuto e dice in quale cornice va ogni pezzo.** Una pagina composta è una pagina impaginata a partire da un modello: cornici con un nome (una fascia per il titolo, un testo, un riquadro con la sua foto), gruppi che si spostano insieme e una decorazione, tutto definito nella configurazione sotto `pageTemplates`. Il Markdown della pagina è un blocco recintato che indica il suo modello e versa il contenuto nelle cornici chiamandole per nome. Nel Markdown non si scrive mai una posizione o una dimensione, e nella configurazione non si scrive mai il testo del contenuto: una traduzione è quindi lo stesso modello con altre parole. Questa pagina tratta il Markdown e il modo in cui la pagina ne viene composta. Il modello in sé (le sue cornici, le dimensioni, gli stili e la decorazione) è descritto in [Configurazione › Pagine composte](https://postext.dev/it/docs/configuration-composed-pages.md). Un documento senza pagine composte si impagina esattamente come prima. ## Il recinto della pagina ```md ::::page{template="tema-cajas" fondo="banda-retos"} # La actividad económica y el dinero Las personas utilizan :chip[recursos]{style="clave"} que se obtienen de la naturaleza… :::: ``` Una pagina composta si apre con una riga di **quattro due punti** seguita da `page` e dai suoi attributi, e si chiude con una riga che contiene soltanto **lo stesso numero di due punti**. Al suo interno i contenitori a tre due punti (`:::frame`, `:::callout`, `:::figure`, `:::columns`, `:::paper`) si aprono e si chiudono come sempre, quindi un `:::` da solo chiude il più interno di essi e mai la pagina. Una pagina scritta con cinque due punti (`:::::page`) si chiude con cinque; una riga di quattro due punti al suo interno è allora testo normale. | Attributo | Effetto | | --- | --- | | `template="…"` | Obbligatorio. L’id di una voce di `pageTemplates`. | | `spread` | La pagina è una doppia pagina su due pagine affiancate; anche il modello deve essere un modello di doppia pagina. | | `id="…"`, `#id` | Un’ancora: un `:ref` che la cita stampa la pagina su cui cade la pagina composta. | | qualsiasi altro | Un valore che il modello legge come `{attr.name}`, per esempio un’immagine di sfondo scelta pagina per pagina: `fondo="banda-retos"` con `resourceId: "{attr.fondo}"` nella decorazione. | Una pagina composta inizia sempre una nuova pagina (o doppia pagina), e il testo dopo il suo recinto di chiusura inizia sulla successiva. Il `:::page{split=…}` a tre due punti è una pagina di fumetto (vedi [Fumetti](https://postext.dev/it/docs/comics.md)) e mantiene questo significato. Un `:::page` a tre due punti che porta `template=` viene comunque letto come pagina di fumetto, e l’avviso `pageFenceLength` ricorda che una pagina composta richiede quattro due punti. Quando manca un recinto, il parser si riprende senza perdere testo: - una pagina lasciata aperta prosegue fino alla fine del capitolo e viene segnalata come contenitore non chiuso alla sua riga di apertura; - una riga `::::page` incontrata mentre una pagina è aperta chiude lì, prima di tutto, la pagina aperta (e viene segnalata allo stesso modo); - il recinto di chiusura chiude ogni cornice o riquadro ancora aperto dentro la pagina, segnalandoli uno per uno; - un recinto di chiusura con un altro numero di due punti non è quello della pagina: resta nel testo, dove lo vedi. ## Cornici e slot ```md :::frame{slot="dinero" label="El dinero"} Es el instrumento utilizado como medio de pago… Hasta hace pocos años, lo más normal era pagar con dinero en **efectivo**… ::: ``` Uno **slot** è il nome che un pezzo di contenuto richiede; corrisponde al nome di una cornice del modello. `:::frame{slot="…"}` manda tutto ciò che contiene in quella cornice. Il suo corpo accetta tutto il Markdown: paragrafi, elenchi, titoli, chip, inserimenti `::resource`, rimandi `:ref`, note a piè di pagina, `:::columns` e riquadri annidati. `label` e `title` danno le parole alla linguetta o al titolo della cornice, come per un `:::callout`; l’aspetto della cornice viene dallo stile di riquadro che il modello le assegna. Un singolo blocco può indicare da sé il suo slot: | Blocco | Come si scrive | | --- | --- | | Un titolo | `## Retos {slot="retos-titulo"}` | | L’inserimento di una risorsa | `::resource{id="dinero-pago" slot="dinero-fotos"}` (i due attributi, in qualsiasi ordine) | | Un listato di codice | `````js {slot="codigo"}`` | | Un riquadro o qualsiasi altro contenitore | `:::callout{type="nota" slot="aside"}`: l’intero riquadro va nello slot | | Una figura | `:::figure{resource="mapa" slot="mapa"}` (vedi sotto) | Il contenuto si distribuisce così: - Più pezzi con lo stesso slot vengono uniti nell’ordine del Markdown. - Il contenuto senza slot va nella **cornice di flusso** del modello (la cornice marcata `flow`). - Un titolo senza slot va per prima cosa nella cornice che prende il suo livello (`takes: "h1"`), se il modello ne ha una; così il titolo di un argomento del libro di scuola è semplicemente `# Titolo` in cima alla pagina. - Il contenuto che indica uno slot che il modello non ha va nella cornice di flusso e viene segnalato (`slotUnknown`). Fuori da una pagina composta, uno `slot` viene letto e non cambia nulla. ## Figure con etichette ```md :::figure{resource="mapa-europa" slot="mapa"} ::label[OCÉANO ATLÁNTICO]{at="atlantico" style="mar"} ::label[**Madrid**]{at="madrid"} ::label[Mar Negro]{at="62% 48%"} ::: ``` `:::figure{resource="…"}` colloca una risorsa, con la sua didascalia e il suo numero, come fa `::resource`, ed elenca le etichette da porre sull’immagine: una riga `::label[TEXT]{…}` per ciascuna, con righe vuote ammesse fra l’una e l’altra. - `at` indica un’ancora della risorsa (un punto definito una sola volta sull’immagine e comune a tutte le lingue), oppure dà un punto in percentuali dell’immagine, `at="x% y%"`, per un’etichetta senza ancora. - `style` indica uno stile di etichetta e prevale su quello dell’ancora. - Il testo fra parentesi quadre è Markdown in linea: grassetto, corsivo, chip. Una figura funziona nel testo corrente come in una cornice. Le etichette vengono lette e conservate con la loro sorgente; il loro disegno sull’immagine arriverà in una versione successiva, e fino ad allora una figura viene composta come la sua risorsa. Dentro una figura, una riga che non è né un’etichetta né vuota chiude una figura a cui manca il `:::` di chiusura, e viene segnalata come contenitore non chiuso. ## Esempio La pagina di un libro di scuola, con una fascia per il titolo, un testo con il suo elenco e tre riquadri colorati, ognuno con la sua foto accanto: ```md ::::page{template="tema-cajas" fondo="banda-retos"} # La actividad económica y el dinero ## La actividad económica Las personas utilizan :chip[recursos]{style="clave"} que se obtienen de la naturaleza… - Las :chip[empresas.]{style="clave"} Ofrecen bienes y servicios a cambio de un beneficio. - Las :chip[personas y familias.]{style="clave"} Adquieren lo que ofrecen las empresas… :::frame{slot="dinero" label="El dinero"} Es el instrumento utilizado como medio de pago, ya que su valor es conocido… ::: ::resource{id="dinero-pago" slot="dinero-fotos"} :::frame{slot="gasto" label="El gasto"} - **Fijo:** es el que se produce todos los meses… - **Variable:** puede cambiar según las necesidades… ::: ::resource{id="gasto-compras" slot="gasto-fotos"} :::frame{slot="ahorro" label="Préstamos y ahorro"} Si necesitas o quieres comprar algo muy caro… ::: ::resource{id="ahorro-balanza" slot="ahorro-fotos"} :::: ``` Il titolo va nella cornice che prende `h1`; il sottotitolo, il paragrafo e l’elenco vanno nella cornice di flusso; ogni riquadro e ogni foto vanno nella cornice del loro slot. L’edizione catalana è fatta delle stesse righe con altre parole: il modello, gli slot e le foto non cambiano. ## Come si compone la pagina Una pagina composta occupa una pagina tutta sua (ruolo `composed` per il filtro `pages` degli elementi di progetto grafico). Il modello si sceglie in base al lato su cui cade la pagina, quindi si applica il suo `variants.recto` o il suo `variants.verso`. Poi ogni cornice viene collocata e riempita, una dopo l’altra, con la tipografia del resto del libro: stili di paragrafo e di titolo, elenchi, chip, richiami di nota e lo stile di riquadro della cornice. ### Collocare le cornici Una cornice sta nella sua cella della griglia, o dove la mette il suo `placement` (un ancoraggio, un bordo e uno scostamento, come per un elemento di progetto grafico), oppure, senza né l’una né l’altro, nell’angolo in alto a sinistra dell’area del modello, larga quanto l’area. Una cornice ancorata a un’altra (`"to": "#dinero"`) viene collocata dopo di essa e si sposta con essa: `below` la appende sotto l’altra cornice, `right-of` la mette accanto, e un angolo come `top-right` la fissa a quell’angolo del riquadro dell’altra cornice. La sua altezza è fissa (una lunghezza o una percentuale), `fill` (fino al bordo dell’area) oppure `auto`, il valore predefinito: l’altezza del contenuto che riceve, fra `minHeight` e `maxHeight`, e mai oltre il piede dell’area. In una cornice più alta del suo contenuto, `verticalAlign` dice dove si colloca il contenuto (`top`, `middle`, `bottom`, oppure `justify` per distribuire lo spazio fra i suoi blocchi). Lo stile di riquadro della cornice disegna sfondo, bordo, angoli arrotondati, fascia e icona alla dimensione piena della cornice; il `label` del recinto `:::frame` si stampa nella linguetta dello stile. ### La cornice di flusso e i titoli Il contenuto che non indica nessuno slot va nella cornice marcata `flow`; il primo titolo di un livello va nella cornice che lo prende con `takes`. Le cornici di una pagina si leggono nell’ordine in cui il loro contenuto compare per la prima volta nel Markdown, ciascuna per intero: un lettore di schermo, il PDF con tag e le uscite a layout fluido leggono un riquadro dopo il testo che apre la pagina, non nel mezzo. ### Concatenare le cornici `next` manda ciò che una cornice non riesce a contenere in un’altra cornice della stessa pagina, e questa in un’altra ancora, come le cornici di testo concatenate dei programmi di impaginazione: ```json { "name": "columna-1", "flow": true, "next": "columna-2", "height": { "value": 120, "unit": "mm" } }, { "name": "columna-2", "placement": { "anchor": { "to": "#columna-1", "edge": "right-of" } } } ``` Il testo si interrompe fra due righe e prosegue nella cornice seguente, spezzato di nuovo alla larghezza di quella cornice, senza perdere né ripetere nulla. `overflow.continueIn: "#frame"` vuol dire la stessa cosa. Il proseguimento nella pagina successiva è previsto (`"next-page"`). ### Cornici che spostano il testo Una cornice con `exclude: "push"` tiene il testo delle altre cornici fuori dal suo rettangolo: la riga di un’altra cornice che lo incontra viene composta più corta dal lato coperto dal rettangolo, come il testo scontorna un’immagine nel testo corrente. Una foto ancorata all’angolo di un riquadro e marcata `push` fa scorrere il testo del riquadro accanto a sé. Un riquadro che deve tenere libera una colonna fissa per le sue immagini può usare invece `padding`. ### Decorazione, testatine e livelli La `decoration` del modello (immagini, filetti, riquadri e testi brevi) viene posata quando le cornici hanno già il loro riquadro definitivo, per cui un elemento può ancorarsi a una cornice (`"to": "#gasto"`) e seguirla. I suoi testi leggono gli attributi della pagina stessa: `fondo="banda-retos"` sul recinto della pagina dà `{attr.fondo}`, per esempio per scegliere pagina per pagina un’immagine di sfondo con `"resourceId": "{attr.fondo}"`. Anche le testatine li leggono. L’`header` o il `footer` di un modello sostituisce quello della sezione, `false` lo nasconde e, se il modello non ne imposta nessuno, si stampano le testatine della sezione. Le cornici si dipingono nell’ordine del loro `layer`: la decorazione al livello 0, le cornici al livello 1 per impostazione predefinita, un livello più alto sopra uno più basso, un livello negativo sotto la decorazione. `rotate` ruota una cornice insieme al suo contenuto, di qualsiasi angolo e attorno al centro della cornice, nel canvas, nel PDF, nel visualizzatore HTML e nell’EPUB a layout fisso. ### Contenuto che non entra Una cornice il cui contenuto è più alto di lei, senza una cornice seguente in cui proseguire, conserva tutto quel contenuto nel documento ma ne mostra solo quanto entra: il resto viene tagliato al piede della cornice nell’uscita impaginata, e l’avviso [`frameOverflow`](https://postext.dev/it/docs/composed-pages.md#frameoverflow) dice quanto. Il contenuto che nessuna cornice prende (non c’è una cornice di flusso, o su quel lato manca una cornice) viene composto nel testo corrente, nella pagina che segue la pagina composta. ## Avvisi I controlli leggono il Markdown e la configurazione prima di qualsiasi impaginazione, quindi compaiono già mentre scrivi nel pannello Verifiche, oltre che in `postext check` e nei `contentWarnings` del documento, ciascuno con l’intervallo di sorgente di ciò che riguarda (vedi [Configurazione › Avvisi nel documento](https://postext.dev/it/docs/configuration-programmatic-usage.md#avvisi-nel-documento)). | Tipo | Causa | Rimedio | | --- | --- | --- | | `templateUnknown` | Il recinto della pagina indica un modello che nessuna voce di `pageTemplates` definisce, oppure non ne indica nessuno. I suoi slot non vengono controllati. | Correggi l’id, oppure aggiungi il modello alla configurazione. | | `slotUnknown` | Uno `slot="…"` non indica alcuna cornice del modello della pagina (contano anche le cornici ereditate tramite `extends` e quelle di una pagina di `variants`). Il contenuto va nella cornice di flusso. | Correggi il nome dello slot, oppure aggiungi al modello una cornice con quel nome. | | `slotEmpty` | Una cornice del modello non riceve nulla in questa pagina: nessuno slot la indica, non prende alcun titolo e, se è la cornice di flusso, nessun contenuto resta senza slot. Una cornice che riceve solo il seguito di un’altra cornice (`next`) non viene segnalata. `postext check` la elenca come nota. | Scrivi un contenuto per quella cornice con il suo slot, oppure marca la cornice come `optional: true` nel modello. | | `pageFenceLength` | Un `:::page` a tre due punti porta `template=`. Viene letto come pagina di fumetto, come prima. | Apri la pagina con quattro due punti, `::::page{template="…"}`, e chiudila con `::::`. | | `unclosedContainer` | Una pagina composta, una cornice o una figura non viene mai chiusa (vedi sopra come si riprende il parser). Il pannello Verifiche chiama la pagina composta `::::page`. | Aggiungi il recinto di chiusura: tanti due punti quanti ne ha la riga di apertura della pagina, oppure `:::` per una cornice o una figura. | ### frameOverflow Questo avviso viene dall’impaginazione, non dai controlli sul sorgente descritti sopra: compare quando la pagina è già composta, nel pannello Verifiche, in `postext check` e nei `contentWarnings` del documento. **Causa.** Il contenuto che entra in una cornice (con il suo slot, o quello che riceve la cornice di flusso) è più alto della cornice, e la cornice non ha più un `next` in cui proseguire. Di solito c’è più testo di quanto la cornice ne contenga: una traduzione più lunga dell’originale, o una cornice vincolata a un `height` o a un `maxHeight` fissi. Quello che non entra viene tagliato al piede della cornice nell’uscita impaginata; resta nel documento, nella mappa del sorgente e nell’EPUB a layout fluido. L’avviso riporta il modello, la cornice, la pagina, l’altezza tagliata (`overflowMm`) e `configPath`, il puntatore JSON della cornice nella configurazione (`/pageTemplates/0/frames/2`). **Correzione.** Dai più spazio alla cornice (alza o togli il suo `height` o il suo `maxHeight`), collegala a un’altra cornice con `next`, accorcia il testo o componi la pagina con un altro modello. Per ora l’impaginazione non riduce il testo per farlo entrare. ## Dal codice `composedPages(blocks)` legge i blocchi analizzati di un capitolo (`parseMarkdownWithIssues(markdown).blocks`) e restituisce, in ordine, un nodo per ogni recinto di pagina: il suo `template`, `spread`, `attrs` con l’intervallo di sorgente di ogni valore (`attrSources`), il suo `fenceIndex` (il numero d’ordine del recinto nel capitolo, uguale in ogni lingua), `slots` (gli indici dei blocchi di ogni slot, nell’ordine del Markdown), `unassigned` (i blocchi senza slot) e l’intervallo di sorgente dell’intera pagina. Un blocco porta lo slot che indica in `ContentBlock.slot`, con l’intervallo di sorgente del valore; una figura è un `resourceBlock` il cui `figure` contiene i suoi attributi e le sue etichette, ciascuna con il suo testo, i suoi span in linea e una mappa che la riporta alla sua sorgente nel Markdown. `checkComposedSlots(pages, config)` restituisce i tre avvisi sugli slot per quelle pagine. Dopo l’impaginazione, il `VDTPage.composed` di una pagina composta registra il suo modello, la variante applicata, gli attributi del recinto della pagina e, per ogni cornice, il suo id (`cp0:dinero`: il numero d’ordine del recinto della pagina e il nome della cornice, uguale in ogni lingua), il suo riquadro, il livello, la rotazione, l’altezza del contenuto che non è entrato (`overflowPx`), la cornice da cui prosegue o in cui prosegue, il suo percorso nella configurazione (`/pageTemplates/0/frames/2`) e gli id dei suoi blocchi. Questi blocchi sono normali blocchi di riquadro in `page.floats` e `doc.blocks`, con i loro intervalli di sorgente, così un clic in una cornice non ruotata dell’anteprima del Sandbox porta al suo Markdown. `composedPaintOrder(page)` dà l’ordine in cui un renderer dipinge le cornici e la decorazione, e `frameMatrix(frame)` la rotazione di una cornice.