How to Load External Resources with EvoPdf baseUrl When Converting HTML to Images

Direct answer: pass the URL that relative resources should resolve against as the baseUrl argument when converting an HTML string with EvoPdf. For example, if the HTML contains images/chart.png and css/site.css, use a base URL such as https://www.example.com/reports/. EvoPdf combines that base with each relative path before requesting the resource.

A base URL supplies resolution context; it does not make an inaccessible resource available. The conversion machine must be able to reach the resulting URL, and protected resources may require cookies, headers or authentication.

1. Minimal C# example

The exact overload depends on your installed EvoPdf edition and output format. The HTML-to-image APIs expose a base URL for HTML-string conversion; use the equivalent overload in your version.

using System;
using EvoPdf;

class Program
{
    static void Main()
    {
        var html = @"
<!doctype html>
<html>
<head>
  <link rel='stylesheet' href='css/site.css'>
</head>
<body>
  <h1>Quarterly report</h1>
  <img src='images/chart.png' alt='Chart'>
</body>
</html>";

        var converter = new HtmlToImageConverter();

        // Relative paths resolve from this URL.
        byte[] image = converter.ConvertHtml(
            html,
            "https://www.example.com/reports/");

        System.IO.File.WriteAllBytes("report.png", image);
    }
}

The important detail is the trailing directory path. With the base above, images/chart.png resolves to https://www.example.com/reports/images/chart.png. Choose the base that matches the page or directory your HTML assumes.

2. Relative and absolute URLs

Reference in HTML	Needs baseUrl?	What to check
`images/logo.png`	Yes	Base path and reachability
`/assets/site.css`	Usually yes	Correct scheme and host
`https://cdn.example.com/site.css`	No	Converter host can reach the CDN
`//cdn.example.com/site.css`	Use a base with the intended scheme	HTTP versus HTTPS behavior
`file:///C:\images\logo.jpg`	No	File permissions and file URL syntax

Fully qualified URLs do not need a base URL. A leading slash is root-relative, while a path without a leading slash is relative to the base directory. A raw Windows filesystem path is not the documented URL form; use a file:/// URL for local assets.

3. Complete resource-loading checklist

Search the HTML, CSS and inline styles for relative images, stylesheets, scripts and font URLs.
Write down the final URL each reference should become after resolution.
Pass that directory or page URL as baseUrl.
Request every final URL from the machine running EvoPdf, not only from your workstation browser.
Check authentication, cookies, request headers, firewall rules and DNS if a resource is protected or private.
For content created after navigation, configure the appropriate conversion delay or manual trigger after URL access is working.

4. Protected and local resources

If an image or stylesheet requires login, a base URL alone is insufficient. Configure EvoPdf’s authentication, request-cookie or request-header settings for the installed edition. The property reference documents HttpRequestHeaders, PersistentHttpRequestHeaders and HttpRequestCookies; persistent headers control whether custom headers are also sent when fetching resources such as CSS and images.

For local files, use a file URL such as file:///C:\images\image.jpg. Confirm that the conversion process has permission to read the file and that the path is valid on the conversion host.

5. Useful converter settings

NavigationTimeout: the documented default is 60 seconds. Increase it only when the page genuinely needs more time.
Conversion delay or manual trigger: useful for assets inserted by client-side code after navigation.
DownloadAllResources: where available, this attempts to download all resources but can slow conversion; it does not correct a wrong URL or missing permission.
Output overload: choose the memory, file, stream or tiled HTML-string overload appropriate for your output and installed edition.

6. Troubleshooting missing images or CSS

“Images and CSS are missing”

Cause: relative paths have no correct resolution context. Fix: pass the base directory that makes each path absolute, then log or calculate the resulting URLs.

The base URL is correct, but resources still fail

Cause: the conversion server cannot reach the host, or the resource requires credentials. Fix: test the final URL from the conversion machine; check firewall rules, localhost bindings, DNS, cookies, headers and authentication.

Only CSS images or web fonts are absent

Cause: those nested URLs are also relative, and headers may not be propagated to subrequests. Fix: verify every URL inside the stylesheet and review persistent request-header and cookie configuration.

Local files work in a browser but not in EvoPdf

Cause: a raw filesystem path was supplied or the service account lacks access. Fix: use the file:/// form and grant the converter process read permission.

Dynamic content is blank

Cause: the page builds the resource after initial navigation. Fix: use the converter’s delay or manual triggering option, while keeping the base URL and network checks in place.

Conversion times out

Cause: slow or blocked navigation, many resources, or an overly short timeout. Fix: test URLs individually, reduce unnecessary resources, and adjust NavigationTimeout only after fixing reachability.

7. Performance and reliability

Absolute asset URLs remove one resolution step, but they still must be reachable.
Every external stylesheet, image, script and font adds network work. Keep the resource set focused for faster conversion.
DownloadAllResources can increase conversion time.
Use a stable, publicly reachable base URL when possible; avoid workstation-only paths and localhost addresses.
For repeatable output, pin asset versions and make authentication headers or cookies explicit.
Log the base URL, final resource URLs, response failures and conversion duration so missing assets can be separated from rendering problems.

8. Or skip the browser setup

If your goal is a clean screenshot rather than controlling an EvoPdf conversion, ScreenshotNeo provides a single screenshot request. Its API removes cookie and consent banners, newsletter popups and chat widgets before capture. Bot checks, blank pages and failed loads are not billed, and response headers identify the page verdict and billing status. It also offers an MCP server so Claude, Cursor and other MCP clients can take screenshots.

See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

There are 1,000 free screenshots each month with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. FAQ

Do I need baseUrl when every resource URL is absolute?

No. Fully qualified URLs already contain their resolution context.

Does baseUrl download or embed resources?

No. It tells EvoPdf how to form URLs. Network access, permissions and authentication remain separate requirements.

Should baseUrl point to a file or a directory?

Use the page or directory location implied by the relative references. A trailing slash makes directory intent clear.

Why does a URL work locally but fail in production?

The conversion host may have different DNS, firewall access, credentials or permissions. Test from that host.

Can delayed JavaScript fix a wrong base URL?

No. Resolve and access the resources first; then use a delay or manual trigger for content created after navigation.