Font Configuration Breaking Change (v4.0)¶

Summary¶

Custom font provider is now enabled by default for improved PDF performance.

Breaking Change¶

Previous behavior (v3.x):

Font provider always enabled, not configurable
Used system fonts only
No user control over font loading

New behavior (v4.0):

Font provider enabled by default
Configurable via FontConfig in PdfConfig
Can disable or add custom font directories
~12-13% faster PDF processing with font caching

Impact¶

Who is affected?

Users who rely on pdfium's default font fallback behavior
Users who want to disable the custom font provider
Users who need to add custom font directories

What changes?

Default: Custom font provider now active (breaking change)
Performance: PDF extraction 12-13% faster
API: New font_config option in PdfConfig

Migration¶

No Action Required (Recommended)¶

For most users, no changes needed. Default behavior provides performance improvements:

RustPythonTypeScriptJavaGoRubyC#

use kreuzberg::ExtractionConfig;

// Previous (v4.0) - no font configuration
let config = ExtractionConfig::default();

// Current (v4.0) - same code, now with font provider enabled
let config = ExtractionConfig::default();
// Font provider automatically enabled with system fonts

from kreuzberg import ExtractionConfig

# Previous (v4.0)
config = ExtractionConfig()

# Current (v4.0) - same code, now with font provider enabled
config = ExtractionConfig()
# Font provider automatically enabled with system fonts

import { ExtractionConfig } from 'kreuzberg';

// Previous (v4.0)
const config: ExtractionConfig = {};

// Current (v4.0) - same code, now with font provider enabled
const config: ExtractionConfig = {};
// Font provider automatically enabled with system fonts

import dev.kreuzberg.config.*;

// Previous (v4.0)
ExtractionConfig config = ExtractionConfig.builder().build();

// Current (v4.0) - same code, now with font provider enabled
ExtractionConfig config = ExtractionConfig.builder().build();
// Font provider automatically enabled with system fonts

import "github.com/kreuzberg-dev/kreuzberg/v4"

// Previous (v4.0)
config := &kreuzberg.ExtractionConfig{}

// Current (v4.0) - same code, now with font provider enabled
config := &kreuzberg.ExtractionConfig{}
// Font provider automatically enabled with system fonts

require 'kreuzberg'

# Previous (v4.0)
config = Kreuzberg::ExtractionConfig.new

# Current (v4.0) - same code, now with font provider enabled
config = Kreuzberg::ExtractionConfig.new
# Font provider automatically enabled with system fonts

using Kreuzberg;

// Previous (v4.0)
var config = new ExtractionConfig();

// Current (v4.0) - same code, now with font provider enabled
var config = new ExtractionConfig();
// Font provider automatically enabled with system fonts

Disable Font Provider¶

If you prefer pdfium's default font handling:

RustPythonTypeScriptJavaGoRubyC#

use kreuzberg::{ExtractionConfig, PdfConfig, FontConfig};

let config = ExtractionConfig {
    pdf_options: Some(PdfConfig {
        font_config: Some(FontConfig {
            enabled: false,
            custom_font_dirs: None,
        }),
        ..Default::default()
    }),
    ..Default::default()
};

from kreuzberg import ExtractionConfig, PdfConfig, FontConfig

config = ExtractionConfig(
    pdf_options=PdfConfig(
        font_config=FontConfig(enabled=False)
    )
)

import { ExtractionConfig } from 'kreuzberg';

const config: ExtractionConfig = {
  pdfOptions: {
    fontConfig: {
      enabled: false
    }
  }
};

import dev.kreuzberg.config.*;

FontConfig fontConfig = FontConfig.builder()
    .enabled(false)
    .build();

PdfConfig pdfConfig = PdfConfig.builder()
    .fontConfig(fontConfig)
    .build();

ExtractionConfig config = ExtractionConfig.builder()
    .pdfOptions(pdfConfig)
    .build();

import "github.com/kreuzberg-dev/kreuzberg/v4"

config := &kreuzberg.ExtractionConfig{
    PdfOptions: &kreuzberg.PdfConfig{
        FontConfig: &kreuzberg.FontConfig{
            Enabled: false,
        },
    },
}

require 'kreuzberg'

config = Kreuzberg::ExtractionConfig.new(
  pdf_options: Kreuzberg::PdfConfig.new(
    font_config: Kreuzberg::FontConfig.new(enabled: false)
  )
)

using Kreuzberg;

var fontConfig = new FontConfig { Enabled = false };
var pdfConfig = new PdfConfig { FontConfig = fontConfig };
var config = new ExtractionConfig { PdfOptions = pdfConfig };

Add Custom Font Directories¶

To use fonts from custom directories (in addition system fonts):

RustPythonTypeScriptJavaGoRubyC#

use kreuzberg::{ExtractionConfig, PdfConfig, FontConfig};
use std::path::PathBuf;

let config = ExtractionConfig {
    pdf_options: Some(PdfConfig {
        font_config: Some(FontConfig {
            enabled: true,
            custom_font_dirs: Some(vec![
                PathBuf::from("/usr/share/fonts/custom"),
                PathBuf::from("~/my-fonts"),  // Tilde expanded automatically
            ]),
        }),
        ..Default::default()
    }),
    ..Default::default()
};

