DOCX to PDF: fonts, page breaks, and fidelity

Fonts affect character widths, line breaks, table heights, and page count. A conversion can preserve all the text and still paginate differently if the selected fonts differ from the fonts used in Word.

Make font selection explicit

The exporter searches installed fonts by default. For repeatable deployments, supply the fonts you need and disable system font discovery with useSystemFonts: false.

The fonts option provides font sources before installed and packaged sources. fallbackFonts adds sources after the packaged fonts. The exporter also reads embedded fonts before choosing a generic substitute for an unresolved family.

Use the font-source types documented by Core's export interface for your package version. Keep font files and package versions fixed when comparing output across machines.

Inspect the selected fonts

import { readFile } from 'node:fs/promises';
import { exportPdf } from '@docx-editor.dev/docx-to-pdf';

const result = await exportPdf(await readFile('document.docx'), {
  useSystemFonts: false,
  fidelityPolicy: 'strict',
});

console.dir(result.fontResolution, { depth: null });
console.dir(result.diagnostics, { depth: null });

Packaged metric-compatible fonts can stand in for common Word families. For example, the example font report records Carlito for Calibri. A metric-compatible substitute is not the original font and does not establish a visual match to Word.

Generic substitution can change line breaks and page count. Strict PDF export rejects it with a font-substitution diagnostic. Best-effort export can return the substituted output and its diagnostics. Core's separate fontPolicy controls font substitution behavior.

Choose a fidelity policy

Strict mode detects known problems. It does not compare the output with Microsoft Word or certify pixel-identical rendering. Your document corpus is the acceptance test.

Build a Word reference set

1. Collect representative documents and every production template. Include difficult tables, section changes, footnotes, equations, and comments.
2. Export reference PDFs from desktop Word. Record the Word version, source document, fonts, and export settings.
3. Convert the same DOCX files with fixed package and font versions.
4. Compare page count and page boundaries first. Then compare line endings, table borders, images, headers, and footers.
5. Review differences page by page, and preserve regressions as fixtures.

Use both visual review and text extraction. An image can look right while text selection or extraction is wrong. Re-run your reference set before updating the converter or its fonts.

Know the current limits

The exporter supports searchable multilingual text, static TrueType and CFF fonts, table text and borders, PNG and JPEG images, headers and footers, notes, textboxes, structured equations, links, and native comments.

Charts, rotated table-cell text, advanced image effects, some revision presentation, and non-PNG/JPEG media produce diagnostics. The writer rejects variable fonts, missing glyphs, prohibited font embedding, fonts that prohibit subsetting, and unsupported font containers.

Tagged PDF, PDF/A, encryption, interactive forms, and reusable export sessions are not currently supported. See the package reference for the full support and error details.