Fonts and complex scripts
DocWright lays text out with the real font files, just as Word does, so line breaks and page breaks match. It needs the fonts your documents use. This page covers where it looks for them, what happens when one is missing, and how complex scripts are shaped.
Where fonts come from
DocWright searches, in order:
the folders in
ConvertOptions.FontDirectories;the operating system's font folders, recursively:
Platform Folders Windows %WINDIR%\Fonts,%LOCALAPPDATA%\Microsoft\Windows\FontsmacOS /System/Library/Fonts,/Library/Fonts,~/Library/FontsLinux /usr/share/fonts,/usr/local/share/fonts,~/.fontsits bundled open-licensed faces: Carlito (metric-compatible with Calibri), Caladea (Cambria) and Liberation (Arial, Times New Roman, Courier New), plus Noto Naskh Arabic for Arabic text and stand-ins for Symbol and Wingdings. A machine with no fonts at all still produces well-laid-out output.
Fonts the document embeds come before all three. They belong to the document, so they are always used.
The same output on every machine
A server, a container or a golden-file test often needs output that doesn't change with what a machine has installed. Turn off the operating-system folders and ship the fonts you depend on:
using DocWright;
using DocWright.Core.Rendering;
using DocWright.Dom;
var confined = new ConvertOptions
{
IncludeSystemFontDirectories = false, // ignore whatever this machine has installed
};
confined.FontDirectories.Add("fonts"); // the fonts you ship with your application
using (FileStream input = File.OpenRead("missing-font.docx"))
using (WordDocument document = converter.Load(input))
{
LaidOutConversion laidOut = converter.Layout(document, confined);
IEnumerable<IGrouping<string, GlyphRun>> byFace = laidOut.Document.Pages[0].Primitives
.OfType<GlyphRun>()
.GroupBy(run => laidOut.Fonts.ResolveRun(run).FamilyName); // the face each run is drawn with
foreach (IGrouping<string, GlyphRun> face in byFace)
{
Console.WriteLine($"{face.Key,-18} {string.Concat(face.Select(run => run.Text))}");
}
}
Output. This machine has Calibri installed, but the second paragraph still gets the bundled Carlito, and the missing family is substituted from inside the set:
Liberation Serif Set in a font that is not installed.
Carlito And a paragraph in Calibri, which is.
| Setting | Default | Effect |
|---|---|---|
IncludeSystemFontDirectories |
true |
false skips the operating-system folders. |
IncludeBundledMetricFonts |
true |
false skips the bundled Carlito, Caladea, Liberation and Noto Naskh Arabic faces and the Symbol and Wingdings stand-ins. |
Convert, ConvertAsync, ConvertToImages and Layout all honour both settings. ConvertPdfToImages ignores them, as it ignores FontDirectories. A family missing from your set is substituted and reported as usual. A bundled face counts as a substitution too, so FailOnFontSubstitution refuses Carlito standing in for Calibri. With both settings off, no FontDirectories and no embedded fonts, the conversion throws FontResolutionException.
When a font is missing
using DocWright;
using DocWright.Core.Diagnostics;
using DocWright.Core.Text;
using DocWright.Fonts;
var diagnostics = new CollectingConversionDiagnostics();
var options = new ConvertOptions
{
Diagnostics = diagnostics,
WarnOnFontSubstitution = true, // report DXP3004 for each substitution
};
options.FontDirectories.Add("fonts"); // your own fonts, searched before the system's
options.FontFallbackChain.Add("Arial"); // tried, in order, for a family that is missing
options.ScriptFallbackFonts[UnicodeScript.Arabic] = [new FontKey("Arial")];
using (FileStream input = File.OpenRead("missing-font.docx"))
using (FileStream output = File.Create("missing-font.pdf"))
{
converter.Convert(input, output, options);
}
foreach (ConversionDiagnostic d in diagnostics.Snapshot())
{
Console.WriteLine($"{d.Code}: {d.Message}");
}
Output
DXP3001: Preflight substitution: 'Fontastic Grotesk' -> 'Arial' (outcome UltimateFallback, distance 0).
DXP3004: Font substitution summary: 1 run(s) affected across 1 family/families; worst-case PANOSE distance 0; includes ultimate-fallback substitutions.
DXP3001: Font fallback: 'Fontastic Grotesk' -> 'Arial' (outcome UltimateFallback, distance 0).