from kreuzberg import ExtractionConfig, PdfConfig, FontConfig

config = ExtractionConfig(
    pdf_options=PdfConfig(
        font_config=FontConfig(
            enabled=True,
            custom_font_dirs=[
                "/usr/share/fonts/custom",
                "~/my-fonts"  # Tilde expanded automatically
            ]
        )
    )
)

import { ExtractionConfig } from 'kreuzberg';

const config: ExtractionConfig = {
  pdfOptions: {
    fontConfig: {
      enabled: true,
      customFontDirs: [
        '/usr/share/fonts/custom',
        '~/my-fonts'  // Tilde expanded automatically
      ]
    }
  }
};

import dev.kreuzberg.config.*;
import java.nio.file.Paths;

FontConfig fontConfig = FontConfig.builder()
    .enabled(true)
    .customFontDirs(Arrays.asList(
        Paths.get("/usr/share/fonts/custom"),
        Paths.get("~/my-fonts")  // Tilde expanded automatically
    ))
    .build();

PdfConfig pdfConfig = PdfConfig.builder()
    .fontConfig(fontConfig)
    .build();

ExtractionConfig config = ExtractionConfig.builder()
    .pdfOptions(pdfConfig)
    .build();

import "github.com/kreuzberg-dev/kreuzberg/v4"

config := &kreuzberg.ExtractionConfig{
    PdfOptions: &kreuzberg.PdfConfig{
        FontConfig: &kreuzberg.FontConfig{
            Enabled: true,
            CustomFontDirs: []string{
                "/usr/share/fonts/custom",
                "~/my-fonts",  // Tilde expanded automatically
            },
        },
    },
}

require 'kreuzberg'

config = Kreuzberg::ExtractionConfig.new(
  pdf_options: Kreuzberg::PdfConfig.new(
    font_config: Kreuzberg::FontConfig.new(
      enabled: true,
      custom_font_dirs: [
        '/usr/share/fonts/custom',
        '~/my-fonts'  # Tilde expanded automatically
      ]
    )
  )
)

using Kreuzberg;

var fontConfig = new FontConfig
{
    Enabled = true,
    CustomFontDirs = new[]
    {
        "/usr/share/fonts/custom",
        "~/my-fonts"  // Tilde expanded automatically
    }
};

var pdfConfig = new PdfConfig { FontConfig = fontConfig };
var config = new ExtractionConfig { PdfOptions = pdfConfig };

Configuration Files¶

TOML Format¶

Font Configuration in TOML

[pdf_options.font_config]
enabled = true
custom_font_dirs = ["/usr/share/fonts/custom", "~/my-fonts"]

YAML Format¶

Font Configuration in YAML

pdf_options:
  font_config:
    enabled: true
    custom_font_dirs:
      - /usr/share/fonts/custom
      - ~/my-fonts

JSON Format¶

Font Configuration in JSON

{
  "pdf_options": {
    "font_config": {
      "enabled": true,
      "custom_font_dirs": ["/usr/share/fonts/custom", "~/my-fonts"]
    }
  }
}

Path Handling¶

The font configuration automatically handles:

Tilde expansion: ~/fonts → /Users/username/fonts
Relative paths: ./fonts → /absolute/path/to/fonts
Symlinks: Resolved to canonical paths (security measure)
Validation: Directories must exist; warnings logged if not found
Graceful degradation: Missing directories don't cause failures

Global Configuration¶

Important: Font configuration is global per process and must be set before the first PDF extraction.

RustPythonTypeScriptJavaGoRubyC#

// CORRECT: Set config before first extraction
let config = ExtractionConfig {
    pdf_options: Some(PdfConfig {
        font_config: Some(FontConfig {
            enabled: true,
            custom_font_dirs: Some(vec![
                PathBuf::from("/usr/share/fonts/custom"),
            ]),
        }),
        ..Default::default()
    }),
    ..Default::default()
};

let result = kreuzberg::extract_file("document.pdf", &config)?;

// INCORRECT: Attempting to change config after first extraction
let new_config = ExtractionConfig {
    pdf_options: Some(PdfConfig {
        font_config: Some(FontConfig {
            enabled: false,
            custom_font_dirs: None,
        }),
        ..Default::default()
    }),
    ..Default::default()
};
let result2 = kreuzberg::extract_file("document2.pdf", &new_config)?;
// Warning logged: "Font config already initialized"

# CORRECT: Set config before first extraction
config = ExtractionConfig(
    pdf_options=PdfConfig(
        font_config=FontConfig(
            enabled=True,
            custom_font_dirs=["/usr/share/fonts/custom"]
        )
    )
)
result = extract_file("document.pdf", config)

# INCORRECT: Attempting to change config after first extraction
new_config = ExtractionConfig(
    pdf_options=PdfConfig(
        font_config=FontConfig(enabled=False)
    )
)
result2 = extract_file("document2.pdf", new_config)
# Warning logged: "Font config already initialized"

