OfficeIMO.Html.Pdf 3.4.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.ToPdfBytes();
source.SaveAsPdf("quarterly-update.pdf");

A prepared HTML report can be exported directly to a file:

var report = HtmlConversionDocument.Load("service-review.html");
report.SaveAsPdf("service-review.pdf").RequireSuccess();

The multi-format report example also exports editable Word and Excel artifacts from the same prepared source.

Review every rendered page

The capability gallery saves the input HTML, PDF, and image previews from one resolved layout. Each artifact has a SHA-256 hash and its own diagnostics. Image evidence records source page numbers, pixel dimensions, and format validation; PDF evidence runs the configured readback checks against the exact serialized bytes.

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

var gallery = new HtmlRenderCapabilityGalleryOptions(new HtmlCapabilityGalleryScenario(
    "quarterly-update", "Quarterly update", "Reports", "Paged report export")) {
    PreviewAllPages = true
};
gallery.PreviewFormats.Add(OfficeImageExportFormat.Webp);
gallery.PdfProofOptions.RequiredTextMarkers.Add("Quarterly update");
HtmlCapabilityGalleryManifest manifest = source.SaveRenderCapabilityGallery("review", gallery);

PNG and SVG are included by default; JPEG, TIFF, and WebP can also be selected. The shared output-count, total-raster-pixel, and total-encoded-byte budgets apply across all selected page/format previews. The rendering deadline includes preview production; the cancellation overload also accepts a caller token. PreviewAllPages = false retains the selected-page preview filenames and uses PreviewPageIndex. Free-text Expectations are declarations, not test results. Executed checks appear under each artifact's Evidence.Checks; a passed readback or format check does not establish visual equivalence to a browser or source application.

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 ToPdfBytes(), and select forward-only PDF object serialization when the destination need not be seekable:

using OfficeIMO.Pdf;

var options = new HtmlToPdfOptions {
    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 HtmlToPdfOptions {
    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 first-party font engine loads policy-approved TrueType-glyf OpenType, WOFF 1, CFF/CFF2, and TrueType or CFF2 variable fonts. Single-face WOFF 2 decoding is built in on .NET 8 and newer; extract and register individual faces from WOFF 2 font collections. Static faces remain eligible for PDF embedding; variable instances and shaped results that cannot use the scalar PDF text path are rendered as vector outlines plus logical ActualText, preserving extraction and accessibility.

PDF outline expansion is fail-closed. The selected program must implement IOfficeBoundedFontProgram; conversion carries cancellation into contour expansion and enforces MaxOutlinedTextCharactersPerRun plus the operation-wide MaxOutlinedTextPathCommands budget. The defaults are 16,384 UTF-16 characters per run and 1,000,000 path commands per conversion. Raise them only for trusted inputs.

No font-program package or license key is required. Select variable-font axes on the font collection before conversion:

using System.Collections.Generic;
using OfficeIMO.Drawing;
using OfficeIMO.Html.Pdf;

var options = new HtmlToPdfOptions();
options.Fonts.FontVariationResolver = request =>
    request.FamilyName == "Report Variable"
        ? new Dictionary<string, float> {
            ["wght"] = 720,
            ["wdth"] = 110
        }
        : null;

options.MaxOutlinedTextCharactersPerRun = 16_384;
options.MaxOutlinedTextPathCommands = 1_000_000;

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 HtmlToPdfOptions {
    TextShapingProvider = OfficeHarfBuzzTextShapingProvider.Instance,
    TextShapingLanguage = "ar"
};
options.Fonts.Add("Report Arabic", File.ReadAllBytes("ReportArabic.ttf"));

If no configured provider accepts a run that requires provider-owned complex shaping, OfficeIMO retains logical searchable text and reports HtmlRenderComplexTextShapingUnsupported; strict mode rejects that fallback, including outlined-font output.

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:

• ToPdfBytes() 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

HtmlToPdfOptions 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 HtmlToPdfOptions {
    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.ToPdfBytes(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 HtmlToPdfOptions {
    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().ToPdfBytes();

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

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.Load("quarterly-update.pdf");
PdfToHtmlOptions semanticOptions = PdfToHtmlOptions.CreateSemanticProfile(
    OfficeVisualThemeKind.TechnicalDocument);
semanticOptions.ReadOptions = new PdfReadOptions {
    PageSelection = PdfPageSelection.Parse("1-20"),
    Pipeline = new PdfUnderstandingPipelineOptions { MaxPages = 20 }
};
string semantic = sourcePdf.ToHtml(semanticOptions);

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

PdfHtmlConversionResult reviewResult = sourcePdf.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.

Choose semantic HTML when readable headings, paragraphs, lists, and tables matter most. Choose positioned review when page geometry and visual comparison matter most. Semantic output reports its unavoidable reflow as a typed approximation. Both profiles report omitted vectors, images, links, forms, annotations, and outlines as typed omissions when the selected profile or options cannot represent them. Report.HasLoss and RequireNoLoss() therefore provide a strict acceptance gate; ordinary semantic conversion is expected to report approximation rather than claim pixel fidelity.

PdfHtmlImageExportMode.PlaceholderOnly retains readable image metadata but omits the source pixels and reports that omission. EmbeddedDataUri embeds supported image files within the configured byte and output-size limits and reports any fallback to a placeholder. Fully transparent and unplaced resources are suppressed, while images whose clips, soft masks, unresolved transparency masks, or unsupported blend modes could reveal hidden pixels are represented without the raw data URI and reported as typed omissions. Supported opacity and blend modes are mapped to CSS with diagnostics where browser compositing can differ from PDF compositing.

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; HtmlToPdfOptions 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.

When the source is an opened PdfDocument, positioned review uses the shared PDF drawing renderer to retain supported vector artwork, clipping, paint order, images, and embedded fonts as an embedded SVG image. Text remains selectable. Browser font substitution can affect text whose fonts are unavailable, and renderer diagnostics appear in the conversion report.

Already-read logical documents use the logical positioned projection because they do not retain the original drawing resources. Opened documents also use that projection for pages with form widgets, restricted reading-order projection, or image settings that require placeholders, omission, or a smaller byte limit. OCR-only pages keep the visual appearance layer and add a transparent searchable text overlay. Check the report for content that could not be reproduced; positioned review is not a guarantee of identical appearance for every PDF.

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

PdfToHtmlOptions.ReadOptions configures the canonical semantic read for an opened PdfDocument. Existing PageRanges take precedence over ReadOptions.PageSelection; the profile, layout, and semantic budgets still come from ReadOptions. The setting is ignored when the source is already a PdfDocumentReadResult.

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.

Generated capability summary

This table is generated from the package-neutral OfficeIMO operation catalog. The detailed source contracts remain authoritative for feature-level behavior and limitations.

The complete rows for OfficeIMO.Html.Pdf are published in the generated operation contract.