Substitution is silent unless you ask to hear about it:
| Setting | Effect |
|---|---|
WarnOnFontSubstitution = true |
Reports DXP3004, a summary of every substitution, to your diagnostics sink. |
FailOnFontSubstitution = true |
Throws FontResolutionException instead of substituting. |
FontFallbackChain |
Families to try, in order, for any missing family. |
ScriptFallbackFonts[script] |
Families to try for one script, such as Arabic or Han, ahead of the general chain. |
Important
Servers and containers: install the fonts your documents use. Substitutes are metric-compatible where possible, but only the real font guarantees the same line breaks as Word. Copy the font files into your image and add the folder to FontDirectories.
The font cache
Indexing the installed fonts takes about a second, so each DocWrightConverter caches its font engine, one per combination of font settings, up to eight. That is why an application should keep one converter. A host that changes fonts per tenant can call converter.ClearFontCache() to release the memory. It is safe while conversions are running, and it never changes the output.
Complex scripts
Arabic always has a face. Arabic text whose font has no Arabic glyphs is set in the bundled Noto Naskh Arabic (Regular and Bold) and shaped there, so a container with no fonts draws joined Arabic instead of empty boxes. This happens, for example, where Arial resolves to Liberation Sans, which has no Arabic. A font that has Arabic keeps its text. A family you name in ScriptFallbackFonts[UnicodeScript.Arabic] comes first. The substitution is reported once as DXP3001. Noto Naskh Arabic is not metric-compatible with Microsoft's Arabic faces: its letters are wider and its lines taller, so ship the document's own Arabic fonts where line breaks must match Word.

Arabic and Hebrew are shaped by the built-in engine: joining forms, ligatures such as lam-alef, and mark positioning. No setup is needed.

Indic scripts (Devanagari, Bengali, Tamil…), Thai, Khmer and other complex scripts need a shaper. Without one, each character is drawn on its own: vowel signs land in the wrong place and conjuncts don't form. Install DocWright.ComplexText and set the HarfBuzz shaper:
dotnet add package DocWright.ComplexText
using DocWright;
using DocWright.ComplexText;
var shaped = new ConvertOptions { TextShaper = new HarfBuzzTextShaper() };
using (FileStream input = File.OpenRead("hindi.docx"))
using (FileStream output = File.Create("hindi-harfbuzz.pdf"))
{
converter.Convert(input, output, shaped);
}
Built-in: the vowel sign in हिन्दी is misplaced
HarfBuzzTextShaper: correctWhen the built-in engine can't shape a script it reports DXP2002, so you can detect documents that need the shaper.
Note
DocWright.ComplexText is the only DocWright package with a native dependency (HarfBuzzSharp). Windows and macOS binaries are included. On Linux, also add HarfBuzzSharp.NativeAssets.Linux to your application.
Symbol fonts
Symbol and Wingdings characters are stored as private-use code points: Word's default bullet is U+F0B7 in Symbol, its third-level bullet U+F0A7 in Wingdings. Those codes mean something only in that one font.
On a machine without Symbol or Wingdings (a Linux container, or IncludeSystemFontDirectories = false), the bundled stand-ins draw them: DocWright Symbol Fallback and DocWright Dingbat Fallback. Each has the original's code points, advance widths and line metrics, so the layout matches, and each code draws the character it means. The text itself is not changed. An installed Symbol or Wingdings always wins, and the substitution is reported as DXP3001.
using DocWright;
using DocWright.Core.Diagnostics;
using DocWright.Core.Rendering;
using DocWright.Dom;
var diagnostics = new CollectingConversionDiagnostics();
var noSystemFonts = new ConvertOptions { IncludeSystemFontDirectories = false, Diagnostics = diagnostics };
using (FileStream input = File.OpenRead("bullets.docx"))
using (WordDocument document = converter.Load(input))
{
LaidOutConversion laidOut = converter.Layout(document, noSystemFonts);
foreach (GlyphRun run in laidOut.Document.Pages[0].Primitives.OfType<GlyphRun>()
.Where(run => run.Text.Length > 0 && run.Text[0] >= ''))
{
Console.WriteLine($"U+{(int)run.Text[0]:X4} drawn in {run.FontFamily}");
}
using FileStream pdf = File.Create("bullets.pdf");
converter.Convert(document, pdf, noSystemFonts);
}
Output:
U+F0B7 drawn in DocWright Symbol Fallback
U+F0A7 drawn in DocWright Dingbat Fallback

Symbol's U+F0C3 (℘) and Wingdings' U+F0FF (the Windows logo) have no glyph in the stand-ins. Wingdings 2, Wingdings 3 and Webdings have no stand-in.
In the PDF's text layer, DocWright maps the Symbol and Dingbat sets to real Unicode, so a Symbol bullet copies as "•" and a Greek alpha as "α". Text drawn with the Wingdings stand-in copies as what it means too ("▪", "✓"). An installed Wingdings, Webdings and private symbol fonts have no published mapping. Their characters render correctly but extract as private-use code points, reported once per font as DXP3006.