Converting MS Office Files with Custom Fonts to PDF

PSPDFKit Processor has been deprecated and replaced by PSPDFKit Document Engine. All PSPDFKit Processor licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

To convert Office files with custom fonts to PDF, provide the fonts to PSPDFKit Processor’s conversion engine. To do so, expose a directory of fonts from the host machine to the Docker container by adding the following to your docker-compose.yml file:

version: "3.7"

services:
  processor:
    image: pspdfkit/processor
    ports:
      - "5000:5000"
    volumes:
      - /path/to/font/directory/on/host/machine:/custom-fonts

Microsoft Core Fonts

Microsoft core fonts are widely used on the web and in PDF files. Including them as custom fonts in your project improves the conversion and rendering fidelity for documents that use them. These fonts aren’t included in PSPDFKit because Microsoft no longer offers these files directly, and the license prohibits redistribution. To use these fonts in your project, download them from SourceForge and add them to PSPDFKit as a custom font.

Font Substitutions

Sometimes, PSPDFKit Processor doesn’t have access to the font required to perform a conversion or render an annotation either as part of the default container fonts or in the fonts directory mounted at /custom-fonts, as described above.

In these cases, it’s necessary to specify alternative fonts that can be used in place of the unavailable fonts. To specify these substitute fonts, create a font-substitutions.json file and mount it on the PSPDFKit Processor container:

processor:
  volumes:
    - /path-to-font-substitutions-json-on-host:/font-substitutions.json

The schema for the font-substitutions.json file is as follows (TypeScript is used for this definition):

type FontSubstitutions = {
	fontSubstitutions: FontSubstitution[];
};

type FontSubstitution = {
	// Please note that font family name replacements are made based upon pattern matching,
	// allowing for a font family name to be replaced with a different name.
	// Patterns are matched using the following rules:
	//  - `*` matches multiple characters
	//  - `?` matches a single character
	pattern: string;

	// The font that should be used as a replacement
	// when any font matching the given pattern is unavailable.
	target: string;
};

Example font-substitions.json file:

{
	"fontSubstitutions": [
		{
			"pattern": "Roboto-*",
			"target": "Courier New"
		},
		{
			"pattern": "Calibri",
			"target": "Caladea"
		}
	]
}

Notes on Font Substitutions

Case-Insensitive — The pattern and target names are case-insensitive.

Ordering Matters — As names could match multiple patterns, it’s important to note that the order of substitutions in the fontSubstitutions array matters. Specifically, the font substitutions are processed from top down.

For example, consider the following list of font substitutions:

{
  "fontSubstitutions": [
    {
      "pattern": "Roboto-*",
      "target": "Courier New"
    },
    {
      "pattern": "Roboto-Medium",
      "target": "Menlo"
    },
    {
      "pattern": "Roboto-Medium*",
      "target": "Consolas"
    }
  ]
}

If PSPDFKit Processor has to convert a document with Roboto-MediumItalic font and the Roboto-MediumItalic font is unavailable, it’ll use the Courier New font as a substitute instead (provided Courier New is available), since Roboto-* is the first match on the list.

The font substitutions specified using font-substitutions.json will be applied where necessary (conversions, rendering annotations, etc.) in the context of every document PSPDFKit Processor processes.