Resolve relative CSS and image references to bytes you supply; the renderer never fetches them. The input files are in the zip and shown below.
dotnet add package RecursiveAI.OneRender.PdfRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
https://render.example/ is only an identifier for resolving relative URLs, not a server you need to run.
using OneRender.Pdf; using var output = File.Create("card.pdf"); HtmlPdf.ToPdf(File.ReadAllText("input.html"), output, new HtmlPdfOptions { BaseUrl = "https://render.example/", Resources = url => url switch { "https://render.example/card.css" => File.ReadAllBytes("card.css"), "https://render.example/tile.png" => File.ReadAllBytes("tile.png"), _ => null } }); Console.WriteLine("card.pdf written");
card.pdf writtenUnzip the example, then dotnet run.
The full program
input.html contains:
<link rel="stylesheet" href="card.css"> <h1>Local resources</h1> <img src="tile.png" width="32" height="32"> <img src="missing.png" width="32" height="32">
card.css contains:
body { margin:16px; font:16px sans-serif } h1 { color:#2563eb }
tile.png is a 32 × 32 solid blue square (#2563eb) included in the download. These sample assets are CC0. missing.png is deliberately absent.
using OneRender.Pdf; string html = File.ReadAllText("input.html"); var files = new Dictionary<string, byte[]> { ["https://render.example/card.css"] = File.ReadAllBytes("card.css"), ["https://render.example/tile.png"] = File.ReadAllBytes("tile.png") }; using var output = File.Create("card.pdf"); var result = HtmlPdf.ToPdf(html, output, new HtmlPdfOptions { BaseUrl = "https://render.example/input.html", Resources = address => files.GetValueOrDefault(address) }); Console.WriteLine($"card.pdf: {result.PageCount} page(s)"); foreach (var diagnostic in result.Diagnostics) Console.WriteLine($"{diagnostic.Kind}: {diagnostic.Message}");
dotnet run prints:
card.pdf: 1 page(s) MissingResource: an image was not supplied by the host
An unavailable image records a MissingResource diagnostic and paints nothing; it does not stop this PDF from being written.
Variations
Supply the missing image
Before creating the output stream in the full program, add this mapping:
files["https://render.example/missing.png"] = files["https://render.example/tile.png"];
The full program then prints:
card.pdf: 1 page(s)Related recipes
The short answer
Set HtmlPdfOptions.BaseUrl and supply Resources, a callback from an absolute address to bytes. Load the CSS and image files you intend to allow, put their bytes in a dictionary, and return null for every other address. The HTML is read separately and passed as text to HtmlPdf.ToPdf. OneRender does not fetch the HTML or its dependencies for you.
This is useful for an invoice template whose layout and pictures are packaged with your application. The callback maps a reference in the document to a known asset; it is not a general-purpose file loader. The example’s HTTPS address is an identifier used for relative URL resolution, not a server you need to run.
How to convert HTML to PDF with images?
An image reference needs both markup and bytes. Here src="tile.png" resolves against the base address to https://render.example/tile.png. That exact key returns the blue tile. The width and height in the markup reserve a square for it. The second image deliberately points to a missing key so you can see the diagnostic instead of mistaking a partially rendered document for a complete one.
The full program prints every returned diagnostic. In this run, the unavailable image produces MissingResource: an image was not supplied by the host. The pinned painting documentation says a missing image paints nothing; it does not draw alt text or a broken-image icon. The PDF can still be written. If your application requires every picture, treat that diagnostic as a reason not to deliver the result.
The variation supplies the absent image under its requested address. It writes the same page count without the missing-resource diagnostic. That is different from merely removing the diagnostic-printing loop: the resource is now actually available.
How to convert HTML to PDF locally?
Read the HTML, CSS and image files from disk in your own code. Nothing in this example needs a network connection after package restore. Keep relative URL resolution separate from file-system access. A base URL tells the renderer what an address means; it does not grant access to a directory.
The dictionary in the full program is an explicit allowlist. An unexpected reference returns null, even if it contains a parent-directory segment or points to another host. Do not replace that mapping with a direct File.ReadAllBytes on document-controlled paths. For a larger template, build the dictionary from a trusted asset manifest before rendering.
How to convert HTML with CSS to PDF?
Supply external stylesheets through the same callback as images. The link to card.css becomes an absolute address and the callback returns the stylesheet bytes. Inline styles do not need the callback. The resource API documentation also allows font bytes through this hook.
The PDF path uses print media, so a stylesheet’s print rules may differ from its screen rules. JavaScript is not executed: populate template data and construct the final HTML before calling the renderer. When styling disappears, first check the resolved address and dictionary key, then check the CSS itself. A successful file write does not establish that every requested asset was supplied.