OfficeIMO.Html.Pdf 3.5.1

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

ToPdfBytes() preserves the established print-paged behavior. Use an explicit render request when the PDF should follow another layout contract:

using OfficeIMO.Drawing;

var options = new HtmlToPdfOptions {
    ViewportWidth = 816,
    PageSize = OfficePageSizes.A4,
    Margins = HtmlRenderMargins.All(24)
};

HtmlPdfRenderRequestResult print = source.RenderToPdfResult(
    HtmlRenderRequest.Create(
        HtmlRenderIntentProfile.PrintPaged,
        HtmlRenderEncoder.Pdf,
        options));

HtmlPdfRenderRequestResult screenReflow = source.RenderToPdfResult(
    HtmlRenderRequest.Create(
        HtmlRenderIntentProfile.ScreenMediaPaged,
        HtmlRenderEncoder.Pdf,
        options));

HtmlPdfRenderRequestResult screenSnapshot = source.RenderToPdfResult(
    HtmlRenderRequest.Create(
        HtmlRenderIntentProfile.ScreenSnapshotPaged,
        HtmlRenderEncoder.Pdf,
        options));

byte[] pdf = screenSnapshot.ToBytes();
double firstSliceOffset = screenSnapshot.RenderResult.Surfaces[0].SourceOffsetY;

The same request may override CSS media, layout surface, or pagination through WithCssMedia(...), WithLayoutSurface(...), and WithPagination(...). Use WithLayout(...) or WithAxes(...) when coupled geometry axes must change atomically. Such a custom combination is reported as unqualified unless its effective axes still exactly match the named profile.

Print paged applies print CSS and normal fragmentation. Screen-media paged keeps screen CSS while reflowing into page sheets. Screen-snapshot paged preserves one continuous screen composition and then slices it into fixed canvases. The latter can split elements at page boundaries. The explicit result retains page order, dimensions, source offsets, clipping, requested scale and background, provider identity, and HTML loss diagnostics alongside the combined PDF conversion report. For stitched output, SourcePlacements preserves every contributing source page or slice and its output offset. Layout, projection, and PDF encoding share one operation deadline.

For a wide print layout that should fit a fixed paper size, set a CSS layout width explicitly. The PDF keeps the physical PageSize; content and margins are scaled uniformly after layout. This changes wrapping and page breaks, so choose the width for the source rather than assuming one width fits every page. CSS media queries and responsive resources still use the captured ViewportWidth.

var fitted = new HtmlToPdfOptions {
    PageSize = OfficePageSizes.A4,
    Margins = HtmlRenderMargins.All(24),
    HonorCssPageRules = false,
    PrintLayoutWidthCssPixels = 1200
};
byte[] fittedPdf = source.ToPdfBytes(fitted);

Fitting applies to print-paged reflow. When HonorCssPageRules is true, the PDF keeps the resolved authored @page size and margins, and fits the chosen layout width inside their printable area. For example, a source with a min-width: 1400px print layout and @page { size: 330mm 427mm; margin: .75in .5in } can use PrintLayoutWidthCssPixels = 1400 without replacing the authored sheet. An explicit width must exceed the printable area. By default, PDF conversion also fits visible layout overflow, including fixed-width descendants, tables and root minimum widths, within a uniform authored sheet. Hidden or scroll-clipped containers and paint-only shadows do not expand the fitting width. Root overflow propagated from html or body clips the final viewport and permits print fitting of the underlying layout. Fixed-position boxes use the page area inside its margins and repeat on each page. CSS media queries retain the physical print context during reflow. Named or page-specific @page rules still need an explicit PrintLayoutWidthCssPixels. Set AutoFitWidePrintContent = false to keep the unscaled print layout. Automatic fitting includes positioned content outside the original sheet; disable it when that content should remain outside a fixed print surface. The retained render result uses the wider CSS page dimensions; the PDF is the scaled paper-size artifact.

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.

ZIP site bundles

Load a ZIP website through OfficeIMO.Html.HtmlSiteBundle and render it with the same explicit PDF intent used for an HTML document:

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

using Stream source = File.OpenRead("saved-site.zip");
HtmlSiteBundle bundle = await HtmlSiteBundle.LoadAsync(source);
HtmlPdfRenderRequestResult result = await bundle.RenderToPdfResultAsync(
    HtmlRenderRequest.Create(HtmlRenderIntentProfile.PrintPaged, HtmlRenderEncoder.Pdf));
File.WriteAllBytes("saved-site.pdf", result.ToBytes());

