# Utilisation programmatique : HTML, Folio et EPUB
> Le livre mis en page dans une page web, en livre 3D avec postext-folio, et en EPUB 3 à mise en page fixe ou recomposable avec postext-epub
- Version HTML: https://postext.dev/fr/docs/configuration-html-folio-epub
- Dernière mise à jour: 2026-10-16
- Temps de lecture: 19 min
- Autres langues: [en](https://postext.dev/en/docs/configuration-html-folio-epub.md), [es](https://postext.dev/es/docs/configuration-html-folio-epub.md), [ca](https://postext.dev/ca/docs/configuration-html-folio-epub.md), [de](https://postext.dev/de/docs/configuration-html-folio-epub.md), [it](https://postext.dev/it/docs/configuration-html-folio-epub.md), [pt](https://postext.dev/pt/docs/configuration-html-folio-epub.md), [zh](https://postext.dev/zh/docs/configuration-html-folio-epub.md), [ja](https://postext.dev/ja/docs/configuration-html-folio-epub.md), [ar](https://postext.dev/ar/docs/configuration-html-folio-epub.md)
## En bref
Cette page s’adresse aux personnes qui écrivent du code et veulent montrer un livre à l’écran. La première section place les pages dans une page web et explique en quoi cette vue diffère du canvas et du PDF. La deuxième montre le livre en 3D, ouvert sur un bureau, avec des pages que le lecteur tourne. La dernière section produit un livre numérique EPUB, à pages fixes ou avec un texte qui s’adapte à l’écran, et vérifie le fichier.
## Intégrer la visionneuse HTML
La visionneuse HTML est le moteur de rendu de Postext conçu d’abord pour l’écran. Au lieu de rastériser les pages en image bitmap, elle produit des nœuds DOM positionnés en absolu, dont la géométrie vient du même pipeline que la sortie imprimée. C’est donc le bon choix quand vous voulez, dans un navigateur, une typographie lisible, sélectionnable et qui suit le redimensionnement (une application de lecture, un aperçu intégré à un produit, une documentation embarquée) sans charger de visionneuse PDF.
Les pièces essentielles de l’API publique :
- **`buildDocument(content, config, cache?)`** : exécute tout le pipeline de mise en page et renvoie un `VDTDocument`.
- **`renderToHtmlIndexed(doc, options)`** : transforme le VDT en une seule chaîne HTML accompagnée d’un découpage par page et par bloc. Ce découpage permet de patcher le DOM à peu de frais quand seuls quelques blocs ont changé d’un rendu à l’autre.
- **`resolveHtmlViewerConfig(partial)`** : complète la configuration avec les valeurs par défaut de la visionneuse HTML (`maxCharsPerLine`, `columnGap`, `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`** : primitives de mesure qui servent à déduire une largeur de colonne réelle, en pixels, d’un nombre de caractères visé.
- **`createMeasurementCache` / `clearMeasurementCache`** : caches interchangeables qui permettent de réutiliser les mesures d’une mise en page à l’autre.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`** : chargent les fontes du document avant la mise en page et relancent la mise en page quand des fontes arrivent (voir [Charger les polices avant la mise en page](https://postext.dev/fr/docs/configuration-programmatic-usage.md#charger-les-polices-avant-la-mise-en-page)).
### Exemple en direct : une chaîne HTML
L’aller-retour complet en JavaScript simple, avant l’intégration React plus bas : construisez le document, passez le `VDTDocument` à `renderToHtml` et déposez la chaîne dans un conteneur. `mode: 'single'` empile les pages verticalement ; `background` leur donne une couleur, car les pages sont transparentes par défaut. Le pen affiche aussi le balisage généré, ce qui vous laisse voir les lignes positionnées en absolu que produit le moteur de rendu : le navigateur les peint mais ne les recompose jamais.
> **Exemple exécutable: Postext · rendre un document en HTML** — Mettre en page un document Markdown avec postext et le rendre en chaîne HTML. ([code](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### Intégration minimale
L’extrait ci-dessous est l’intégration utile la plus courte : construire le document à la taille actuelle de la fenêtre, le rendre dans un conteneur et recommencer à chaque redimensionnement.
```tsx
import { useEffect, useRef } from 'react';
import {
buildDocument,
renderToHtmlIndexed,
resolveHtmlViewerConfig,
buildFontString,
measureGlyphWidth,
dimensionToPx,
createMeasurementCache,
watchFonts,
onFontsChanged,
} from 'postext';
import type { PostextConfig, MeasurementCache } from 'postext';
// Screen-friendly DPI: at 144 DPI, an 8pt body size resolves to 16 px.
const HTML_DPI = 144;
const PADDING_PX = 24;
// Prose sample used to measure the target column width. Proportional fonts
// make "N × average width" unreliable, so we measure a representative string.
const SAMPLE =
'The quick brown fox jumps over the lazy dog. Sphinx of black quartz, judge my vow.';
function sampleForChars(n: number): string {
let s = SAMPLE;
while (s.length < n) s += ' ' + SAMPLE;
return s.slice(0, n);
}
export function PostextHtmlViewer({
markdown,
config,
mode = 'multi',
}: {
markdown: string;
config: PostextConfig;
mode?: 'single' | 'multi';
}) {
const hostRef = useRef(null);
const cacheRef = useRef(createMeasurementCache());
useEffect(() => {
const host = hostRef.current;
if (!host) return;
const relayout = () => {
const rect = host.getBoundingClientRect();
if (rect.width === 0 || rect.height === 0) return;
const viewer = resolveHtmlViewerConfig(config.htmlViewer);
const fontFamily = config.bodyText?.fontFamily ?? 'EB Garamond';
const fontWeight = config.bodyText?.fontWeight ?? 400;
const fontSize = config.bodyText?.fontSize ?? { value: 8, unit: 'pt' as const };
const fontSizePx = dimensionToPx(fontSize, HTML_DPI);
// Measure the *actual* column width for N characters of body prose.
const targetColumnPx = measureGlyphWidth(
sampleForChars(viewer.maxCharsPerLine),
buildFontString(fontFamily, fontSizePx, String(fontWeight), 'normal'),
);
const inner = Math.max(rect.width - PADDING_PX * 2, 100);
let columnWidthPx: number;
if (mode === 'single') {
columnWidthPx = Math.min(targetColumnPx, inner);
} else {
// Fit as many columns as we can at the target width.
const count = Math.max(
1,
Math.floor((inner + viewer.columnGap) / (targetColumnPx + viewer.columnGap)),
);
columnWidthPx = (inner - viewer.columnGap * (count - 1)) / count;
}
columnWidthPx = Math.max(Math.floor(columnWidthPx), 80);
// Single mode uses one very tall page; multi mode uses the viewport
// height so each VDT "page" becomes one column.
const pageHeightPx =
mode === 'single' ? Math.max(rect.height * 20, 200_000) : Math.max(rect.height - PADDING_PX * 2, 400);
const override: PostextConfig = {
...config,
page: {
...config.page,
dpi: HTML_DPI,
width: { value: columnWidthPx, unit: 'px' },
height: { value: pageHeightPx, unit: 'px' },
margins: {
top: { value: 0, unit: 'px' },
bottom: { value: 0, unit: 'px' },
left: { value: 0, unit: 'px' },
right: { value: 0, unit: 'px' },
},
},
layout: { ...config.layout, layoutType: 'single' },
bodyText: {
...config.bodyText,
optimalLineBreaking: viewer.optimalLineBreaking,
},
};
const doc = buildDocument({ markdown }, override, cacheRef.current);
const { html } = renderToHtmlIndexed(doc, {
mode,
columnGap: viewer.columnGap,
padding: PADDING_PX,
background: 'transparent',
});
host.innerHTML = html;
};
relayout();
const ro = new ResizeObserver(() => relayout());
ro.observe(host);
// Re-measure when web fonts land so glyph widths aren't taken from fallbacks.
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
Quelques remarques sur ce que fait cet exemple :
- **Mesurer la colonne plutôt que l’estimer.** Comme `maxCharsPerLine` est une *cible* exprimée en caractères, la largeur réelle en pixels dépend de la police du texte courant. `measureGlyphWidth` donne une vraie mesure dans la police choisie, ce qui garde la longueur de ligne constante quand on change de police.
- **Réécrire la page.** La visionneuse HTML traite chaque « page » du VDT comme une colonne à l’écran. L’exemple remplace `page.width` par la largeur de colonne mesurée, met les marges à zéro (la marge intérieure se trouve hors de la page, dans le div `.pt-doc` qui l’enveloppe) et utilise `HTML_DPI = 144` pour qu’un texte courant de `8pt` donne `16px`.
- **Tenir compte du chargement des polices.** `watchFonts` écoute `document.fonts` et, une fois par image, oublie ce qui a été mesuré dans les familles dont des fontes sont arrivées ; `onFontsChanged` relance ensuite la mise en page de la colonne. Sans cette relance, le premier rendu utilise les métriques d’une police de secours et saute quand la vraie police arrive.
- **Réutiliser le cache de mesures.** Créer le cache une seule fois par composant permet aux redimensionnements et aux changements d’échelle de police de reprendre les mesures du rendu précédent au lieu de remesurer chaque paragraphe.
### Aller plus loin
L’exemple ci-dessus est volontairement dépouillé. Les intégrations en production ajoutent en général :
- **L’isolation par Shadow DOM** : rendre dans `host.attachShadow({ mode: 'open' })` pour qu’aucune règle CSS de la page extérieure ne déborde sur la visionneuse.
- **Le patch incrémental** : `renderToHtmlIndexed` renvoie `pages[i].blocks`, chacun avec un `id` stable et le HTML extérieur du bloc. Quand seuls quelques blocs diffèrent entre deux rendus, vous pouvez remplacer ces enveloppes de blocs sur place au lieu de reconstruire `innerHTML`.
- **Les calques** : superposer un SVG positionné en absolu sur chaque `.pt-page` pour les curseurs, les sélections ou les grilles de ligne de base.
- **Les liens** : les mots d’un lien Markdown sont enveloppés dans ``, qui prend la couleur du texte et n’est pas souligné ; voir [Format du document › Liens](https://postext.dev/fr/docs/document-format-inline.md#liens). Dans une visionneuse de type éditeur, interceptez les clics sur les `a[href]` qui ne commencent pas par `#` et ouvrez-les dans un nouvel onglet (les ancres de `:ref` renvoient à l’intérieur du document).
- **Les images à encre unique** : avec `diagramStyle.singleInk` activé, les `![]()
` SVG reçoivent un filtre CSS, sauf si vous passez `singleInk: false` pour des URL déjà recolorées ; voir [Encre unique sur le canvas et en HTML](https://postext.dev/fr/docs/configuration-resources.md#encre-unique-sur-le-canvas-et-en-html).
Le composant `HtmlPreview` du Sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) met tout cela en œuvre sur la même API que ci-dessus et peut servir de référence. Il fait aussi passer chaque construction par un worker de mise en page partagé (voir [Exécuter la mise en page dans un Web Worker](https://postext.dev/fr/docs/configuration-programmatic-usage.md#mise-en-page-dans-un-web-worker)), si bien que les modifications en direct et les redimensionnements ne bloquent jamais le thread principal : remplacez l’appel direct `buildDocument(...)` de l’extrait ci-dessus par `layoutWorker.build(...)` quand vous êtes prêt à sortir la mise en page du thread principal.
### En quoi la sortie HTML diffère du canvas et du PDF
`renderToHtml` place chaque ligne, chaque figure et chaque élément de maquette exactement là où les placent le canvas et le PDF, mais peint moins de choses autour :
| Fonction | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| Fond de page | Blanc, avec `page.backgroundColor` sur le format rogné et le fond perdu. | **Transparent**, sauf si vous passez `background` ou définissez `page.backgroundColor` (qui remplit alors toute la boîte de la page, zone de repères comprise). | Blanc, avec `page.backgroundColor` sur le format rogné et le fond perdu. |
| Grille de ligne de base (`page.baselineGrid`) | Dessinée | Non dessinée | Dessinée |
| Filet entre colonnes (`layout.columnRule`) | Dessiné | Non dessiné | Dessiné |
| Traits de coupe (`page.cutLines`) | Dessinés | Non dessinés ; la boîte de la page inclut toujours la zone de repères autour du format rogné. | Dessinés |
| Page en négatif | Option `pageNegative` | Non disponible | Option `pageNegative` |
| Texte | Pixels | Texte sélectionnable dans des éléments positionnés en absolu, composé dans les familles de polices CSS : la page doit charger les mêmes fontes. | Polices incorporées fournies par votre `fontProvider` ; texte sélectionnable, consultable par recherche et balisé. |
| Texte vertical (`layout.writingMode: 'vertical-rl'`) | Caractères peints une cellule à la fois, remis debout ; formes verticales obtenues par une fonte jumelle (`loadVerticalAlternates`). | Le flux tient dans une boîte tournée d’un quart de tour ; chaque ligne est remise debout et composée avec `writing-mode: vertical-rl`, si bien que le navigateur prend les formes verticales et redresse les caractères ; les nombres courts sont en `text-combine-upright: all` ; un tiret, des points de suspension, un point médian ou un tiret ondulé occupent une boîte de leur cellule (le navigateur les ferait avancer de leur largeur horizontale), un tiret étant étiré pour la remplir selon `flow.dashAdvances`. | Caractères debout grâce à un jumeau `Identity-V` de chaque police ; voir [Texte vertical dans le PDF](https://postext.dev/fr/docs/configuration-pdf-output.md#texte-vertical-dans-le-pdf). |
| Images | `registerResourceImage` | L’option `resourceImageUrl(fileId)` ; sans elle, une boîte grise en guise d’image. | L’option `resourceBytes(fileId)`. |
| Formules | Tracés vectoriels | `