Guidance on Font replacement when converting to PDF

GroupDocs.Conversion Product Family
, , ,
1

We are currently using GroupDocs.Conversion version 26.1 to convert docx (and many other types) to PDF files. An issue we’re encountering is that if a symbol on the source document does not exist in a font in the executing (Linux docker container) environment, the output PDF renders that symbol as a box.

When searching this forum, the common refrain seems to be that the environment needs to have the fonts for the source document installed in order to render them properly in the output PDF file.

In our application, we expect to be ingesting document files with an unknown combination of fonts and symbols. It is my current understanding that when running conversion, it will try to do Font replacement based on the WordProcessingLoadOptions properties, and the fonts available on the environment that the code is executing on.

Is there any mechanism for which we can be notified of a warning or failure during font replacement during conversion when these symbols are failing to find a match? Or do you have any guidance or recommendations on handling files of varied fonts and symbols?

We’ve currently tried to add a trace logger to the created ConverterSettings, but there did not seem to be any feedback with regards to fonts in the output.

2

Hi @tonyMilyli

Thanks for your question about font substitution handling!

First, a quick note about font availability: yes, the fonts referenced in your source document need to be installed in the system font folders (or in custom font folders that you configure). If a
font isn’t available, the conversion engine will substitute it with an available one.

We’ve been working on a new feature to make these substitutions more visible: a new event that fires whenever a font substitution occurs. This is coming in GroupDocs.Conversion for .NET 26.6 at
the end of this month.

Here’s what the new event will look like:

using GroupDocs.Conversion;
using GroupDocs.Conversion.Contracts;
using GroupDocs.Conversion.Options.Convert;

var events = new ConversionEvents
{
    OnFontSubstituted = context =>
    {
        // Prefer the typed names when present; otherwise use the verbatim Reason.
        var detail = context.OriginalFontName != null
            ? $"{context.OriginalFontName} -> {context.SubstituteFontName}"
            : context.Reason;
        Console.WriteLine($"Font substituted in '{context.SourceFileName}': {detail}");
    }
};

using var converter = new Converter("source.docx", () => new ConverterSettings(), () => events);
converter.Convert("output.pdf", new PdfConvertOptions());

The event provides:

  • OriginalFontName - the font that was referenced but unavailable
  • SubstituteFontName - the font that was used instead
  • Reason - a descriptive message about what happened
  • SourceFileName - helps identify which document had the substitution

We’ll include full details in the release notes when 26.6 ships at the end of this month.

1 Like