OfficeIMO.Html 2.0.1

OfficeIMO.Html

OfficeIMO.Html contains the shared HTML parser, resource policy, layout scene, and direct PNG/SVG rendering APIs used by OfficeIMO converters.

It owns the reusable parts that should behave consistently across HTML-to-Markdown, HTML-to-Word, HTML-to/from-RTF, and HTML-backed PDF workflows:

• URL policy evaluation and base URI resolution
• AngleSharp document parsing helpers
• DOM traversal facts and node/depth limit tracking
• image source discovery for img, lazy-loading attributes, srcset, and picture/source
• image data URI parsing and media-type extension mapping
• dependency-free HTML layout for continuous and paged output
• direct PNG and SVG export over OfficeIMO.Drawing
• semantic HTML to/from RTF conversion over the dependency-free OfficeIMO.Rtf model

Markdown, Word, Excel, PowerPoint, RTF, and PDF models remain in their owning packages. Those projections are explicit: for example, HTML becomes a WordDocument through ToWordDocument() and a MarkdownDoc through ToMarkdownDocument().

Direct HTML rendering

using OfficeIMO.Drawing;
using OfficeIMO.Html;

string html = "<h1>Status</h1><p>Generated by OfficeIMO.</p>";
HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
var options = new HtmlRenderOptions {
    ViewportWidth = 720,
    Margins = HtmlRenderMargins.All(24),
    Scale = 1.5
};

byte[] png = source.ToPng(options);
string svg = source.ToSvg(options);

OfficeImageExportResult pngSave = source.SaveAsPng("status.png", options);
OfficeImageExportResult svgSave = source.SaveAsSvg("status.svg", options);

Dependency footprint

• External: AngleSharp and AngleSharp.Css for DOM and CSS parsing.
• OfficeIMO: OfficeIMO.Drawing and OfficeIMO.Rtf. Resource policy, layout scene, rendering, and format mappings are first-party.

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

ToPng() and ToSvg() return in-memory output. ExportImage() and ExportImages() return encoded output plus dimensions and diagnostics. SaveAsPng() and SaveAsSvg() write to a file or stream and return the same structured evidence.

Add OfficeIMO.Html.Pdf for direct PDF output. HtmlPdfSaveOptions derives from HtmlRenderOptions, so the same configured instance can be used for PDF, PNG, and SVG.

using OfficeIMO.Html.Pdf;

var options = new HtmlPdfSaveOptions {
    Margins = HtmlRenderMargins.All(32)
};

byte[] pdf = source.ToPdf(options);
byte[] png = source.ToPng(options);
string svg = source.ToSvg(options);

RTF Bridge

using OfficeIMO.Html;

RtfDocument document = "<p>Hello <strong>RTF</strong></p>".ToRtfDocument();
string rtf = document.ToRtf();
var webOptions = RtfToHtmlOptions.CreateWebSafeProfile();
RtfToHtmlResult result = document.ToHtmlResult(webOptions);
string html = result.RequireValue();
result.Report.RequireNoLoss();

RTF-to-RTF editing in OfficeIMO.Rtf remains the lossless preservation path. The HTML bridge is semantic: it preserves supported text, inline formatting, links, lists, tables, bookmarks, fields, form fields, notes, tracked revisions, object metadata, shape metadata, and embedded PNG/JPEG images without Office/COM automation.

The web-safe profile is the default publishing boundary: only allowed web/mail URLs are emitted, private data-officeimo-rtf-* metadata is disabled, and image payloads require an explicit resolver. Use RtfToHtmlOptions.CreateRoundTripProfile() only for trusted OfficeIMO round trips; it can carry private metadata and embedded binary data and should not be published without sanitization.

URL Policy

var policy = HtmlUrlPolicy.CreateWebOnlyProfile();
string href = HtmlUrlPolicyEvaluator.ResolveUrl(
    "/docs/start.html",
    new Uri("https://example.com/"),
    policy);

Parsing And Base URIs

var document = HtmlDocumentParser.ParseDocument(html);
Uri? baseUri = HtmlDocumentParser.ResolveEffectiveBaseUri(
    document,
    new Uri("https://example.com/articles/"));

Traversal Limits

HtmlDomLimitTracker? tracker = HtmlDomLimitTracker.Create(
    maxHtmlNodes: 10000,
    maxHtmlDepth: 64);

Converter packages use these primitives to keep bounded HTML ingestion behavior consistent while still reporting converter-specific diagnostics.

Shared Diagnostics And Gallery Contracts

var report = new HtmlDiagnosticReport();
report.Add("OfficeIMO.Word.Html", "HtmlCommentSkipped", "Comment skipped");

var scenario = new HtmlCapabilityGalleryScenario(
    "quarterly-report",
    "Quarterly Report",
    "Word HTML",
    "HTML import, DOCX validation, and round-trip export proof");

HtmlDiagnosticReport and the capability-gallery contracts provide a common shape for HTML converters, PDF bridges, readers, tests, and documentation generators.

Native adapters use HtmlConversionResult<TArtifact> when callers need conversion evidence. Each diagnostic has a stable code, severity, and LossKind (Approximation, Omission, or Failure). Convenience methods still return the native artifact directly; they throw HtmlConversionException when required semantic content is missing. Result methods retain the artifact and diagnostics so applications can decide how to handle the failure.

Conversion Document And Normalized HTML

var conversion = HtmlConversionDocumentBuilder.Build(html, new HtmlConversionDocumentOptions {
    Profile = HtmlConversionProfile.Document,
    Trust = HtmlInputTrust.Untrusted,
    BaseUri = new Uri("https://example.com/reports/"),
    UrlPolicy = HtmlUrlPolicy.CreateWebOnlyProfile()
});

string normalized = conversion.NormalizedHtml;
var resources = conversion.ResourcePlan.GetSummary(HtmlResourceKind.Image);
var styles = conversion.StyleSummary;

HtmlConversionDocument is the shared conversion contract for OfficeIMO HTML workflows. It parses once and keeps the source DOM, policy-normalized adapter DOM, logical document model, computed-style summary, resource manifest, resource dependency plan, normalized HTML, profile contract, and caller-assigned trust boundary.

Target packages accept this shared document while keeping target-specific conversion in their owning packages. The prepared DOM can be sent to Word, Markdown, RTF, PDF, PNG, and SVG without reparsing it for every adapter. Excel and PowerPoint accept prepared documents when the HTML contains their semantic sheet or slide envelopes.

Conversion profile and trust are separate decisions. A Document or HighFidelityPrint profile does not make external resources trusted. Leave Trust as Untrusted for user-supplied HTML; set it to Trusted only when the caller controls the document and resource locations.

Normalized HTML output is policy-aware: URL-bearing attributes are resolved against the configured base URI, disallowed URLs are removed, boolean attributes are normalized, event-handler attributes are stripped by default, and non-document executable elements are skipped. It is intended for clean review, gallery proof, and downstream adapter input selection, not for pretending OfficeIMO is a browser layout engine.

Image Sources

string source = HtmlImageSourceResolver.ResolveImageSource(
    imageElement,
    baseUri,
    HtmlUrlPolicy.CreateOfficeIMOProfile());

Image Data URIs

if (HtmlImageDataUri.TryParse(source, out var dataUri) && dataUri.IsBase64) {
    byte[] bytes = dataUri.DecodeBytes();
    string extension = dataUri.FileExtension;
}