# Programmatische Nutzung: HTML, Folio und EPUB
> Das gesetzte Buch in einer Webseite, als 3D-Buch mit postext-folio und als EPUB 3 mit festem Layout oder umfließend mit postext-epub
- HTML-Fassung: https://postext.dev/de/docs/configuration-html-folio-epub
- Zuletzt aktualisiert: 2026-10-16
- Lesezeit: 16 min
- Andere Sprachen: [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), [fr](https://postext.dev/fr/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)
## Kurz gesagt
Diese Seite richtet sich an Menschen, die Code schreiben und ein Buch auf einem Bildschirm zeigen wollen. Der erste Abschnitt bettet die Seiten in eine Webseite ein und erklärt, worin sich diese Ansicht vom Canvas und vom PDF unterscheidet. Der zweite zeigt das Buch in 3D, aufgeschlagen auf einem Tisch, mit Seiten, die der Leser umblättert. Der letzte Abschnitt erstellt ein E-Book im Format EPUB, mit festen Seiten oder mit Text, der sich dem Bildschirm anpasst, und prüft die Datei.
## Den HTML-Betrachter einbinden
Der HTML-Betrachter ist der Renderer von Postext, der für den Bildschirm gedacht ist. Statt Seiten zu einer Bitmap zu rastern, gibt er absolut positionierte DOM-Knoten aus, deren Geometrie aus derselben Pipeline stammt, die auch die Druckausgabe erzeugt. Damit ist er die richtige Wahl, wenn Sie im Browser lesbare, auswählbare und auf Größenänderungen reagierende Typografie wollen – eine Lese-App, eine Vorschau im Produkt oder eine eingebettete Dokumentationsoberfläche –, ohne einen PDF-Betrachter einzubinden.
Die wichtigsten Teile der öffentlichen API:
- **`buildDocument(content, config, cache?)`** – durchläuft die gesamte Layout-Pipeline und gibt ein `VDTDocument` zurück.
- **`renderToHtmlIndexed(doc, options)`** – macht aus dem VDT einen einzigen HTML-String sowie eine Aufschlüsselung pro Seite und pro Block. Die Aufschlüsselung erlaubt günstige DOM-Aktualisierungen, wenn sich zwischen zwei Renderings nur wenige Blöcke geändert haben.
- **`resolveHtmlViewerConfig(partial)`** – ergänzt die Standardwerte des HTML-Betrachters (`maxCharsPerLine`, `columnGap`, `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`** – Messgrundfunktionen, mit denen sich aus einer Zielzahl von Zeichen eine tatsächliche Spaltenbreite in Pixeln ableiten lässt.
- **`createMeasurementCache` / `clearMeasurementCache`** – austauschbare Caches, mit denen Sie Messungen über Neuaufbauten des Layouts hinweg wiederverwenden.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`** – laden die Schnitte des Dokuments vor dem Layout und setzen erneut, wenn Schnitte eintreffen (siehe [Schriften vor dem Layout laden](https://postext.dev/de/docs/configuration-programmatic-usage.md#schriften-vor-dem-layout-laden)).
### Live-Beispiel: ein HTML-String
Der ganze Ablauf in reinem JavaScript, vor der React-Integration weiter unten: das Dokument setzen, das `VDTDocument` an `renderToHtml` übergeben und den String in einen Container einfügen. `mode: 'single'` stapelt die Seiten untereinander; `background` gibt ihnen eine Farbe, da Seiten standardmäßig transparent sind. Der Pen gibt außerdem das erzeugte Markup aus, sodass Sie die absolut positionierten Zeilen sehen, die der Renderer ausgibt – der Browser zeichnet sie, bricht sie aber nie neu um.
> **Ausführbares Beispiel: Postext · ein Dokument als HTML rendern** — Ein Markdown-Dokument mit postext setzen und als HTML-String rendern. ([Quelltext](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### Minimale Einbindung
Das folgende Snippet ist die kürzeste brauchbare Integration: Es setzt das Dokument in der aktuellen Größe der Ansicht, rendert es in einen Container und wiederholt das bei Größenänderungen.
```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 ;
}
```
Einige Anmerkungen dazu, was dieses Beispiel tut:
- **Die Spalte messen, nicht schätzen.** Da `maxCharsPerLine` ein *Zielwert* in Zeichen ist, hängt die tatsächliche Breite in Pixeln von der Grundschrift ab. `measureGlyphWidth` liefert eine echte Messung mit der gewählten Schrift, sodass die Satzbreite auch beim Wechsel der Schrift stimmig bleibt.
- **Die Seite umschreiben.** Der HTML-Betrachter behandelt jede „Seite“ des VDT als eine Spalte auf dem Bildschirm. Das Beispiel überschreibt `page.width` mit der gemessenen Spaltenbreite, setzt die Ränder auf null (der Innenabstand liegt außerhalb der Seite im umhüllenden div `.pt-doc`) und verwendet `HTML_DPI = 144`, sodass Grundtext in `8pt` zu `16px` aufgelöst wird.
- **Auf das Laden von Schriften achten.** `watchFonts` beobachtet `document.fonts` und verwirft einmal pro Frame, was in den Familien gemessen wurde, deren Schnitte eingetroffen sind; `onFontsChanged` setzt die Spalte dann erneut. Ohne diesen Neuaufbau verwendet das erste Rendering die Metriken einer Ersatzschrift und springt, wenn die echte Schrift eintrifft.
- **Den Mess-Cache wiederverwenden.** Wird der Cache einmal pro Komponente erzeugt, verwenden Größenänderungen und Änderungen des Schriftmaßstabs die Messungen des vorherigen Renderings wieder, statt jeden Absatz neu zu messen.
### Weiterführende Schritte
Das Beispiel oben ist bewusst flach gehalten. Produktive Integrationen ergänzen meist:
- **Isolation per Shadow DOM** – rendern Sie in `host.attachShadow({ mode: 'open' })`, damit kein CSS der umgebenden Seite in den Betrachter durchsickern kann.
- **Inkrementelle Aktualisierung** – `renderToHtmlIndexed` gibt `pages[i].blocks` zurück, jeweils mit einer stabilen `id` und dem äußeren HTML des Blocks. Unterscheiden sich zwischen zwei Renderings nur wenige Blöcke, können Sie diese Block-Hüllen an Ort und Stelle ersetzen, statt `innerHTML` neu aufzubauen.
- **Überlagerungen** – ein absolut positioniertes SVG über jeder `.pt-page` für Cursor, Auswahlen oder Grundlinienraster.
- **Links** – die Wörter eines Markdown-Links werden in `` gehüllt, das die Textfarbe übernimmt und nicht unterstrichen ist; siehe [Dokumentformat › Links](https://postext.dev/de/docs/document-format-inline.md#links). Fangen Sie in einem editorähnlichen Betrachter Klicks auf `a[href]` ab, die nicht mit `#` beginnen, und öffnen Sie sie in einem neuen Tab (Anker von `:ref` verlinken innerhalb des Dokuments).
- **Einfarbige Bilder** – mit eingeschaltetem `diagramStyle.singleInk` erhalten SVG-Elemente `![]()
` einen CSS-Filter, sofern Sie nicht `singleInk: false` für URLs übergeben, die bereits umgefärbt sind; siehe [Einfarbmodus auf dem Canvas und in HTML](https://postext.dev/de/docs/configuration-resources.md#einfarbmodus-auf-dem-canvas-und-in-html).
Die Komponente `HtmlPreview` der Sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) setzt all das auf derselben hier gezeigten API um und kann als Referenz dienen. Sie leitet außerdem jeden Build über einen gemeinsamen Layout-Worker (siehe [Layout in einem Web Worker ausführen](https://postext.dev/de/docs/configuration-programmatic-usage.md#layout-in-einem-web-worker-ausführen)), sodass Live-Bearbeitungen und Größenänderungen den Haupt-Thread nie blockieren – ersetzen Sie den direkten Aufruf `buildDocument(...)` im Snippet oben durch `layoutWorker.build(...)`, sobald Sie das Layout aus dem Haupt-Thread verlagern wollen.
### Wie sich die HTML-Ausgabe von Canvas und PDF unterscheidet
`renderToHtml` setzt jede Zeile, jede Abbildung und jedes Gestaltungselement genau dorthin, wo auch Canvas und PDF sie setzen, zeichnet aber weniger darum herum:
| Merkmal | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| Seitenhintergrund | Weiß, mit `page.backgroundColor` über Endformat und Anschnitt. | **Transparent**, sofern Sie nicht `background` übergeben oder `page.backgroundColor` setzen (das dann den ganzen Seitenkasten einschließlich Infobereich füllt). | Weiß, mit `page.backgroundColor` über Endformat und Anschnitt. |
| Grundlinienraster (`page.baselineGrid`) | Gezeichnet | Nicht gezeichnet | Gezeichnet |
| Spaltenlinie (`layout.columnRule`) | Gezeichnet | Nicht gezeichnet | Gezeichnet |
| Schnittmarken (`page.cutLines`) | Gezeichnet | Nicht gezeichnet; der Seitenkasten umfasst aber weiterhin den Infobereich um das Endformat. | Gezeichnet |
| Seitennegativ | Option `pageNegative` | Nicht verfügbar | Option `pageNegative` |
| Text | Pixel | Auswählbarer Text in absolut positionierten Elementen, gesetzt in den CSS-Schriftfamilien: Die Seite muss dieselben Schnitte laden. | Eingebettete Schriften aus Ihrem `fontProvider`; auswählbar, durchsuchbar und getaggt. |
| Vertikaler Text (`layout.writingMode: 'vertical-rl'`) | Zeichen werden Zelle für Zelle gezeichnet und wieder aufgerichtet; vertikale Formen über einen Zwillingsschnitt (`loadVerticalAlternates`). | Der Fluss in einem Kasten, um eine Vierteldrehung gedreht; jede Zeile wieder aufgerichtet und mit `writing-mode: vertical-rl` gesetzt, sodass der Browser die vertikalen Formen nimmt und die Zeichen aufrichtet; kurze Zahlen in `text-combine-upright: all`; ein Strich, eine Auslassung, ein Mittelpunkt oder ein Wellenstrich in einem Kasten seiner Zelle (der Browser würde ihn um seine horizontale Breite vorrücken), ein Strich auf die Zellenlänge gestreckt durch `flow.dashAdvances`. | Aufrechte Zeichen über einen Zwilling jeder Schrift mit `Identity-V`; siehe [Vertikaler Text im PDF](https://postext.dev/de/docs/configuration-pdf-output.md#vertikaler-text-im-pdf). |
| Bilder | `registerResourceImage` | Die Option `resourceImageUrl(fileId)`; ohne sie ein grauer Platzhalterkasten. | Die Option `resourceBytes(fileId)`. |
| Formeln | Vektorpfade | Inline-`