Guide

How to create a PDF from a Liquid HTML template in C#

Reference ZingPDF.Templates.LiquidHtml, render a Liquid template with a .NET model, and write the converted PDF stream.

The package uses Fluid for Liquid rendering and ZingPDF.FromHTML for HTML-to-PDF conversion. It has the same browser automation requirements as ZingPDF.FromHTML.

Render the model to PDF

LiquidHtmlPdfTemplate.FromFile(...) reads the template, renders it with the supplied model, converts the rendered HTML to PDF, and copies the PDF bytes to the output stream.

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);

Write a Liquid HTML template

Liquid variables, loops, and conditionals are evaluated before the HTML is sent to the PDF converter.

<!doctype html>
<html>
  <head>
    <style>
      body { font-family: Arial, sans-serif; margin: 40px; }
      table { border-collapse: collapse; width: 100%; }
      th, td { border-bottom: 1px solid #ddd; padding: 8px; text-align: left; }
      .amount { text-align: right; }
    </style>
  </head>
  <body>
    <h1>Invoice {{ Number }}</h1>
    <p>Bill to: {{ CustomerName }}</p>

    <table>
      <thead>
        <tr>
          <th>Description</th>
          <th class="amount">Total</th>
        </tr>
      </thead>
      <tbody>
        {% for item in Items %}
        <tr>
          <td>{{ item.Description }}</td>
          <td class="amount">{{ item.Total }}</td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
  </body>
</html>

Inspect the rendered HTML

Use RenderHtmlAsync(...) when you want to inspect Liquid output before browser conversion.

var html = await LiquidHtmlPdfTemplate
    .FromFile("invoice.liquid.html")
    .RenderHtmlAsync(invoice);

await File.WriteAllTextAsync("invoice-preview.html", html);

Use includes from the template directory

File-backed templates resolve Liquid includes from the template file directory unless LiquidHtmlPdfTemplateOptions.BasePath is set.

{% include 'line-item.liquid' %}

await LiquidHtmlPdfTemplate
    .FromFile("templates/invoice.liquid.html")
    .RenderAsync(invoice, output, new LiquidHtmlPdfTemplateOptions
    {
        BasePath = "templates/partials"
    });

Account for browser conversion

Liquid rendering is in-process .NET code. PDF conversion uses ZingPDF.FromHTML, which depends on PuppeteerSharp and a Chromium runtime. Validate containers, serverless hosts, CI, and locked-down desktops before relying on this package in those environments.

Need PDF-native fields instead?

AcroForm filling uses an existing PDF form as the template and does not use HTML conversion.

Open form guide Open template docs