Fonts

CobaltPdf can inject local font files into the browser context so that your PDF renders using exactly the fonts you supply, regardless of what is installed on the server.

How It Works

When you call ConfigureFonts(directory), CobaltPdf reads every supported font file from the directory, Base64-encodes each one, and generates a CSS @font-face block. This CSS is injected as an init script before the page loads — meaning the fonts are available from the first paint.

Font family names, weights, and styles are inferred automatically from the filename using standard naming conventions.

Supported Formats

Extension	Format
`.ttf`	TrueType
`.otf`	OpenType
`.woff`	Web Open Font Format
`.woff2`	Web Open Font Format 2

Basic Usage

var pdf = await renderer
    .ConfigureFonts("C:/fonts/roboto")   // directory containing .ttf/.woff2 files
    .WithCspBypass()                      // recommended when injecting fonts into strict sites
    .RenderUrlAsPdfAsync("https://example.com");

Important

Many sites use a Content Security Policy that blocks inline styles or data URIs. Always pair ConfigureFonts with WithCspBypass() to ensure the injected @font-face declarations are not blocked.

Filename Convention

CobaltPdf infers metadata from the filename. The last hyphen-or-space-separated segments that match known weight/style keywords become the font weight and style; everything before them becomes the family name.

Examples

Filename	Family	Weight	Style
`Roboto-Regular.ttf`	Roboto	400	normal
`Roboto-Bold.ttf`	Roboto	700	normal
`Roboto-BoldItalic.ttf`	Roboto	700	italic
`Roboto-Light.ttf`	Roboto	300	normal
`OpenSans-ExtraBold.woff2`	Open Sans	800	normal
`Montserrat-SemiBold.otf`	Montserrat	600	normal
`Helvetica.ttf`	Helvetica	400	normal

Weight Keyword Mapping

Keyword(s)	CSS `font-weight`
`Thin`, `Hairline`	100
`ExtraLight`, `UltraLight`	200
`Light`	300
`Regular`, `Normal` (or none)	400
`Medium`	500
`SemiBold`, `DemiBold`	600
`Bold`	700
`ExtraBold`, `UltraBold`	800
`Black`, `Heavy`	900

Directory Layout Example

C:/fonts/
└── roboto/
    ├── Roboto-Thin.ttf
    ├── Roboto-Light.ttf
    ├── Roboto-Regular.ttf
    ├── Roboto-Medium.ttf
    ├── Roboto-Bold.ttf
    ├── Roboto-ExtraBold.ttf
    └── Roboto-Black.ttf

// All seven weights injected automatically
var pdf = await renderer
    .ConfigureFonts("C:/fonts/roboto")
    .WithCspBypass()
    .RenderHtmlAsPdfAsync("""
        <html>
        <body style="font-family: Roboto, sans-serif;">
            <h1 style="font-weight:700;">Bold heading</h1>
            <p style="font-weight:300;">Light body text</p>
        </body>
        </html>
        """);

Multiple Font Families

Point to a directory that contains files from multiple families — all are injected:

C:/fonts/brand/
├── Roboto-Regular.ttf
├── Roboto-Bold.ttf
├── Montserrat-SemiBold.otf
└── Montserrat-Black.otf

var pdf = await renderer
    .ConfigureFonts("C:/fonts/brand")
    .WithCspBypass()
    .RenderUrlAsPdfAsync("https://myapp.com/report");

Caching

Font CSS is cached in memory by directory path. The first render for a given directory pays the disk I/O and Base64 encoding cost; subsequent renders use the cached result. To invalidate the cache (e.g. after updating font files at runtime), call:

// Internal API — accessible via reflection if needed, or restart the application.
// The cache is automatically cleared when the application restarts.

Table of Contents