Using own fonts for Html to Pdf converter in Docker

Merold · December 8, 2025, 10:22am

How to use certain fonts for Html to Pdf converter in docker in .NET

Professionalize.Discourse · December 8, 2025, 10:23am

How to make Aspose.HTML for .NET use custom fonts inside a Docker container

Make the fonts available to the container
*Copy the required .ttf/.otf files into the image (or mount a volume).

# Example based on a .NET 6 SDK image
FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime

# Install fontconfig (required for Aspose.HTML to discover system fonts)
RUN apt-get update && apt-get install -y fontconfig

# Copy your custom fonts
COPY ./fonts /usr/share/fonts/custom
RUN fc-cache -f -v   # refresh the font cache

If you prefer to mount the fonts at runtime:

docker run -v /host/path/to/fonts:/usr/share/fonts/custom \
           -e ASPNETCORE_URLS=http://+:80 \
           your-image

Tell Aspose.HTML where to look for the fonts (optional)
Aspose.HTML automatically scans the system font directories (e.g., /usr/share/fonts).
If you want to point it to a specific folder, use FontSettings:

using Aspose.Html;
using Aspose.Html.Rendering.Pdf;

// Create a FontSettings instance
var fontSettings = new FontSettings();
// Add a folder that contains your custom fonts
fontSettings.FontSources.Add(new FileFontSource("/usr/share/fonts/custom"));

// Pass the settings to the HtmlToPdf converter
var converter = new HtmlToPdf();
converter.FontSettings = fontSettings;

// Convert
converter.Convert("input.html", "output.pdf");

Verify that the font is being used

Render a simple HTML snippet that explicitly references the custom font:

<style>
    @font-face {
        font-family: 'MyCustomFont';
        src: url('file:///usr/share/fonts/custom/MyCustomFont.ttf');
    }
    body { font-family: 'MyCustomFont', sans-serif; }
</style>
<p>Hello, custom font!</p>

Run the conversion and open the resulting PDF to confirm the text uses MyCustomFont.

What we still need to know (to fine‑tune the solution)

Item	Why it matters
Aspose.HTML version	Some APIs (e.g., `FontSettings.FontSources`) were introduced in specific releases.
Base Docker image (e.g., `alpine`, `debian`, `ubuntu`)	Determines the package manager (`apk`, `apt-get`) for installing `fontconfig`.
How you load the HTML (URL, string, file)	May affect the way you reference the font file (`file://` vs relative path).
Any error messages you see when the font is not applied	Helps pinpoint whether the issue is font discovery, cache, or CSS reference.

Please provide the above details if the steps above don’t produce the expected result, and we can adjust the guidance accordingly.

Merold · December 8, 2025, 3:38pm

Aspose.HTML.Drawing Version 25.11.0
Package manager apt-get

Code-Snippet:
using var configuration = Aspose.Html.Configuration.Create();
var userAgentService = configuration.GetRequiredService();
var fontPath = Path.Combine(Environment.CurrentDirectory, “Font”);

        userAgentService.FontsSettings.SetFontsLookupFolder(fontPath, true);

        var stream = new MemoryStream();
        using var streamProvider = new InMemoryStreamProvider(stream);
        using var document = new HTMLDocument(request.Html, "/", configuration);

        var options = CreatePdfSaveOptions(request.PdfTitel, Configuration);

        Converter.ConvertHTML(document, options, streamProvider);

Professionalize.Discourse · December 8, 2025, 3:38pm

@Merold

Steps to make custom fonts work with Aspose.HTML .Drawing 25.11.0 in a Docker container (apt‑get base)

Install the system‑wide font manager – Aspose.HTML scans the font cache that fontconfig builds.

FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
RUN apt-get update && apt-get install -y fontconfig

Copy (or mount) your font files into the image – place the .ttf/.otf files in a folder that will be reachable from the container, e.g. /usr/share/fonts/custom.
```
# copy from the build context
COPY ./fonts /usr/share/fonts/custom
# refresh the cache
RUN fc-cache -f -v
```
If you prefer to mount at runtime:
```
docker run -v /host/path/to/fonts:/usr/share/fonts/custom \
           your-image
```

Tell Aspose.HTML where to look for the fonts (optional but recommended) – use the IUserAgentService.FontsSettings API you already have. The folder must be an absolute path inside the container.

using var configuration = Aspose.Html.Configuration.Create();

// Resolve the absolute path (e.g. /usr/share/fonts/custom)
var fontPath = "/usr/share/fonts/custom";

