OfficeIMO.Html.Pdf 3.2.4

OfficeIMO.Html.Pdf

OfficeIMO.Html.Pdf converts HTML directly to PDF with the same first-party layout scene used by HTML-to-PNG/JPEG/TIFF/SVG/WebP. It also converts PDF to semantic or positioned-review HTML.

The HTML-to-PDF path has no browser process, Office automation, Markdown bridge, Word bridge, or new external dependency.

Use OfficeIMO.Html.Pdf.Browser when the source is a live website or its final output depends on JavaScript or browser layout. That package asks HtmlTinkerX to capture the page, then opens the generated bytes as a normal OfficeIMO.Pdf.PdfDocument. Browser capture is explicit; this managed renderer does not fall back to Chromium automatically.

Install

dotnet add package OfficeIMO.Html.Pdf

HTML to PDF

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);
byte[] pdf = source.ToPdf();
source.SaveAsPdf("quarterly-update.pdf");

Data-driven reports and long tables

Keep data binding outside the renderer. Build finalized, encoded HTML with Razor, Scriban, Handlebars, or the template system already used by the application, then pass that HTML to HtmlConversionDocument.Parse. OfficeIMO does not execute JavaScript or template expressions while rendering.

In paged output, table cells measure and wrap through the shared layout engine. A leading <thead> and a trailing <tfoot> repeat on each table fragment. Use <tfoot> for a genuine repeating table footer; put a subtotal or grand-total card that must appear once after the table and give it break-inside: avoid.

<table>
  <thead><tr><th>Item</th><th>Qty</th><th>Amount</th></tr></thead>
  <tbody></tbody>
</table>
<section class="totals" style="break-inside:avoid">
  Total: $7,239.46
</section>

For large output, prefer SaveAsPdf(Stream, options) over ToPdf(), and select forward-only PDF object serialization when the destination need not be seekable:

using OfficeIMO.Pdf;

var options = new HtmlPdfSaveOptions {
    PdfOptions = new PdfOptions {
        FileVersion = PdfFileVersion.Pdf17,
        ObjectSerializationMode = PdfObjectSerializationMode.ForwardOnly
    }
};

using Stream destination = File.Create("purchases.pdf");
PdfSaveResult saved = HtmlConversionDocument.Parse(html).SaveAsPdf(destination, options);
Console.WriteLine(saved.Serialization?.PeakRetainedPageContentBytes);

This bounds completed PDF page and object payloads and avoids buffering the final artifact inside OfficeIMO. HTML parsing, cascading, and layout still operate on the complete document so CSS page counters, named pages, cross-page fragmentation, and other whole-document rules remain correct. PdfSerializationReport.IsForwardOnlyLayout stays false; split independently generated documents at the application boundary when a workload requires a hard end-to-end heap ceiling.

Paged-media and PDF semantics

The managed path supports named page rules, margin boxes, page counters, running strings, and running elements. It also maps headings and CSS bookmark controls to PDF outlines, maps supported semantic roles to the tagged structure tree, and marks repeated decorative margin content as PDF artifacts.

<style>
  @page {
    margin: 18mm;
    @top-center { content: element(report-header, first) }
    @bottom-right { content: "Page " counter(page) " / " counter(pages) }
  }
  .running-header { position: running(report-header) }
  section { break-after: page; -officeimo-pdf-tag-type: Sect }
  section:last-child { break-after: auto }
  h1 { bookmark-level: 1; bookmark-state: open }
  .summary { display: grid; grid-template-rows: 32px 48px }
  .summary-body { display: grid; grid-column: 1; grid-row: 1 / 3; grid-template-rows: subgrid }
  .badge { clip-path: polygon(0 0, 100% 0, 88% 100%, 0 100%) }
</style>
<header class="running-header">Quarterly report</header>
<section>
  <h1>Overview</h1>
  <div class="summary">
    <div class="summary-body"><div>Revenue</div><div>Margin</div></div>
    <div class="badge">Approved</div>
  </div>
</section>

bookmark-level:none suppresses an automatic heading outline. bookmark-label:"…" changes its outline label, and bookmark-state:open|closed controls its initial state. -officeimo-pdf-tag-type accepts the declared PDF structure roles plus artifact/none for decorative content. Invalid values keep the normal semantic behavior and produce a typed warning.

Use strict mode when the input must stay inside the declared static contract, and require the PDF-stage report as well:

