How to Convert HTML to PDF with Images Using HiQPdf

Direct answer: when converting an HTML string with HiQPdf, pass a base URL to the HTML-to-PDF method. HiQPdf uses that URL to resolve relative image, stylesheet, and script references. You can also make every resource URL absolute. If images remain missing, verify that the conversion process can access the resources, then check lazy loading and content created asynchronously by JavaScript.

The exact method signature depends on the HiQPdf generation and package installed in your project. HiQPdf Next documents separate Windows and Linux packages with a shared .NET Standard 2.0 library and platform-specific native runtimes, while older documentation uses different API names and properties.

1. How relative image URLs are resolved

Suppose your HTML contains:

A base URL gives relative images and styles the location they need before HiQPdf renders the PDF.

<img src="Images/report-chart.png" alt="Sales chart">

The path is relative, so the converter needs an origin from which to resolve it. With https://www.example.com/reports/ as the base URL, the resource resolves under that location according to normal URL rules. An absolute reference carries its own location and does not need a base URL:

<img src="https://cdn.example.com/images/report-chart.png" alt="Sales chart">

The same rule applies to relative CSS, JavaScript, fonts, and other resources. A correct base URL fixes path resolution; it does not make unavailable or not-yet-created content appear.

2. Minimal HiQPdf Next conversion from an HTML string

For the current HiQPdf Next API, the documented file conversion has this shape:

using HiQPdf;

var html = @"<!doctype html>
<html>
  <body>
    <h1>Monthly report</h1>
    <img src='Images/report-chart.png' alt='Sales chart'>
  </body>
</html>";

var baseUrl = "https://www.example.com/reports/";
var outputPdfPath = "report.pdf";

var converter = new HtmlToPdf();
converter.ConvertHtmlToFile(html, baseUrl, outputPdfPath);

Create a new HtmlToPdf instance for each conversion call as described by the Next API reference. Use the namespace and package version installed in your application; older HiQPdf generations may expose a different method or output type.

Absolute URLs instead of a base URL

var html = @"<html>
  <body>
    <img src='https://cdn.example.com/images/report-chart.png' alt='Sales chart'>
  </body>
</html>";

var converter = new HtmlToPdf();
converter.ConvertHtmlToFile(html, null, "report.pdf");

This approach is useful when HTML is shared between renderers or generated outside the website whose paths normally provide the context. The renderer still needs network access to the absolute URL.

3. Complete C# example with a report, CSS, and images

using HiQPdf;

var html = @"<!doctype html>
<html>
<head>
  <meta charset='utf-8'>
  <link rel='stylesheet' href='css/report.css'>
</head>
<body>
  <h1>Quarterly report</h1>
  <p>Images, styles, and scripts resolve relative to the base URL.</p>
  <img src='images/revenue.png' alt='Revenue chart'>
  <img src='images/team.jpg' alt='Team photograph'>
</body>
</html>";

var converter = new HtmlToPdf();
converter.ConvertHtmlToFile(
    html,
    "https://www.example.com/reports/",
    "quarterly-report.pdf");

Choose a base URL whose path matches the references in the markup. If images/revenue.png should resolve from the site root, use a root URL or change the HTML to an absolute path that reflects the deployment layout.

4. Local images and local stylesheets

HiQPdf Next’s API reference documents file:/// as the base URL for local file resources referenced with a file:// URL or an absolute disk path.

using HiQPdf;

var html = @"<html>
  <body>
    <h1>Local report</h1>
    <img src='file:///C:/reports/images/chart.png' alt='Chart'>
  </body>
</html>";

var converter = new HtmlToPdf();
converter.ConvertHtmlToFile(html, "file:///", "local-report.pdf");

On Linux, use a correctly formed file URL for the mounted path, for example file:///var/app/reports/images/chart.png. The conversion process must have permission to read the file. A web URL cannot resolve a path that exists only on your application server’s filesystem.

5. URL conversion versus HTML-string conversion

Input	What supplies resource context	Typical use
Web page URL	The page URL and its document location	Convert an already published page
HTML string with relative paths	The `baseUrl` argument	Convert templates or rendered server output
HTML string with absolute paths	Each resource URL	Portable markup with explicit origins
HTML string with local files	`file:///` base and readable paths	Offline or server-side assets

A page URL is itself the input route. The base URL parameter is primarily relevant when the input is an HTML string whose references need resolving.

6. Lazy-loaded and asynchronous images

A correct base URL does not force an image into the document if the page has not created or loaded it yet.

Correct URL resolution cannot replace the wait needed for lazy or asynchronous content.

Lazy loading

HiQPdf troubleshooting documentation identifies HtmlToPdfLoadLazyImages as the setting for lazy images and documents it as enabled by default in the relevant product generation. Confirm the property name and default for your installed package.

var converter = new HtmlToPdf();
// Confirm this property name and behavior against your installed HiQPdf version.
converter.HtmlToPdfLoadLazyImages = true;
converter.ConvertHtmlToFile(html, baseUrl, "lazy-images.pdf");

Also inspect the markup. Many sites put the real URL in data-src and leave src as a placeholder until JavaScript runs. The converter cannot load the final image until that script executes.

Images created after an API call

