# Convert HTML to PDF

Convert HTML pages and reports to PDF in .NET without a browser, with page size, margins, extra CSS, headers and footers, and local images and fonts.

**Packages**

- [OfficeIMO.Html](https://www.nuget.org/packages/OfficeIMO.Html) `dotnet add package OfficeIMO.Html`
- [OfficeIMO.Html.Pdf](https://www.nuget.org/packages/OfficeIMO.Html.Pdf) `dotnet add package OfficeIMO.Html.Pdf`

**Works with**

- .NET
- [PowerShell](/docs/pswriteoffice/install/) `Install-Module PSWriteOffice`
- [CLI](/docs/cli/install/) `dotnet tool install --global OfficeIMO.Tool`

**Target frameworks**

netstandard2.0, net8.0, net10.0, net472

**APIs**

- [`HtmlConversionDocument`](/api/html/officeimo-html-htmlconversiondocument/)
- [`HtmlPdfExportOptions`](/api/html-pdf/officeimo-html-pdf-htmlpdfexportoptions/)
- [`HtmlRenderFidelityPolicy`](/api/html/officeimo-html-htmlrenderfidelitypolicy/)
- [`HtmlRenderOptions`](/api/html/officeimo-html-htmlrenderoptions/)
- [`HtmlConversionDocumentOptions`](/api/html/officeimo-html-htmlconversiondocumentoptions/)
- [`HtmlInputTrust`](/api/html/officeimo-html-htmlinputtrust/)
- [`HtmlRenderMargins`](/api/html/officeimo-html-htmlrendermargins/)
- [`OfficeConversionReport`](/api/core/officeimo-officeconversionreport/)
- [`OfficeDiagnostic`](/api/core/officeimo-officediagnostic/)
- [`OfficePageSizes`](/api/core/officeimo-drawing-officepagesizes/)
- [`PdfCreateOptions`](/api/pdf/officeimo-pdf-pdfcreateoptions/)
- [`PdfObjectSerializationMode`](/api/pdf/officeimo-pdf-pdfobjectserializationmode/)

**Cmdlets**

- [`Convert-OfficeDocument`](/api/powershell/convert-officedocument/)
- [`New-OfficeHtmlPdfOptions`](/api/powershell/new-officehtmlpdfoptions/)

**Commands**

- [`officeimo html convert`](/docs/cli/html/)

**Limits**

The renderer lays out static HTML and CSS; it does not run JavaScript, so pages that build their content in script need a browser capture first. [OfficeIMO.Html support matrix](/compatibility/#package-html), [OfficeIMO.Html.Pdf support matrix](/compatibility/#package-html-pdf)

**Verified**

Examples compiled against the source on 2026-11-14

**Data**

- [OfficeIMO.Html API index](/api/html/index.json)
- [OfficeIMO.Html.Pdf API index](/api/html-pdf/index.json)
- [PSWriteOffice command catalog](/data/powershell/commands.json)
- [CLI command catalog](/data/cli/commands.json)
- [Capability catalog (JSON)](/data/capabilities.json)

`OfficeIMO.Html.Pdf` lays out HTML and CSS with the managed OfficeIMO renderer and writes the result through `OfficeIMO.Pdf`. No browser, Office or native library is involved. Parse or load the page into an `HtmlConversionDocument`, then call `SaveAsPdf` or `ToPdf`. Options live on `HtmlPdfExportOptions`, which extends the `HtmlRenderOptions` used for image export, so one options object can drive both.

Build the HTML with whatever template engine you already use (Razor, Scriban, string templates) and pass the finished markup in; OfficeIMO does not evaluate script or template expressions.

```sh
dotnet add package OfficeIMO.Html.Pdf
```

## Convert an HTML string or file to PDF

### C#

```csharp
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;

string html = """
<h1>Quarterly update</h1>
<p>Generated directly by OfficeIMO.</p>
<table>
  <tr><th>Area</th><th>Status</th></tr>
  <tr><td>PDF</td><td>Green</td></tr>
</table>
""";

HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
source.SaveAsPdf("quarterly-update.pdf");

byte[] bytes = source.ToPdf().ToBytes();
Console.WriteLine($"{bytes.Length} bytes");
```

### PowerShell

```powershell
Convert-OfficeDocument -Path .\Report.html -OutputPath .\Report.pdf

'<h1>Review</h1>', '<p>Approved.</p>' |
    Convert-OfficeDocument -Text { $_ } -From Html -To Pdf -OutputPath .\Review.pdf
```

### CLI

```sh
officeimo html convert report.html --output report.pdf
```

## Set page size, margins and extra CSS

`PageSize` and `Margins` set the default sheet. Authored `@page` rules win unless you set `HonorCssPageRules = false`. Stylesheets in `AdditionalStylesheets` are applied after the page's own CSS, which is the place for house styles.

### C#

```csharp
using OfficeIMO.Drawing;
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;

var options = new HtmlPdfExportOptions {
    PageSize = OfficePageSizes.A4,
    Margins = HtmlRenderMargins.All(36),
    DefaultFontFamily = "Arial",
    MaxPageCount = 200
};
options.AdditionalStylesheets.Add("body { color: hsl(215 35% 20%) } h1 { border-bottom: 1px solid #ccc }");

HtmlConversionDocument
    .Parse("<h1>Invoice</h1><p>Thank you for your order.</p>")
    .SaveAsPdf("invoice.pdf", options);
```

### PowerShell

```powershell
$options = New-OfficeHtmlPdfOptions -Margin 2cm -Font 'Arial'
Convert-OfficeDocument -Path .\Report.html -To Pdf -OutputPath .\Report.pdf -Options $options
```

### CLI

```sh
officeimo html convert report.html --output report.pdf --stylesheet print.css --max-pages 200
```

## Add page numbers, headers and footers

Paged output supports `@page` margin boxes with `counter(page)` and `counter(pages)`, and running elements with `position: running(name)` and `content: element(name)`. Repeated margin content is tagged as a PDF artifact, so it does not clutter the document structure. A leading `<thead>` repeats on every page a table spans.

### C#

```csharp
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;

string html = """
<style>
  @page {
    margin: 20mm;
    @top-left { content: "Purchase report"; font-size: 9pt; }
    @bottom-right { content: "Page " counter(page) " of " counter(pages); font-size: 9pt; }
  }
</style>
<h1>Purchases</h1>
<table>
  <thead><tr><th>Item</th><th>Qty</th></tr></thead>
  <tbody>
    <tr><td>Paper</td><td>12</td></tr>
    <tr><td>Toner</td><td>3</td></tr>
  </tbody>
</table>
""";

HtmlConversionDocument.Parse(html).SaveAsPdf("purchases.pdf");
```

## Load local images, stylesheets and fonts

By default, conversion reads no local files and makes no network calls; data URIs still work. For your own trusted templates, load the file with a base URI and allow local files through the PDF resource policy.

### C#

```csharp
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;
using OfficeIMO.Pdf;

Directory.CreateDirectory("site");
File.WriteAllText(Path.Combine("site", "site.css"), "h1 { color: navy }");
File.WriteAllText(Path.Combine("site", "index.html"),
    "<link rel=\"stylesheet\" href=\"site.css\"><h1>Team handbook</h1>");

HtmlConversionDocument page = HtmlConversionDocument.Load(Path.Combine("site", "index.html"), new HtmlConversionDocumentOptions {
    Trust = HtmlInputTrust.Trusted,
    BaseUri = new Uri(Path.GetFullPath("site") + Path.DirectorySeparatorChar)
});

page.SaveAsPdf("handbook.pdf", new HtmlPdfExportOptions {
    ResourcePolicy = PdfResourcePolicy.CreateTrustedHost()
});
```

### PowerShell

```powershell
$options = New-OfficeHtmlPdfOptions -IncludeLocalResources
Convert-OfficeDocument -Path .\site\index.html -To Pdf -OutputPath .\handbook.pdf -Options $options
```

### CLI

The CLI reads no local or remote resources. Supply fonts and stylesheets explicitly:

```sh
officeimo html convert index.html --output handbook.pdf --stylesheet site.css --font-family "Noto Sans" --font-regular NotoSans-Regular.ttf --font-bold NotoSans-Bold.ttf
```

## Check what the conversion changed

The PDF result carries a conversion report. Warnings name images that did not load, fonts that were substituted and CSS that was simplified. Set `FidelityPolicy = HtmlRenderFidelityPolicy.FailOnLoss` to stop instead of writing an approximate PDF.

### C#

```csharp
using OfficeIMO;
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;

HtmlConversionDocument source = HtmlConversionDocument.Parse(
    "<h1>Status</h1><img src=\"https://example.com/chart.png\" alt=\"Chart\">");

OfficeConversionReport report = source.SaveAsPdf("status.pdf", new HtmlPdfExportOptions());

Console.WriteLine($"Loss reported: {report.HasLoss}");
foreach (OfficeDiagnostic diagnostic in report.Diagnostics) {
    Console.WriteLine($"{diagnostic.Severity} {diagnostic.Code}: {diagnostic.Message}");
}
```

## Write large reports to a stream

For long tables, write to a stream with forward-only object serialization so OfficeIMO does not buffer the finished file.

### C#

```csharp
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;
using OfficeIMO.Pdf;

var rows = string.Concat(Enumerable.Range(1, 2000).Select(i => $"<tr><td>Item {i}</td><td>{i * 3}</td></tr>"));
string html = $"<table><thead><tr><th>Item</th><th>Amount</th></tr></thead><tbody>{rows}</tbody></table>";

var options = new HtmlPdfExportOptions {
    PdfOptions = new PdfCreateOptions {
        ObjectSerializationMode = PdfObjectSerializationMode.ForwardOnly
    }
};

using Stream destination = File.Create("large-report.pdf");
HtmlConversionDocument.Parse(html).SaveAsPdf(destination, options);
```

<!-- PowerForge markdown source sha256:9780BDE098AF20C0E65F37145AC0BA34400306D9A91C962615C98875257C336A; title=True -->

<!-- PowerForge markdown artifact sha256:D99D74453847EA3E17AA108CBC7B2C9B665918C5BEE866266EF6952CA2599490 -->