var options = new HtmlPdfSaveOptions {
    FidelityPolicy = HtmlRenderFidelityPolicy.RequireNoLoss,
    PdfOptions = new OfficeIMO.Pdf.PdfOptions()
        .EnableTaggedPdfCatalogMarkers()
};

var result = HtmlConversionDocument.Parse(html).ToPdfDocumentResult(options);
result.RequireNoLoss();
result.Save("report.pdf").RequireNoLoss();

Fonts and text shaping

The dependency-light path loads policy-approved TrueType-glyf OpenType and WOFF 1 faces and provides deterministic managed Unicode, bidirectional, and bounded core-Arabic behavior. WOFF 2 transformed tables and CFF outlines are not silently substituted: font loading reports HtmlRenderFontFormatUnsupported unless the host pre-converts the face to a supported static font.

For complete OpenType GSUB/GPOS shaping, add the optional OfficeIMO.Drawing.HarfBuzz adapter and assign its provider to the same options object used by PDF and image output:

using OfficeIMO.Drawing.HarfBuzz;

var options = new HtmlPdfSaveOptions {
    TextShapingProvider = OfficeHarfBuzzTextShapingProvider.Instance,
    TextShapingLanguage = "ar"
};
options.Fonts.Add("Report Arabic", File.ReadAllBytes("ReportArabic.ttf"));

If a configured provider declines a joining-script run, OfficeIMO retains logical searchable text and reports HtmlRenderComplexTextShapingUnsupported; strict mode rejects that fallback.

Install OfficeIMO.Mhtml.Pdf when the source is an MHT/MHTML archive. That bridge adds MIME parsing and embedded-resource resolution without putting OfficeIMO.Email into ordinary HTML/PDF applications.

Naming is consistent across the direct output APIs:

• ToPdf() returns encoded bytes.
• ToPdfDocument() returns the first-party PDF model.
• ToPdfDocumentResult() returns the PDF model plus diagnostics.
• ExportImage() and ExportImages() return image output, dimensions, and diagnostics.
• SaveAsPdf(path) and SaveAsPdf(stream) write to a destination.
• Async counterparts use the same names with Async appended.

One options shape for PDF and all image formats

HtmlPdfSaveOptions derives from HtmlRenderOptions, so one configured instance can drive PDF and all five direct image outputs.

using OfficeIMO.Drawing;
using OfficeIMO.Html;
using OfficeIMO.Html.Pdf;

var options = new HtmlPdfSaveOptions {
    PageSize = OfficePageSizes.A4,
    Margins = HtmlRenderMargins.All(32),
    DefaultFontFamily = "Arial",
    BackgroundColor = OfficeColor.White,
    Scale = 1.5,
    PdfOptions = new OfficeIMO.Pdf.PdfOptions()
        .EnableTaggedPdfCatalogMarkers()
};
options.AdditionalStylesheets.Add("@page { margin: 18mm }");

HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
byte[] pdf = source.ToPdf(options);
byte[] png = source.ToPng(options);
byte[] jpeg = source.ToJpeg(options);
byte[] tiff = source.ToTiff(options);
string svg = source.ToSvg(options);
byte[] webp = source.ToWebp(options);

PDF always uses paged layout. Image output honors the selected continuous or paged render mode and page index.

Diagnostics and external resources

Options are reusable configuration and are not mutated with operation results. Request a result when diagnostics matter.

var options = new HtmlPdfSaveOptions {
    ResourcePolicy = PdfResourcePolicy.CreateTrustedHost(),
    ResourceResolver = (request, cancellationToken) =>
        Task.FromResult<HtmlResolvedResource?>(null)
};

HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
var result = await source.ToPdfDocumentResultAsync(options);
var pngResult = await source.ExportImageAsync(OfficeImageExportFormat.Png, options);
var svgResult = await source.ExportImageAsync(OfficeImageExportFormat.Svg, options);
await result.SaveAsync("report.pdf");

foreach (var warning in result.Report.Warnings) {
    Console.WriteLine($"{warning.Code}: {warning.Message}");
}

foreach (var diagnostic in pngResult.Diagnostics) {
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
}

foreach (var diagnostic in svgResult.Diagnostics) {
    Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
}

Resource resolution is opt-in. PdfResourcePolicy is the host-access gate for local files, remote resolver calls, data URIs, embedded package resources, and installed fonts. HtmlUrlPolicy independently validates URL syntax and schemes; timeouts, byte limits, count limits, and stylesheet-depth limits inherited from HtmlRenderOptions bound resources after access is granted. The balanced default allows installed fonts plus bounded data URIs and MHTML package parts, but does not call local or remote resolvers. Portable deterministic mode disables installed-font discovery explicitly.