var userAgentService = configuration.GetRequiredService<IUserAgentService>();
// true = also scan sub‑folders
userAgentService.FontsSettings.SetFontsLookupFolder(fontPath, true);

Reference the font in your HTML/CSS – either rely on the system lookup or use an explicit @font-face with a file:// URL that points to the same folder.

<style>
@font-face {
    font-family: 'MyCustomFont';
    src: url('file:///usr/share/fonts/custom/MyCustomFont.ttf');
}
body { font-family: 'MyCustomFont', sans-serif; }
</style>

Run the conversion – the rest of your code can stay unchanged.

using var stream = new MemoryStream();
using var streamProvider = new InMemoryStreamProvider(stream);
using var document = new HTMLDocument(request.Html, "/", configuration);

var options = CreatePdfSaveOptions(request.PdfTitel, configuration);
Converter.ConvertHTML(document, options, streamProvider);

What to verify

The folder /usr/share/fonts/custom exists in the container and contains the font files.
fc-cache -f -v finishes without errors (you’ll see the fonts being added).
The generated PDF shows the expected font (open the PDF and check the font name in the document properties).

If the font still isn’t applied, capture the container logs and share:

Any warnings from fc-cache.
The exact HTML snippet you are converting.
The PDF’s font list (e.g., via Adobe Reader → File → Properties → Fonts).

With those details we can pinpoint whether the issue is font discovery, CSS reference, or cache refresh.

Merold · December 9, 2025, 1:32pm

give me examples of FontsSettings.SetFontsLookupFolder

asad.ali · December 9, 2025, 6:37pm

@Merold

Below is a simple and basic example of using FontSettings during HTML to PDF Conversion:

using (var configuration = new Aspose.Html.Configuration())
{
    // Get the IUserAgentService
    var service = configuration.GetService<IUserAgentService>();
    service.FontsSettings.SetFontsLookupFolders(new[] { @"D:\Fonts\" });
    service.UserStyleSheet = @"@page 
                            {
                                margin-top: 1cm; 
                                margin-left: 1cm;
                                margin-right: 1cm;
                                margin-bottom: 1cm;
                            }";
    using (var document1 = new HTMLDocument(dataDir + "Input.html", configuration))
    {
        // Convert HTML to PDF
        Converter.ConvertHTML(document1, new Aspose.Html.Saving.PdfSaveOptions(), dataDir + "out.pdf");
    }
}

In case it does not help, please share more details about your scenario so that we can investigate accordingly and share our feedback with you.

Merold · December 10, 2025, 9:33am

Under Docker Linux, the font path set with SetFontsLookupFolder (/app/Font) is not used when ConvertHTML is called. In this case, the fonts are always loaded from the default directory /usr/share/fonts. Under Windows it works. Is this a bug or what’s wrong with the code:

public MemoryStream Convert(HtmlToPdfRequest request)
{
using var configuration = Aspose.Html.Configuration.Create();
var userAgentService = configuration.GetRequiredService();

        // https://docs.aspose.com/html/net/how-to-set-font-folder/
        var fontPath = Path.Combine(Environment.CurrentDirectory, "Font");
        Logger.LogDebug($"Setze Schriftartenpfad für Aspose HTML auf: {fontPath}");

        userAgentService.FontsSettings.SetFontsLookupFolder(fontPath, true);

        using (HTMLDocument document = new HTMLDocument(request.Html, "/", configuration))
        {
            var stream = new MemoryStream();
            using var streamProvider = new InMemoryStreamProvider(stream);
            var options = CreatePdfSaveOptions(request.PdfTitel, Configuration);
            Converter.ConvertHTML(document, options, streamProvider);

            // Post-Processing der PDF durchfuehren.
            using var pdf = new Aspose.Pdf.Document(stream);
            foreach (var page in pdf.Pages)
            {
                foreach (var processor in request.PdfPostProcessors)
                {
                    processor.PostProcess(document, pdf, page);
                }
            }

            var resultStream = new MemoryStream();
            pdf.Save(resultStream);

            resultStream.Position = 0;
            return resultStream;
        }
    }

asad.ali · December 10, 2025, 6:28pm

@Merold

It looks like related to the configurations in docker. We have logged an investigation ticket as HTMLNET-6842 in our issue management system for further analysis. We will look into its details and keep you posted with the status of its correction. Please be patient and spare us some time.

We are sorry for the inconvenience.