If JavaScript inserts the image after a request, configure a wait supported by your HiQPdf generation or trigger the rendering code manually. Use a deterministic wait when possible; an arbitrary short delay can capture a partially rendered page.

7. Sizing and page layout

Missing assets and incorrect sizing are separate problems. Older HiQPdf FAQ material describes a default BrowserWidth of 1200 pixels and explains that, at 96 DPI, this is a 12.5-inch HTML width that can be scaled to fit default A4 portrait output. Treat that detail as generation-specific and verify it against your installed package.

If images are present but too small, inspect browser width and PDF page-fit or width settings.
If a wide table is clipped, choose a wider page, landscape orientation, or a smaller browser width according to your document requirements.
Keep image dimensions explicit in CSS when stable pagination matters.
Use print CSS for page breaks, margins, and headers where supported by your HiQPdf version.

8. Troubleshooting missing images

Symptom	Likely cause	Fix
Every relative image is missing	No base URL or an incorrect base path	Pass the site or directory URL that contains the relative resources, or use absolute URLs.
Only local images are missing	Wrong file URL or insufficient filesystem permissions	Use `file:///` as the base for local resources and verify the conversion process can read the files.
Images work in a browser but not in the PDF	The conversion host cannot reach the remote origin, or TLS/authentication differs	Check outbound network access, DNS, certificates, authentication, and firewall rules from the conversion environment.
Lazy images are blank	The image has not entered the document before capture	Enable the lazy-image option documented for your package and allow the page to reach its loaded state.
Charts or images generated by JavaScript are absent	Capture occurs before asynchronous rendering finishes	Configure a supported wait or manually trigger the rendering code, then capture.
Some images load and others do not	Mixed relative paths, blocked hosts, or per-resource errors	Log and open each resolved URL from the conversion host; fix the failing origin or path individually.
Images appear but are unexpectedly small	Browser width or page-fit scaling	Review browser width, DPI, page size, orientation, and fit settings.
Code compiles in examples but not your project	Documentation from a different HiQPdf generation	Match the method and property names to the installed Next or legacy package and its platform runtime.

9. A practical diagnostic checklist

Print the final HTML string and inspect every src, href, and stylesheet URL.
Classify each reference as relative, absolute HTTP(S), or local file.
Resolve one relative reference manually against the proposed base URL.
Open remote resources from the same machine, container, or service account running HiQPdf.
Check authentication, certificates, redirects, and robots or firewall rules that affect that environment.
Determine whether the page uses loading="lazy", data-src, an intersection observer, or asynchronous JavaScript.
Configure the package’s lazy-image and wait behavior, then capture again.
Only after resources load, adjust browser width, page size, margins, and scaling.

10. Reliability, performance, and cost considerations

Reliability

Prefer absolute URLs when the HTML moves between unrelated hosts and you can guarantee those URLs remain valid.
Prefer a base URL when you want the HTML to retain portable, site-relative references.
Make the conversion host’s network and filesystem access explicit in deployment configuration.
Pin and document the HiQPdf package and native runtime so Windows and Linux deployments use matching components.

Performance

Large images increase download and rendering time. Resize source assets when the PDF does not need their full pixel dimensions.
Waiting for network idle or asynchronous scripts improves completeness but increases latency. Use the shortest wait that consistently produces the required content.
Reuse stable, cacheable resources where your deployment allows it, while preserving authentication and freshness requirements.
For high-volume jobs, monitor memory and temporary-file usage and isolate conversions so one unusually large page does not affect unrelated requests.

Cost and licensing

HiQPdf is a commercial .NET library distributed through NuGet packages and licensed per developer seat. Confirm current package, runtime, and licensing terms for your project before deployment. The research materials do not establish a universal conversion price or performance benchmark.

11. Complete command-line and language examples for a hosted page

If your source is already a publicly reachable page and you only need a screenshot or rendered artifact, a hosted capture API can remove browser-runtime setup. The following examples use ScreenshotNeo’s documented endpoint and request shape. For PDF options and the full parameter list, see the ScreenshotNeo API documentation.

cURL

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

Python

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)

Node.js

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 buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);

12. Or skip the browser setup

ScreenshotNeo provides a one-request website capture API and MCP server. Before capture, it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the result with X-Page-Verdict and X-Billed headers. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.

You get 1,000 screenshots per month free with no card. Paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Is a base URL required for every HiQPdf conversion?

No. It is needed when the HTML contains relative URLs. It can be null when there are no relative references, and absolute URLs can remove the need for relative-path resolution.

Can I use a page URL as the base URL?

Yes, when its origin and path correctly resolve the relative references in your rendered HTML. A site root is not always equivalent to the directory containing the HTML assets.

Why does fixing the base URL not fix a lazy image?

Base resolution answers where a resource is. Lazy loading and asynchronous rendering determine when that resource is inserted or requested. You must address both conditions.

Which HiQPdf API example should I trust?

Use the documentation matching the package and generation installed in your project. HiQPdf Next and older product generations do not necessarily share method and property signatures.

Should I convert HTML strings or URLs?

Use an HTML string when your application owns the rendered markup and needs a controlled base URL. Use a page URL when the complete page is already deployed and reachable by the converter.