ZingPDF.Templates.LiquidHtml
1.0.60
dotnet add package ZingPDF.Templates.LiquidHtml --version 1.0.60
NuGet\Install-Package ZingPDF.Templates.LiquidHtml -Version 1.0.60
<PackageReference Include="ZingPDF.Templates.LiquidHtml" Version="1.0.60" />
<PackageVersion Include="ZingPDF.Templates.LiquidHtml" Version="1.0.60" />
<PackageReference Include="ZingPDF.Templates.LiquidHtml" />
paket add ZingPDF.Templates.LiquidHtml --version 1.0.60
#r "nuget: ZingPDF.Templates.LiquidHtml, 1.0.60"
#:package ZingPDF.Templates.LiquidHtml@1.0.60
#addin nuget:?package=ZingPDF.Templates.LiquidHtml&version=1.0.60
#tool nuget:?package=ZingPDF.Templates.LiquidHtml&version=1.0.60
ZingPDF.Templates.LiquidHtml
ZingPDF.Templates.LiquidHtml creates PDFs from Liquid HTML templates. It uses Fluid for Liquid rendering and ZingPDF.FromHTML for HTML-to-PDF conversion.
.NET compatibility
Targets net8.0, with .NET 8 as the minimum. Runtime validation covers .NET 8,
9, and 10 on Windows. .NET Framework 4.x and applications targeting .NET 6 or 7
are not supported. Native dependencies and deployment requirements remain package-specific. See runtime and platform requirements.
Installation
dotnet add package ZingPDF.Templates.LiquidHtml
Quick start
Render a Liquid HTML template file to PDF:
using ZingPDF.Templates.LiquidHtml;
var invoice = new
{
Number = "INV-1001",
CustomerName = "Ada Lovelace",
Items = new[]
{
new { Description = "Consulting", Total = 240m },
new { Description = "Support", Total = 80m }
}
};
await using var output = File.Create("invoice.pdf");
await LiquidHtmlPdfTemplate
.FromFile("invoice.liquid.html")
.RenderAsync(invoice, output);
The template can use Liquid variables, loops, and conditionals:
<!doctype html>
<html>
<body>
<h1>Invoice {{ Number }}</h1>
<p>{{ CustomerName }}</p>
<table>
{% for item in Items %}
<tr>
<td>{{ item.Description }}</td>
<td>{{ item.Total }}</td>
</tr>
{% endfor %}
</table>
</body>
</html>
Share a configured browser
The invoice model above can use a caller-owned renderer. Pass the application cancellation token through RenderAsync.
using ZingPDF.FromHTML;
using ZingPDF.Templates;
using ZingPDF.Templates.LiquidHtml;
await using var renderer = new HtmlToPdfRenderer(new HtmlToPdfOptions
{
BrowserExecutablePath = Environment.GetEnvironmentVariable("ZINGPDF_BROWSER_PATH")
?? throw new InvalidOperationException("Set ZINGPDF_BROWSER_PATH to an installed browser.")
});
var template = LiquidHtmlPdfTemplate.FromSource(
PdfTemplateSource.FromFile("invoice.liquid.html"),
new RendererHtmlToPdfConverter(renderer));
await using var output = File.Create("invoice.pdf");
await template.RenderAsync(invoice, output, cancellationToken: cancellationToken);
The converter receives the cancellation token after Liquid rendering and uses the renderer's concurrency, deadline and print settings. The renderer deadline starts at browser conversion; it does not include Liquid rendering. Liquid parsing and rendering are not an interruptible OS-level workload.
For paginated invoices, define @page, a thead with display: table-header-group, and break-inside: avoid on rows. Keep totals outside repeating table footers. See examples/GenerateInvoices for 0, 1, 40 and 500 line items, repeated headers, totals and embedded fonts.
Notes
- Supply
BrowserExecutablePathfor an installed Chromium-compatible browser.AllowBrowserDownloaddefaults tofalse; enable it explicitly only if runtime downloading is intended. - Reuse one
HtmlToPdfRendereracross jobs. It owns one browser and creates an isolated browser context for each conversion.MaxConcurrencydefaults to 4; additional jobs queue. RenderTimeoutdefaults to 30 seconds and covers queueing, browser startup, page loading, font readiness and PDF printing. Set it toTimeout.InfiniteTimeSpanto disable the overall deadline.BrowserStartupTimeoutindependently limits browser provisioning and launch to 30 seconds by default and must remain finite. Expiry throwsTimeoutException; caller cancellation throwsOperationCanceledException. Context creation and cleanup must complete to release resources; browser startup or downloading can remain renderer-owned after a caller stops waiting, within the separate startup budget. Disposal cancels browser provisioning. The deadline is not an OS-enforced hard worker bound.- The renderer snapshots options, including print options and launch arguments, at construction. The caller disposes the renderer and returned streams; templates and their converter adapter do not own the renderer.
- New renderer defaults use print media, background printing and CSS page sizes. Set
PdfOptionsfor paper, margins, page ranges or headers/footers. Original staticConverter.ToPdfAsync(...)overloads retain automatic browser downloading, screen media and default PuppeteerSharp print settings. They disable the overall conversion deadline so explicit navigation timeouts, including zero, remain effective; the independent browser startup budget still defaults to 30 seconds. The overload takingHtmlToPdfOptionsuses explicit settings for one job. Offline = trueemulates offline page networking. Embed fonts and images as data URLs. This setting is not an OS-level network sandbox or a security guarantee.- HTML and scripts must be trusted. Isolated browser contexts separate job state; they do not sandbox hostile code at the process or network boundary. The renderer does not disable Chromium's sandbox by default.
- File-backed templates resolve Liquid includes from the template directory by default.
- Use
RenderHtmlAsync(...)to inspect rendered HTML before PDF conversion. - Default
FromFile,FromStringand single-argumentFromSourceuse the original static converter settings. Select the two-argumentFromSourceoverload to control browser deployment and printing.
More information
- core docs: zingpdf.dev/docs.html
- Liquid HTML template guide: zingpdf.dev/create-pdf-from-liquid-html-template-csharp.html
- repository: github.com/ZingPDF/ZingPDF
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net8.0
- Fluid.Core (>= 2.31.0)
- Microsoft.Extensions.FileProviders.Physical (>= 9.0.4)
- ZingPDF.FromHTML (>= 1.0.60)
- ZingPDF.Templates (>= 1.0.60)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.