HTML to PDF features

You can convert HTML to PDF using the Docotic.Pdf library. Check the resources mentioned on this page to find out how to create beautiful PDFs from your data.

You would need the HTML to PDF add-on for HTML to PDF conversions. This is a free add-on for the Docotic.Pdf library. The add-on is also available in the zip file with library binaries.

Docotic.Pdf library 9.5.17664-dev HTML to PDF add-on 9.5.17664-dev
Regression tests 14,820 passed Total NuGet downloads 4,998,853

API reference

On our site, we provide the API reference for the HTML to PDF add-on.

Articles

Read the following to know more about HTML to PDF conversion in C# and VB.NET code.

Convert HTML to PDF in C# and VB.NET
Contains C# HTML to PDF conversion code that shows how to generate PDF in C# and VB.NET from HTML code with CSS styles.
Convert HTML to PDF in Azure Functions
How to convert HTML to PDF in Azure Functions and Azure App Services with .NET Core in Windows and Linux.

Sample code

HTML to PDF conversion is the term that can describe the variety of related tasks. The following sections describe these tasks in more detail.

HTML to PDF C# Conversion

You would need to start with installing the add-on. Use Package Manager to install the HTML to PDF add-on from NuGet.

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

The add-on provides asynchronous-only API. We designed it to work with async event handlers and async methods. You can use the add-on in Windows Forms, WPF, ASP.NET and console applications.

C# HTML to PDF code looks like this:

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("out.pdf");

The code creates an instance of the HTML to PDF converter. Then the code uses the instance to create a PDF from HTML. You can continue working with the PDF document but the example code just saves the document.

If your console application uses an older version of C# and you don't have async Main - don't worry. You still can use the add-on in your app.

The following code shows how to convert URL to PDF in a regular synchronous method:

Task.Run(async () =>
{
    using var converter = await HtmlConverter.CreateAsync();
    var uri = new Uri("https://bitmiracle.com/pdf-library/html-pdf/");
    using var pdf = await converter.CreatePdfAsync(uri);
    pdf.Save("out.pdf");
}).GetAwaiter().GetResult();

VB.NET applications use a similar code. Here is a snippet that shows how to convert HTML to PDF in VB.NET.

Task.Run(
    Async Function()
        Using converter = Await HtmlConverter.CreateAsync()
            Dim uri = New Uri("https://bitmiracle.com/pdf-library/html-pdf/")
            Using pdf = Await converter.CreatePdfAsync(uri)
                pdf.Save("out.pdf")
            End Using
        End Using
    End Function
).GetAwaiter().GetResult()

Download complete test projects from our GitHub repository:

Convert HTML string to PDF in C#

One of the common tasks is to generate PDF from HTML in C# or VB.NET application. The process may start with a template that the app populates with data from a database. It is not uncommon for a user of a website to create the template, the data, or both.

The auto-generated or uploaded HTML can take a form of a file or a string with the code. The add-on provides a method that accepts a file path. Use the method to convert HTML file to PDF in C# code. The following code is for the case when you have a string.

using var converter = await HtmlConverter.CreateAsync();

var html = "<body><br><br><br><h1>Hello, World</h1></body>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("out.pdf");

HTML can contain relative references to images, scripts and CSS files. To properly convert such code, you would need to use conversion options. Here is how to specify a base URL using the options:

using var converter = await HtmlConverter.CreateAsync();

var incompleteHtml = "<img src=\"/images/team.svg\"></img>";
var options = new HtmlConversionOptions();
options.Load.BaseUri = new Uri("https://bitmiracle.com/");
using var pdf = await converter.CreatePdfFromStringAsync(incompleteHtml, options);
pdf.Save("out.pdf");

Our GitHub repository contains the full test project.

Execute JavaScript before conversion

The add-on API provides a way to run a JS code before the conversion. The code can dynamically generate or modify the HTML content. For example, it can toggle elements, or to make dynamic content loading happen.

The following code shows how to delay HTML to PDF conversion until JavaScript has finished.

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
var js = @"document.body.style.backgroundColor = 'green';";
options.Start.SetStartAfterScriptRun(js);

var url = new Uri("https://google.com");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

The above snippet uses a very simple code just to illustrate the approach. For a more real-world example, check out the corresponding sample app in our GitHub repo. The app shows how to deal with a page that dynamically loads its contents. The JavaScript code in the app scrolls the page until there is no more new content. After that, the conversion to PDF happens.

Ignore SSL errors

When sending secure requests to load HTML, the add-on checks if the SSL certificate that authenticates a website's identity and enables an encrypted connection is valid and trusted.

By default, the add-on will throw an exception if the HTML to PDF converter does not trust the certificate for any reason. If you understand the risk of accepting an untrusted certificate, you can tell the add-on to bypass the checks.

var engineOptions = new HtmlEngineOptions
{
    IgnoreSslErrors = true
};
using var converter = await HtmlConverter.CreateAsync(engineOptions);

var url = new Uri("https://self-signed.badssl.com/");
using var pdf = await converter.CreatePdfAsync(url);
pdf.Save("out.pdf");

For the complete code, head over to Docotic.Pdf samples repo.

Provide password for protected pages

