Motore di impaginazione open source · v1.77.0

Il compositore tipografico programmabile per il web

Postext prende Markdown semantico e applica regole editoriali secolari (giustificazione Knuth-Plass, colonne bilanciate, elementi flottanti che sanno stare al loro posto) per produrre pagine di qualità editoriale in HTML, canvas o PDF pronto per la stampa.

Ogni pagina viene calcolata nel tuo browser

Postext

In breve

Postext è un software libero e open source che impagina libri, riviste e relazioni. Scrivi il testo con pochi segni semplici, e Postext lo trasforma in pagine finite, come quelle di un libro stampato. Segue regole che i tipografi usano da secoli, così il testo è facile da leggere. Le pagine possono finire su un sito web, in un’app o in un PDF pronto per la stampa. È pensato per autori, editori, grafici e sviluppatori.

Trascrizione

Tutto ciò che dice la voce narrante, con una descrizione di ciò che appare sullo schermo.

  1. 0:00

    Sullo schermoUna scheda scura riporta «MAGONZA · 1455» sopra un sottile filetto dorato. Dietro il titolo «Per cinque secoli, la stampa ha imparato a comporre la pagina.», l’anno scorre da 1455 a 2026 in enormi cifre contornate, e attorno si posano termini di tipografia: Giustificazione, Crenatura, Vedove, orfane, Colonne bilanciate, Interlinea, Griglia di base, sil·la·ba·zio·ne, Giustezza, Flottanti, Testatine, Canali. La telecamera si tuffa nel punto finale, che inonda lo schermo d’oro.

    NarrazioneNel corso di cinque secoli, la stampa ha imparato a comporre la pagina.

  2. 0:06

    Sullo schermoTitolo: «Il web ha imparato a impaginare interfacce. Non ha mai imparato a comporre una pagina.» Una finestra del browser aperta su example.com/longform/article contiene un articolo giustificato su tre colonne, «Perché il web fallisce»; etichette rosse segnalano canali di bianco, un’orfana, una vedova, un’immagine che cade sul testo e un’ultima colonna sbilanciata. Accanto, un riquadro di codice mostra «column-count: 3;», poi «…e poco altro.» e un elenco barrato degli stessi cinque difetti: Canali di bianco, Orfane, Vedove, Collisioni, Colonne sbilanciate. La finestra si disturba e crolla.

    NarrazioneIl web ha imparato a impaginare interfacce. Mai pagine. Per questo il testo lungo continua a rompersi: canali di bianco, vedove, orfane, collisioni.

  3. 0:19

    Sullo schermoDopo un lampo bianco e una passata di strisce blu, oro e rosse, il logo e il nome di Postext salgono al loro posto con lo slogan «Il compositore programmabile per il web». Sotto: OPEN SOURCE · LICENZA MIT · v1.33.8 · FUNZIONA NEL TUO BROWSER.

    NarrazioneQuesto è Postext: il compositore programmabile per il web.

  4. 0:25

    Sullo schermoSezione 01 di 07, «Entra il contenuto»: «Il Markdown dice cos’è ogni cosa.» Un file Markdown, 03-perche-postext.md, si scrive da solo: una direttiva di parte, il titolo «Perché Postext» con un sommario, un paragrafo che rimanda alla figura fig-flow con :ref, una riga ::resource e un blocco :::callout. Accanto, config.ts chiama buildDocument con un’impaginazione a due colonne, il testo corrente giustificato e la sillabazione per "it", sotto la frase «La configurazione decide come appare. Il testo non contiene decisioni di impaginazione.»

    NarrazioneScrivi Markdown semantico, che dice che cos’è ogni cosa. La configurazione decide come appare.

  5. 0:33

    Sullo schermoSezione 02, «Pretext misura»: «Misurato senza toccare il DOM.» Un titolo, un paragrafo e un riquadro vengono scansionati uno dopo l’altro, e linee di quota ne danno l’altezza in punti; un pannello di codice mostra prepare(text, '25px Lora') e layout(prepared, width, 38), che restituiscono un’altezza e un numero di righe. Due barre gareggiano su 10.000 paragrafi: «Reflow del browser · DOM» si muove appena, mentre «Pretext · canvas + aritmetica» si riempie in un attimo, e un contatore sale fino a 600× sopra «più veloce del DOM nel misurare il testo, così un libro intero si ricompone mentre scrivi.» e «Basato su @chenglou/pretext».

    NarrazioneOgni paragrafo si misura senza toccare il DOM, fino a seicento volte più in fretta, grazie a Pretext, la libreria che l’ha reso possibile.

  6. 0:44

    Sullo schermoSezione 03, «Postext decide»: «Ogni riga al suo posto prima di disegnare un pixel.» Un anello di sette segmenti si accende a turno, Struttura, Misura, Collocazione, Flottanti, Rifinitura, Equilibrio e Ritmo, ognuno con una descrizione di una riga, mentre accanto si compone una pagina a due colonne della guida di Postext: blocchi etichettati volano nelle loro colonne, una figura scivola al suo posto sotto la nota «:ref{id="fig-flow"} → piede della colonna», la fascia d’apertura scende, compaiono le righe, le colonne si pareggiano e una griglia della linea di base scorre dall’alto in basso. L’anello ripete le iterazioni da 1 a 3 e mostra «Stabile in 3 iterazioni» con un segno di spunta; un fumetto indica il riquadro di delimitazione e la linea di base di una riga.

    NarrazionePoi Postext decide. Sette passate collocano ogni riga, portano ogni figura al suo posto e bilanciano le colonne, finché nulla si muove più.

  7. 0:57

    Sullo schermoSezione 04, «Il documento virtuale»: «Cambia una parola. Si ricompone solo ciò che cambia.», con la nota «Come il virtual DOM di React, ma per le pagine: il VDT, un albero virtuale del documento.» Sette pagine, da p. 7 a p. 13, stanno in fila; un cursore segna una modifica a pagina 11, il resto di quella colonna diventa oro con la scritta DA RIFARE e un filo di testo trabocca a pagina 12, che riceve un segno di spunta e STABILE, mentre le pagine precedenti riportano SALTATA e quelle successive INTATTA. Tre punti enunciano la regola, e un pannello intitolato renderToHtmlIndexed() segna come AGGIORNATO i nodi modificati dell’albero del documento.

    NarrazioneTutto vive in un documento virtuale, come il virtual DOM di React. Cambi una parola, e si ricompone solo ciò che cambia.

  8. 1:06

    Sullo schermo«Un documento lungo? Si disegna solo ciò che è sullo schermo.» Una colonna di pagine di libro scorre dentro una cornice dorata con la scritta VIEWPORT, con un margine di 200 pixel sopra e sotto: le pagine all’interno sono disegnate per intero, quelle all’esterno sono contorni tratteggiati. Un grande contatore mostra quante delle 51 pagine sono disegnate in quel momento (IntersectionObserver · +200 px), accanto a «Geometria: tutte le pagine. Pixel: solo ciò che vedi.»

    NarrazioneE in un libro lungo, si disegnano soltanto le pagine che sono visibili sullo schermo.

  9. 1:13

    Sullo schermoSezione 05, «Giustificazione Knuth–Plass»: «Tutti i modi di dividere il paragrafo. Insieme.» A sinistra, sotto «Greedy · il browser», un paragrafo sulla divisione in righe è composto in modo greedy, come fa un browser, e le sue righe più larghe diventano rosse. Sotto, ogni parola diventa un punto su una linea: archi rossi segnano gli a capo greedy, tenui archi blu provano ogni a capo possibile e un percorso dorato sceglie l’insieme migliore. A destra, la versione «Knuth–Plass · Postext» ha una spaziatura uniforme, con i demeriti di ogni riga, la formula «(1 + badness + penalità)²» e un totale di demeriti più basso.

    NarrazioneUn browser spezza le righe in modo ingordo, una alla volta. Postext usa Knuth-Plass, l’algoritmo di TeX: soppesa tutti i modi di spezzare l’intero paragrafo e tiene il più uniforme.

  10. 1:28

    Sullo schermoSezione 06, «Un’impaginazione, cinque output»: «Ciò che vedi è ciò che va in stampa.» Sotto la riga di codice const vdt = buildDocument(content, config); una pagina si divide in cinque. Canvas (renderToCanvas(), bitmap esatte al pixel) riceve una lente d’ingrandimento sulla sua griglia di pixel; HTML (renderToHtml(), selezionabile e responsive) vede ogni blocco contornato ed etichettato <h1>, <p>, <figure> e così via; PDF (renderToPdf(), per la stampa, PDF/UA, CMYK) fa scivolare quattro lastre di colore fino al registro, poi compaiono i segni di taglio e una scala colori. EPUB 3 (renderToEpub(), e-book, fisso o fluido) mostra la pagina in un lettore di e-book con l’etichetta «Layout fisso»; lo schermo si restringe alle dimensioni di un telefono, il testo si ricompone e l’etichetta diventa «Layout fluido». Folio (postext-folio, un libro 3D che si sfoglia) apre la pagina in una doppia pagina e gira un foglio sopra il dorso.

    NarrazioneUn’impaginazione, cinque output: canvas, HTML, PDF per la stampa, EPUB 3, fisso o fluido, e un libro in 3D. Quello che vedi è quello che va in stampa.

  11. 1:43

    Sullo schermoSezione 07, «Perché uno standard aperto»: «LaTeX ha fatto scuola sulla carta. Oggi l’editoria vive anche su ogni schermo.» Due schede: LaTeX, 1984, con delle croci accanto a «Pensato per la pagina stampata», «Legato ai font e ai pacchetti di una macchina», «Compilare, aspettare, ripetere» e «Niente impaginazione editoriale nel web responsive»; Postext, 2026, con dei segni di spunta accanto a «Web, PDF per la stampa ed EPUB 3, un’impaginazione», «Un solo file .postext contiene tutto», «Si ricompone dal vivo mentre scrivi» e «In ogni browser · senza server · MIT». La scheda di Postext si illumina.

    NarrazioneLaTeX ha fissato lo standard della carta. Ma oggi l’editoria vive su tutti gli schermi.

  12. 1:50

    Sullo schermoOcchiello «Un file, l’intero libro», titolo «Uno standard aperto per l’editoria, oltre i confini di LaTeX.» L’icona di un file .postext si apre in cinque parti: preset.json (configurazione e grafica), chapters/*.md (un Markdown per capitolo), fonts/*.woff2 (i font stessi), images/ · SVG (ogni immagine, inclusa) e resources (tabelle, figure e didascalie). Didascalia: «Un normale ZIP: aperto, documentato e con licenza MIT. Qualsiasi strumento può leggerlo e scriverlo.»

    NarrazionePostext è uno standard aperto: un unico file portabile, documentato e con licenza MIT, che qualunque strumento può leggere e scrivere.

  13. 2:02

    Sullo schermo«La vetrina · composta dal vero motore»: un muro di pagine dell’edizione italiana della guida si allontana in prospettiva mentre un contatore arriva a 51 pagine. Testo: «11 capitoli, 3 parti e le copertine, impaginati in meno di un secondo. Ogni pagina della guida di Postext, calcolata in un browser da postext v1.33.8 per questo video. Nulla messo a mano.» Seguono le etichette Libri di testo, Riviste, Edizioni letterarie, Cataloghi.

    NarrazionePer questo riesce a impaginare libri di centinaia di pagine in pochi decimi di secondo.

  14. 2:10

    Sullo schermoScheda finale: il logo di Postext con lo slogan «Il compositore programmabile per il web», l’indirizzo postext.dev, una riga di terminale che digita «$ pnpm add postext», e il piede «Open source · MIT · github.com/drnachio/postext».

    NarrazionePostext. Open source, su postext.dev.

Capitolo 1 · Perché Postext

Impaginazione editoriale, calcolata per il web

La tipografia a stampa ha impiegato cinque secoli a imparare come comporre una pagina; i browser hanno imparato a disporre un’interfaccia. Postext porta la prima nei secondi.

Il CSS ti dà un layout responsive: flexbox, grid, colonne. Ma non sa bilanciare le colonne, tenere un titolo con il suo paragrafo, evitare vedove e orfane o far flottare una figura in testa alla colonna successiva. Sono decisioni editoriali, affinate in secoli di stampa.

Postext colma questa distanza. Gli dai Markdown semantico e un oggetto di configurazione. Misura il testo da 300 a 600 volte più in fretta del DOM grazie a @chenglou/pretext (si apre in una nuova scheda), poi calcola la geometria completa della pagina (ogni riga, elemento flottante e didascalia) e la disegna con i backend HTML, canvas o PDF pronto per la stampa.

Markdown in ingresso

:::part{number="I" title="Fondamenti"
  palette="band=#2b4acb"}
:::

# Perché Postext {lead="La tipografia
a stampa ha impiegato cinque secoli…"}

Postext è un **motore di
impaginazione open source** che
porta sul web il mestiere della
tipografia a stampa, come mostra
:ref{id="fig-flusso"}.

:::callout{type="try"}
Cambia una parola: la pagina
si ricompone.
:::

Pagine in uscita

Figura 1.1 Lo stesso Markdown prima e dopo il motore: un’apertura di capitolo, due colonne bilanciate e una figura spostata in testa a una colonna.

In cifre

più veloce del DOM nel misurare il testo, così un libro intero si ricompone mentre scrivi
300–600×più veloce del DOM nel misurare il testo, così un libro intero si ricompone mentre scrivi
output da un’unica impaginazione: HTML, canvas, PDF pronto per la stampa ed EPUB 3
4output da un’unica impaginazione: HTML, canvas, PDF pronto per la stampa ed EPUB 3
output PDF accessibile e con tag, con segnalibri e colori CMYK
PDF/UAoutput PDF accessibile e con tag, con segnalibri e colori CMYK
server: il motore gira interamente nel browser, con licenza MIT
0server: il motore gira interamente nel browser, con licenza MIT

Capitolo 2 · Funzionalità

Quello che i compositori tipografici hanno sempre saputo

Sei cose di cui una pagina ha bisogno e che il CSS non è mai stato pensato per decidere: le calcola il motore, ogni volta allo stesso modo.

  1. 2.1

    Giustificazione Knuth-Plass

    Lo stesso algoritmo ottimale di divisione in righe usato da TeX, con sillabazione a pattern TeX e controllo delle orfane: blocchi di testo composti in modo uniforme, senza canali di bianco, ben oltre ciò che il CSS sa esprimere.

    Leggi nella documentazione
  2. 2.2

    Risorse e rimandi

    Figure, diagrammi SVG e tabelle flottano in cima o in fondo a colonne e pagine, come gli elementi flottanti della stampa, con numerazione per tipo e rimandi :ref sempre aggiornati.

    Leggi nella documentazione
  3. 2.3

    Tabelle e didascalie

    Tabelle con tipografia indipendente per corpo e intestazione, divise tra le pagine con intestazioni ripetute, e didascalie che seguono la tua configurazione: numerate e collocate accanto alla risorsa che descrivono.

    Leggi nella documentazione
  4. 2.4

    Diagrammi a un solo inchiostro

    Ricolora i diagrammi SVG in tinte di un solo inchiostro in base alla luminanza, così ogni illustrazione si accorda al tuo progetto grafico: pronta per la stampa a colori speciali.

    Leggi nella documentazione
  5. 2.5

    Formule LaTeX

    Equazioni in linea e in display scritte in LaTeX, misurate e composte dal motore in modo che poggino sulla griglia della linea di base insieme al testo.

    Leggi nella documentazione
  6. 2.6

    Web, PDF pronto per la stampa ed EPUB

    Un motore di impaginazione, quattro output. Le stesse pagine calcolate diventano HTML, canvas o PDF pronto per la stampa (con segnalibri, colori CMYK e output PDF/UA accessibile e con tag) ed escono come e-book EPUB 3, pagina per pagina o a layout fluido.

    Leggi nella documentazione
Ogni pagina della guida di Postext, copertina, indice e pagine di parte comprese, è composta da Postext, nel tuo browser, mentre la leggi.
— Colophon della guida integrata

Vetrina

Libri veri, composti nel tuo browser

Un manuale, una rivista, un poema epico annotato, un catalogo di mostra, un classico cinese in 120 capitoli, Le mille e una notte in arabo, un romanzo giapponese composto in verticale, un fumetto in dieci lingue. Aprine uno qualsiasi nella Sandbox, cambia una regola e guarda ogni pagina ricomporsi.

Capitolo 3 · Flusso di lavoro

Tre passi verso un’impaginazione di qualità editoriale

Contenuti in Markdown, progetto grafico in un oggetto di configurazione, pagine da una sola chiamata di funzione.

  1. 3.1

    Scrivi Markdown semantico

    Scrivi i tuoi contenuti in Markdown arricchito: titoli, elenchi, tabelle, formule, riquadri e rimandi :ref alle tue figure. Nessuna preoccupazione di impaginazione, solo contenuti.

  2. 3.2

    Configura le regole di impaginazione

    Definisci formato della pagina, colonne, tipografia, stili dei titoli, testatine e collocazione degli elementi flottanti in un oggetto PostextConfig, oppure progettali visivamente nella Sandbox.

  3. 3.3

    Esporta in HTML, canvas o PDF

    Chiama buildDocument e ricevi la geometria completa dell’impaginazione, poi disegnala con il backend HTML, canvas o PDF pronto per la stampa.

API

Una funzione, pieno controllo

Chiama buildDocument con i tuoi contenuti e un oggetto di configurazione. Ottieni la geometria completa delle pagine: disegna qualsiasi pagina come immagine con renderPage, oppure componi l’intero libro come PDF pronto per la stampa con renderToPdf.

book.ts
import { buildDocument, renderPage } from "postext";
import { renderToPdf } from "postext-pdf";

const doc = buildDocument(
  { markdown },
  {
    page: { sizePreset: "21x28" },
    layout: { layoutType: "double" },
    bodyText: {
      fontSize: { value: 12, unit: "pt" },
      textAlign: "justify",
      hyphenation: { enabled: true, locale: "en-us" },
    },
  }
);

// Ogni pagina come immagine…
const cover = renderPage(doc.pages[0], doc);
cover.toBlob((png) => save(png, "cover.png"));

// …oppure l’intero libro come PDF pronto per la stampa
// fontProvider: byte TTF per famiglia e peso (vedi la documentazione)
const pdf = await renderToPdf(doc, { fontProvider });

Capitolo 4 · Formato aperto

Un file, il libro intero

Un file .postext contiene tutto ciò che serve per comporre di nuovo un documento, su qualsiasi macchina: un formato aperto e modificabile che chiunque può adottare.

Quasi tutti i formati editoriali disperdono un progetto. La compilazione di un documento LaTeX dipende dai font e dai pacchetti installati su una macchina, e i file nativi dei principali programmi di impaginazione rimandano a immagini e caratteri conservati fuori da essi. Sposti il progetto e qualcosa va perso. Abbiamo incontrato questi limiti con LaTeX in prima persona.

Un .postext è un semplice archivio ZIP che chiunque può aprire, leggere e modificare: un manifest JSON, un file Markdown per capitolo, e i file dei font e le immagini stessi. La Sandbox lo esporta, la skill per agenti postext-port lo scrive e postext/bundle lo apre in qualsiasi programma per comporre di nuovo le stesse pagine. Il formato è documentato e con licenza MIT, pronto perché qualsiasi strumento lo legga e lo scriva.

Dentro postext-guide.postext
  1. 4.1preset.json

    Configurazione. Pagina, griglia, caratteri, stili di titolo e di paragrafo, colori e testatine, in JSON leggibile.

  2. 4.2chapters/<lang>/*.md

    Capitoli. Un file Markdown per capitolo: qui 22 capitoli in 2 lingue.

  3. 4.3fonts/*.woff2

    Caratteri. I file dei font, non solo i loro nomi: 23 file di Lora, Fraunces, Geist, Bricolage Grotesque e Geist Mono.

  4. 4.4preset.json › resources

    Risorse. Didascalie, numerazione, collocazione e contenuto delle tabelle per le 30 figure e tabelle a cui il testo rimanda.

  5. 4.5resources/*.svg

    Immagini. Le illustrazioni stesse, SVG o bitmap, con la versione di ogni lingua: 41 file.

Figura 4.1 Il .postext della guida, 1364 KB: tutto ciò che serve al libro, e niente che debba scaricare.

Prova

Apri la guida, ottieni le sue pagine

Il primo esempio della Sandbox, la guida di Postext, è un solo file .postext. Aprilo nel browser e trasforma ogni pagina in un’immagine: caratteri, figure e tabelle vengono dal file stesso.

Scarica la guidapostext-guide.postext · 1364 KB
open-guide.js
import { openBundle, loadBundleFonts, registerBundleImages,
  buildBundle, renderPageToCanvas } from "postext";

// La guida della Sandbox: configurazione, capitoli, font e immagini
const file = await fetch("postext-guide.postext").then((r) => r.blob());
const book = await openBundle(file, { locale: "en" });

await loadBundleFonts(book);      // i suoi caratteri
await registerBundleImages(book); // le sue figure

// Ogni pagina di ogni capitolo, come immagine
for (const doc of buildBundle(book))
  for (const page of doc.pages) {
    const canvas = document.createElement("canvas");
    renderPageToCanvas(page, doc, canvas, { scale: 0.5 });
    document.body.append(canvas);
  }

Installazione

Comincia in meno di un minuto

Un pacchetto, nessun server, nessuna dipendenza nativa. Aggiungi postext-pdf quando ti serve la stampa.

quick-start.ts
// Avvio rapido
import { buildDocument, renderPage } from "postext";
import { renderToPdf } from "postext-pdf";

const doc = buildDocument({
  markdown: "# Hello World\n\nYour content here.",
});

// La prima pagina, disegnata su un canvas
document.body.append(renderPage(doc.pages[0], doc));

// L’intero documento come PDF
const pdf = await renderToPdf(doc, { fontProvider });