Command-line conversion

Install OfficeIMO.Tool when a script or build pipeline is the desired surface:

dotnet tool install --global OfficeIMO.Tool
officeimo html convert report.html --output report.pdf
officeimo html convert archive.mhtml --output archive.pdf
officeimo html capabilities --format json

The command uses the same renderer and capability catalog as the .NET API. Local and remote resource reads are disabled by default; embedded data and bounded MHTML resources remain available. Standard input/output, caller stylesheets, page limits, atomic file replacement, and explicit embedded fonts for PDF/UA-ready artifacts are supported.

Explicit document projections

Direct rendering is the normal HTML-to-PDF path. If the desired target is an editable Word document or a Markdown AST, request that target explicitly and then use its PDF converter:

using OfficeIMO.Markdown.Html;
using OfficeIMO.Markdown.Pdf;
using OfficeIMO.Word.Html;
using OfficeIMO.Word.Pdf;

HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
byte[] markdownPdf = source.ToMarkdownDocument().ToPdf();

using var word = source.ToWordDocument();
byte[] wordPdf = word.ToPdf();

Those adapters remain separate packages and are not dependencies of OfficeIMO.Html.Pdf.

PDF to HTML

using OfficeIMO.Drawing;
using OfficeIMO.Html.Pdf;
using OfficeIMO.Pdf;

PdfDocument sourcePdf = PdfDocument.Open("quarterly-update.pdf");
PdfHtmlSaveOptions semanticOptions = PdfHtmlSaveOptions.CreateSemanticProfile(
    OfficeVisualThemeKind.TechnicalDocument);
string semantic = sourcePdf.ToHtml(semanticOptions);

PdfHtmlSaveOptions reviewOptions = PdfHtmlSaveOptions.CreatePositionedReviewProfile(
    OfficeVisualThemeKind.Report);
reviewOptions.ImageExportMode = PdfHtmlImageExportMode.EmbeddedDataUri;
PdfConversionReport saveReport = sourcePdf.SaveAsHtml("quarterly-review.html", reviewOptions);

PdfHtmlConversionResult reviewResult = sourcePdf.Read.Logical().ToHtmlResult(reviewOptions);
foreach (PdfConversionWarning warning in reviewResult.Report.Warnings) {
    Console.WriteLine($"{warning.Code}: {warning.Message}");
}

The named profiles emit the shared responsive OfficeIMO document shell, stable profile metadata, and adapter-owned PDF review styles. PdfHtmlConversionResult.Report and the report returned by save APIs retain the established PdfConversionReport type but are frozen snapshots (IsReadOnly is true); the mutable report used while conversion is in progress is never exposed as result state. The positioned-review profile also enables inert link and form-widget overlays. Set IncludeDefaultStyles = false to omit the theme and presentation layer. Positioned output still emits its minimal structural CSS because absolute page geometry is part of that profile's fidelity contract.

PDF-to-HTML profiles describe how an existing PDF is projected to review HTML. They are unrelated to HTML-to-PDF, which has one direct rendering path. HTML-to-PDF and HTML-to-PNG/JPEG/TIFF/SVG/WebP use the same HtmlRenderOptions scene and diagnostics; HtmlPdfSaveOptions extends that shared options type with PDF-only settings. PDF page images use OfficeIMO.Pdf's ToImage() / ToImages() API instead of routing through HTML. An image is embedded into HTML as a resource; turning image pixels into document structure is an OCR workflow, not an image-rendering profile.

Semantic output uses the shared crop-, rotation-, spanning-band-, and column-aware PDF reading order by default. Set PdfHtmlSaveOptions.UseSharedPageReadingOrder = false only when source sequence is deliberately preferred; positioned-review output always retains source geometry.

Targets and license

• Targets: netstandard2.0, net8.0, net10.0.
• License: MIT.
• Repository: EvotecIT/OfficeIMO

Dependency footprint

• External: None beyond AngleSharp/AngleSharp.Css already isolated in OfficeIMO.Html; no browser process or native HTML renderer.
• OfficeIMO: OfficeIMO.Html, OfficeIMO.Pdf, and OfficeIMO.Core own layout, rendering, reverse projection, and reports.

See the complete OfficeIMO package map for related formats and conversion paths.