# Uso programático: HTML, Folio y EPUB
> El libro compuesto en una página web, como libro en 3D con postext-folio y como EPUB 3 de maquetación fija o fluida con postext-epub
- Versión HTML: https://postext.dev/es/docs/configuration-html-folio-epub
- Última actualización: 2026-10-16
- Tiempo de lectura: 18 min
- Otros idiomas: [en](https://postext.dev/en/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), [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)
## En pocas palabras
Esta página es para quienes escriben código y quieren mostrar un libro en una pantalla. La primera sección coloca las páginas dentro de una página web y explica en qué se diferencia esa vista del canvas y del PDF. La segunda muestra el libro en 3D, abierto sobre una mesa, con hojas que el lector pasa. La última sección crea un libro electrónico EPUB, con páginas fijas o con un texto que se adapta a la pantalla, y comprueba el archivo.
## Integrar el visor HTML
El visor HTML es el renderizador de Postext orientado a pantalla. En lugar de rasterizar páginas a un bitmap emite nodos DOM posicionados absolutamente cuya geometría está generada por el mismo pipeline que produce la salida impresa. Es la opción adecuada cuando quieres tipografía legible, seleccionable y consciente del resize en el navegador — una app de lectura, una previsualización dentro de un producto o una superficie de documentación embebida — sin arrastrar contigo un visor PDF.
Las piezas clave de la API pública:
- **`buildDocument(content, config, cache?)`** — ejecuta el pipeline completo de composición y devuelve un `VDTDocument`.
- **`renderToHtmlIndexed(doc, options)`** — convierte el VDT en una única cadena HTML más un desglose por página y por bloque. El desglose permite parchear el DOM de forma barata cuando solo han cambiado algunos bloques entre renders.
- **`resolveHtmlViewerConfig(partial)`** — completa los valores por defecto del visor HTML (`maxCharsPerLine`, `columnGap`, `optimalLineBreaking`).
- **`buildFontString` + `measureGlyphWidth` + `dimensionToPx`** — primitivas de medida usadas para derivar un ancho de columna real en píxeles a partir de un objetivo en caracteres.
- **`createMeasurementCache` / `clearMeasurementCache`** — cachés enchufables para reutilizar medidas entre recomposiciones.
- **`prepareFonts` / `buildDocumentWithFonts` / `watchFonts` / `onFontsChanged`** — cargan las caras del documento antes de componer y vuelven a componer cuando llegan caras nuevas (ver [Cargar las fuentes antes de componer](https://postext.dev/es/docs/configuration-programmatic-usage.md#cargar-las-fuentes-antes-de-componer)).
### Ejemplo en vivo: una cadena HTML
El recorrido completo en JavaScript plano, antes de la integración con React de más abajo: construir el documento, pasar el `VDTDocument` a `renderToHtml` y volcar la cadena en un contenedor. `mode: 'single'` apila las páginas en vertical; `background` les da color, porque por defecto las páginas son transparentes. El pen también imprime el marcado generado, para que veas las líneas posicionadas de forma absoluta que emite el renderizador: el navegador las pinta, pero nunca las recompone.
> **Ejemplo ejecutable: Postext · renderizar un documento a HTML** — Compone un documento markdown con postext y renderízalo a una cadena HTML. ([código](https://github.com/drnachio/postext/tree/main/docs/examples/render-html))
### Integración mínima
El fragmento siguiente es la integración útil más corta: construye el documento al tamaño actual del viewport, lo renderiza en un contenedor y recompone al redimensionar.
```tsx
import { useEffect, useRef } from 'react';
import {
buildDocument,
renderToHtmlIndexed,
resolveHtmlViewerConfig,
buildFontString,
measureGlyphWidth,
dimensionToPx,
createMeasurementCache,
watchFonts,
onFontsChanged,
} from 'postext';
import type { PostextConfig, MeasurementCache } from 'postext';
// DPI adecuado para pantalla: a 144 DPI un tamaño de cuerpo de 8pt resuelve a 16 px.
const HTML_DPI = 144;
const PADDING_PX = 24;
// Muestra de prosa usada para medir el ancho objetivo de columna. Las fuentes
// proporcionales hacen poco fiable "N × ancho medio", así que medimos una
// cadena representativa.
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);
// Mide el ancho *real* de columna para N caracteres de prosa del cuerpo.
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 {
// Encaja tantas columnas como se pueda al ancho objetivo.
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);
// El modo single usa una página muy alta; el modo multi usa la altura
// del viewport, de modo que cada "página" VDT se convierte en una columna.
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);
// Vuelve a medir cuando cargan las web fonts para que los anchos de glifo no
// queden tomados a partir de las fuentes de reserva.
const stopWatching = watchFonts();
const off = onFontsChanged(() => relayout());
return () => {
ro.disconnect();
off();
stopWatching();
};
}, [markdown, config, mode]);
return ;
}
```
Algunas notas sobre lo que hace el ejemplo:
- **Se mide la columna, no se aproxima.** Como `maxCharsPerLine` es un *objetivo* expresado en caracteres, el ancho real en píxeles depende de la fuente del cuerpo. `measureGlyphWidth` da una medida real sobre la fuente elegida, manteniendo la medida consistente al cambiar de fuente.
- **Se reescribe la página.** El visor HTML trata cada "página" del VDT como una columna en pantalla. El ejemplo sobrescribe `page.width` con el ancho medido de columna, pone los márgenes a cero (el padding vive fuera de la página, en el `.pt-doc` envolvente) y usa `HTML_DPI = 144` para que `8pt` de cuerpo resuelva a `16px`.
- **Atento a la carga de fuentes.** `watchFonts` escucha `document.fonts` y, una vez por fotograma, descarta lo medido en las familias cuyas caras han llegado; `onFontsChanged` vuelve a componer entonces la columna. Sin recomponer, el primer render usa métricas de la fuente de reserva y se produce un salto cuando llega la real.
- **Se reutiliza la caché de medidas.** Crear la caché una sola vez por componente hace que los resizes y los cambios de escala de fuente reutilicen medidas del render anterior en lugar de volver a medir cada párrafo.
### Siguiente paso
El ejemplo de arriba es deliberadamente plano. Las integraciones en producción añaden habitualmente:
- **Aislamiento con Shadow DOM** — renderiza en `host.attachShadow({ mode: 'open' })` para que nada del documento externo filtre CSS al visor.
- **Parcheo incremental** — `renderToHtmlIndexed` devuelve `pages[i].blocks`, cada uno con un `id` estable y el HTML externo del bloque. Cuando solo unos cuantos bloques difieren entre dos renders puedes reemplazar esos envoltorios en el sitio en lugar de reconstruir `innerHTML`.
- **Superposiciones** — apila un SVG absoluto sobre cada `.pt-page` para cursores, selecciones o la rejilla base.
- **Enlaces** — las palabras de un enlace Markdown se envuelven en ``, que toma el color del texto y no se subraya; consulta [Formato del documento › Enlaces](https://postext.dev/es/docs/document-format-inline.md#enlaces). En un visor que funcione como editor, intercepta los clics en los `a[href]` que no empiecen por `#` y ábrelos en una pestaña nueva (las anclas de `:ref` enlazan dentro del documento).
- **Imágenes a una sola tinta** — con `diagramStyle.singleInk` activo, los `![]()
` SVG llevan un filtro CSS, salvo que pases `singleInk: false` porque las URL ya están recoloreadas; consulta [Tinta única en canvas y en HTML](https://postext.dev/es/docs/configuration-resources.md#tinta-única-en-canvas-y-en-html).
El componente `HtmlPreview` del sandbox (`packages/postext-sandbox/src/viewport/HtmlPreview/index.tsx`) implementa todo esto sobre la misma API que se muestra aquí y puede servirte de referencia. Además enruta cada build a través de un worker de layout compartido (consulta [Ejecutar la composición en un Web Worker](https://postext.dev/es/docs/configuration-programmatic-usage.md#ejecutar-la-composición-en-un-web-worker)) para que las ediciones en vivo y los resizes nunca bloqueen el hilo principal — sustituye la llamada directa `buildDocument(...)` del snippet anterior por `layoutWorker.build(...)` cuando quieras mover la composición fuera del hilo principal.
### En qué se diferencia la salida HTML del canvas y del PDF
`renderToHtml` coloca cada línea, figura y elemento de diseño exactamente donde lo hacen el canvas y el PDF, pero pinta menos a su alrededor:
| Elemento | Canvas (`renderPage`) | HTML (`renderToHtml`) | PDF (`renderToPdf`) |
| --- | --- | --- | --- |
| Fondo de página | Blanco, con `page.backgroundColor` sobre la caja de corte y el sangrado. | **Transparente**, salvo que pases `background` o fijes `page.backgroundColor` (que entonces rellena toda la caja de la página, incluida la zona de las marcas de corte). | Blanco, con `page.backgroundColor` sobre la caja de corte y el sangrado. |
| Rejilla de línea base (`page.baselineGrid`) | Se dibuja | No se dibuja | Se dibuja |
| Filete entre columnas (`layout.columnRule`) | Se dibuja | No se dibuja | Se dibuja |
| Marcas de corte (`page.cutLines`) | Se dibujan | No se dibujan; la caja de la página sigue incluyendo el margen exterior de las marcas. | Se dibujan |
| Negativo de página | Opción `pageNegative` | No disponible | Opción `pageNegative` |
| Texto | Píxeles | Texto seleccionable en elementos con posición absoluta, compuesto en las familias CSS: la página debe cargar las mismas caras. | Fuentes incrustadas desde tu `fontProvider`; seleccionable, buscable y etiquetado. |
| Texto vertical (`layout.writingMode: 'vertical-rl'`) | Caracteres pintados casilla a casilla y enderezados; formas verticales mediante una fuente gemela (`loadVerticalAlternates`). | El flujo en una caja girada un cuarto de vuelta; cada línea enderezada y compuesta con `writing-mode: vertical-rl`, así que el navegador toma las formas verticales y pone los caracteres de pie; los números cortos, en `text-combine-upright: all`; una raya, unos puntos suspensivos, un punto medio o una tilde de onda, en una caja del largo de su celda (el navegador los haría avanzar su ancho horizontal), y la raya estirada hasta llenarla según `flow.dashAdvances`. | Caracteres de pie mediante una gemela `Identity-V` de cada fuente; ver [Texto vertical en el PDF](https://postext.dev/es/docs/configuration-pdf-output.md#texto-vertical-en-el-pdf). |
| Imágenes | `registerResourceImage` | La opción `resourceImageUrl(fileId)`; sin ella, una caja gris provisional. | La opción `resourceBytes(fileId)`. |
| Fórmulas | Trazos vectoriales | `