Some web pages require authentication to access them. When you access a secure URL that requires HTTP authentication, the browser asks you to provide username and password.

Using the conversion options, you can instruct the API to provide credentials for webpages that require login.

This C# code shows how to convert password protected HTML to PDF

using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://httpbin.org/basic-auth/foo/bar");

var options = new HtmlConversionOptions();
options.Authentication.SetCredentials("foo", "bar");

using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

Find the complete working sample in samples repo.

Wait before conversion

Delaying HTML to PDF conversion can be useful if the page keeps updating for a while after being loaded. It is often the case when dealing with dynamic content generated by JavaScript or AJAX calls.

The Acid 3 test is a perfect example of a page that would benefit from a delay before conversion. The test executes the number of checks to evaluate a browser's ability to render complex web pages correctly. These checks take time. Try changing the wait time in the following code to see how it affects the conversion results.

var options = new HtmlConversionOptions();
options.Start.SetStartAfterDelay(10 * 1000);

using var converter = await HtmlConverter.CreateAsync();
var url = new Uri("http://acid3.acidtests.org/");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

The above code shows how to convert HTML to PDF with delay. While the additional time helps with getting better results, please note that adding delays can affect performance. Insufficient delays can negatively affect the quality of the conversion. An alternative approach to using a delay is to use a script that would execute until the page is ready.

You can get the full test project in Docotic.Pdf samples repository.

Add header and footer

The HTML to PDF API can add repeatable footer / header blocks on generated pages. Converter creates the blocks from the HTML templates specified in conversion options. We recommend using inline styles and Data URIs for images inside the templates.

The converter places headers and footers inside page margins. Given that the page margins are small, the content of the header and footer may not be visible. We recommend specifying top and bottom margins explicitly. The size should match the size of the header and the footer, respectively.

See how to change HTML to PDF and add header and footer

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
options.Page.HeaderTemplate = File.ReadAllText("header-template.html");
options.Page.MarginTop = 50;

options.Page.FooterTemplate = File.ReadAllText("footer-template.html");
options.Page.MarginBottom = 50;

var url = new Uri("https://www.iana.org/numbers");
using var pdf = await converter.CreatePdfAsync(url, options);
pdf.Save("out.pdf");

The converter can insert values like the conversion date and document title in predefined places inside the templates. Check out the description of HeaderTemplate and FooterTemplate properties for more information.

The full test project and template code is in Docotic.Pdf samples repository.

Scale content

When dealing with web pages that have wide layouts, you can either increase the output PDF size or scale the content down to fit the PDF page. To better position the scaled content, you can also set up margins.

A well-scaled PDF provides a better reading experience, because its readers won't need to zoom in or out to view the content properly. If the HTML document is hard to read because of a small font size, you may scale the content up.

By default, the API produces PDFs with page size equal to A4. There are no margins and no magnification. Using the conversion options, you can change these settings.

See how to set up scaling factor and margins when generating PDF from HTML

using var converter = await HtmlConverter.CreateAsync();

var html = "<html><head><style>body { background-color: coral; margin-top: 100px;}</style></head>" +
"<body><h1>Did you notice the margins and the scale?</h1></body></html>";

var options = new HtmlConversionOptions();
options.Page.MarginLeft = 10;
options.Page.MarginTop = 20;
options.Page.MarginRight = 30;
options.Page.MarginBottom = 40;
options.Page.Scale = 1.5;

using var pdf = await converter.CreatePdfFromStringAsync(html, options);
pdf.Save("out.pdf");

Docotic.Pdf samples repository contains the complete project.

Overlay HTML onto an existing PDF

There are cases when you would like to use an existing PDF as a backdrop for the conversion result. This is possible with Docotic.Pdf and the add-on.

This method involves creating a new PDF from the HTML (the overlay content) and then merging it with the existing PDF. The final document will include both the original content and the new overlay. Here is the code that illustrates the method.

using var converter = await HtmlConverter.CreateAsync();

var options = new HtmlConversionOptions();
options.Page.SetSizeInches(4.13, 5.83);

string htmlCode =
    "<div style=\"position: absolute; top: 270px; right: 100px;\">" +
    "I would like to put this here</div>";
using var htmlPdf = await converter.CreatePdfFromStringAsync(htmlCode, options);

using var pdf = new PdfDocument("pdf-to-merge-with.pdf");
var xObj = pdf.CreateXObject(htmlPdf.Pages[0]);

pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("out.pdf");

It is important to specify a page size for the overlay. Usually, the size should be equal to the size of the page you want to overlay. Then you would need to produce the new PDF with the overlay content. Please note that the background is transparent by default. You may change the background by running a script before the conversion if needed.

It is time to open the existing PDF. This document should create an XObject from a page in the generated PDF. Then the code draws the XObject on top of the existing page.

The full test project with an example source PDF is in Docotic.Pdf samples repository.

Convert SVG to PDF in C#

Use the HTML to PDF converter to create a PDF from images with scalable vector graphics. The following code shows the simplest way to perform the conversion:

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/team.svg");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("out.pdf");

The converter uses the width and/or height specified in the SVG image to produce a high-quality output of the correct size.

You can produce an output of a different size using customization options. It is possible to add the converted image to another PDF.

Check out the full test project on GitHub.