The result retains the selected HTML surfaces and combined conversion report. Archive images, CSS and fonts require ResourcePolicy.AllowEmbeddedPackageResources. Local files and remote resources remain governed by their separate PDF permissions and an explicitly supplied resolver; loading a ZIP does not enable either permission. The bundle loader owns entry selection, input limits, integrity checks and archive resource identities.

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

Flex content keeps its source hierarchy in the tagged reading order when CSS order, reverse directions or pagination change where it is painted. Repeated table headers and continued list/table content retain their semantic ancestors across pages. This preserves logical ownership without changing the visual layout; manual assistive-technology review remains a separate accessibility requirement.

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. Presentation MathML keeps its vector paint and searchable logical text inside a tagged Formula container. Its description follows the shared accessible-name resolution, then alttext, then the logical expression. Tagged formulas carry UTF-8 application/mathml+xml associated-file supplements. Exact original standalone MathML survives document cloning and unrelated edits; changed or recovered formulas carry current namespace-aware MathML with a normalization diagnostic. Hidden formulas and untagged output do not emit formula attachments. These associations select PDF 2.0, or PDF 1.7 when configured PDF/A-3 groundwork permits them. Association metadata alone does not establish PDF/A or PDF/UA conformance.

An explicit standalone PDF/UA-1 request cannot retain these Formula attachments: PDF/UA-1 requires PDF 1.7, while native structure-associated files require PDF 2.0. RequireCompliance(PdfComplianceProfile.PdfUa1) rejects that combination before writing output. Setting FileVersion to Pdf17 does not override the attachment requirement. The converter never drops MathML or changes the requested profile automatically. Callers needing both PDF/UA-1 and the source supplements can explicitly configure PDF/A-3 groundwork alongside PDF/UA-1, provide MathMlSourceModificationDate and embedded fonts, and validate the resulting bytes against both profiles. A PDF 2.0 profile is a separate caller choice and requires its own qualification.

Column notes retain note bodies as Note elements with unique IDs. Linked call markers remain in their originating paragraph, and return links remain in the note. The logical body follows column flow; notes follow the body of the page on which they start, with continuations belonging to the same note. These structural guarantees do not replace assistive-technology reading-order review.

Set HtmlToPdfOptions.MathMlSourceModificationDate when an archival profile requires a modification date for embedded sources. The renderer does not invent dates.

<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, including supported OpenType features. Color glyphs and feature-bearing color fonts retain palette-aware outlines. Variable instances and text that requires vector paint use outlines plus logical ActualText, preserving extraction and accessibility.

PDF outline expansion remains bounded. 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. A run above the character limit still fails. If the path-command budget is exhausted, conversion stops outlining and uses PDF text for the remaining runs, with a loss-bearing HtmlPdfFontOutlineBudgetApproximated warning because font appearance or shaping may differ. Raise the outline budget only for trusted inputs. Outline-only private-use symbols encountered after exhaustion are omitted with HtmlPdfUnavailablePrivateUseGlyphOmitted, rather than passed to an incompatible PDF text font.

HTML body text and SVG text share font discovery, including nested SVG viewports, effect groups and tiling patterns. Fonts registered through options.Fonts are available to layout and PDF encoding in those groups. Automatic installed-font fallback follows ResourcePolicy for both HTML and SVG text; CreatePortableDeterministic() requires explicit in-memory or allowed document fonts. Already registered style faces in the requested family remain eligible when the nominal face lacks a glyph. If the selected fonts cannot encode painted text, PDF conversion throws HtmlConversionException with the encoding diagnostics before returning a generated document. Logical ActualText and accessibility labels do not require painted-glyph coverage.

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

Hosts that ship the OfficeIMO portable browser font set can activate its layout aliases, fallback order, PDF embedding, and substitutions through one reusable profile. The profile does not embed or download fonts; the host remains responsible for supplying pinned and licensed bytes:

HtmlPortableBrowserFontProfile fonts = HtmlPortableBrowserFontProfile.Create(
    "my-portable-fonts-v1",
    fileName => File.ReadAllBytes(Path.Combine(fontDirectory, fileName)));

HtmlToPdfOptions options = fonts.CreateHtmlOptions(
    OfficeHarfBuzzTextShapingProvider.Instance);

The same options instance can drive screen images, browser-print PDF, and screen-to-page PDF so layout and encoded output use the same fonts.

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.

Under the balanced policy, MathML can use the renderer's fixed mathematical font families when a supported installed face is available. CSS cannot use that fallback list to select another named host font. AllowDocumentFontEmbedding still gates document-selected host families and installed system-UI lists. Disable AllowSystemFontEmbedding or AllowSystemFontFallback to prevent installed math font loading, or supply an in-memory math face for portable output. Font loading retains the shared source-byte, decoded-byte and cancellation limits.

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.