// CORRECT: Set config before first extraction
const config: ExtractionConfig = {
  pdfOptions: {
    fontConfig: {
      enabled: true,
      customFontDirs: ['/usr/share/fonts/custom']
    }
  }
};
const result = await extractFile('document.pdf', config);

// INCORRECT: Attempting to change config after first extraction
const newConfig: ExtractionConfig = {
  pdfOptions: {
    fontConfig: { enabled: false }
  }
};
const result2 = await extractFile('document2.pdf', newConfig);
// Warning logged: "Font config already initialized"

// CORRECT: Set config before first extraction
FontConfig fontConfig = FontConfig.builder()
    .enabled(true)
    .customFontDirs(Arrays.asList(Paths.get("/usr/share/fonts/custom")))
    .build();
PdfConfig pdfConfig = PdfConfig.builder()
    .fontConfig(fontConfig)
    .build();
ExtractionConfig config = ExtractionConfig.builder()
    .pdfOptions(pdfConfig)
    .build();
ExtractionResult result = Kreuzberg.extractFile("document.pdf", config);

// INCORRECT: Attempting to change config after first extraction
FontConfig newFontConfig = FontConfig.builder()
    .enabled(false)
    .build();
PdfConfig newPdfConfig = PdfConfig.builder()
    .fontConfig(newFontConfig)
    .build();
ExtractionConfig newConfig = ExtractionConfig.builder()
    .pdfOptions(newPdfConfig)
    .build();
ExtractionResult result2 = Kreuzberg.extractFile("document2.pdf", newConfig);
// Warning logged: "Font config already initialized"

// CORRECT: Set config before first extraction
config := &kreuzberg.ExtractionConfig{
    PdfOptions: &kreuzberg.PdfConfig{
        FontConfig: &kreuzberg.FontConfig{
            Enabled: true,
            CustomFontDirs: []string{"/usr/share/fonts/custom"},
        },
    },
}
result, _ := kreuzberg.ExtractFile("document.pdf", config)

// INCORRECT: Attempting to change config after first extraction
newConfig := &kreuzberg.ExtractionConfig{
    PdfOptions: &kreuzberg.PdfConfig{
        FontConfig: &kreuzberg.FontConfig{
            Enabled: false,
        },
    },
}
result2, _ := kreuzberg.ExtractFile("document2.pdf", newConfig)
// Warning logged: "Font config already initialized"

# CORRECT: Set config before first extraction
config = Kreuzberg::ExtractionConfig.new(
  pdf_options: Kreuzberg::PdfConfig.new(
    font_config: Kreuzberg::FontConfig.new(
      enabled: true,
      custom_font_dirs: ['/usr/share/fonts/custom']
    )
  )
)
result = Kreuzberg.extract_file('document.pdf', config)

# INCORRECT: Attempting to change config after first extraction
new_config = Kreuzberg::ExtractionConfig.new(
  pdf_options: Kreuzberg::PdfConfig.new(
    font_config: Kreuzberg::FontConfig.new(enabled: false)
  )
)
result2 = Kreuzberg.extract_file('document2.pdf', new_config)
# Warning logged: "Font config already initialized"

// CORRECT: Set config before first extraction
var fontConfig = new FontConfig
{
    Enabled = true,
    CustomFontDirs = new[] { "/usr/share/fonts/custom" }
};
var pdfConfig = new PdfConfig { FontConfig = fontConfig };
var config = new ExtractionConfig { PdfOptions = pdfConfig };
var result = Kreuzberg.ExtractFile("document.pdf", config);

// INCORRECT: Attempting to change config after first extraction
var newFontConfig = new FontConfig { Enabled = false };
var newPdfConfig = new PdfConfig { FontConfig = newFontConfig };
var newConfig = new ExtractionConfig { PdfOptions = newPdfConfig };
var result2 = Kreuzberg.ExtractFile("document2.pdf", newConfig);
// Warning logged: "Font config already initialized"

Performance Impact¶

With default settings (enabled=true, system fonts):

PDF extraction: ~12-13% faster
Memory: Minimal increase (~100KB for font cache)
Startup: Lazy initialization (no overhead for non-PDF workloads)

Troubleshooting¶

Custom fonts not working¶

Symptom: PDF still uses fallback fonts

Solutions:

Verify directories exist and contain .ttf/.otf/.ttc files
Check logs for "Custom font directory not found" warnings
Ensure paths are absolute or properly expanded
Verify font files are readable

"Font config already initialized" warning¶

Symptom: Configuration changes ignored after first PDF extraction

Solution: Set FontConfig in the first ExtractionConfig used. Subsequent config changes are not supported (global limitation).

Performance regression¶

Symptom: PDF extraction slower after upgrade

Solution: This is unexpected. Please report as a bug with:

PDF sample (if shareable)
Benchmark comparison (before/after)
Configuration used

Questions?¶

Issue tracker: https://github.com/kreuzberg-dev/kreuzberg/issues
Discussions: https://github.com/kreuzberg-dev/kreuzberg/discussions