HTML import and export

HTML reads into the word-processing hub and the hub writes it back. Both directions report what they could not carry.

using Document doc = Document.Open("page.html");            // sniffed by content: <!DOCTYPE html>, <html>, <head>, <body> or a tag such as <p>, <h1>, <table>
using Document frag = Document.FromHtml("<h1>Title</h1><p>Hello <b>world</b></p>");
LossReport? lost = doc.ImportLoss;                        // scripts, handlers, unsafe links, forms, frames, external images ...
Office.Convert("page.html", "page.docx");                 // and "page.docx" -> "page.html"
string html = doc.ToHtml();                               // a page; new HtmlExportOptions { Fragment = true } for the content only
doc.SaveAsHtml("out.html", new HtmlExportOptions { ImageSink = i => { File.WriteAllBytes(i.SuggestedName, i.Data.ToArray()); return i.SuggestedName; } });

Workbook.ToHtml and Presentation.ToHtml (and SaveAs("x.html") on them) write a basic export, below.

Import

The page is parsed as a browser parses it (OneHtml: encoding from the byte-order mark or meta, tree construction, error recovery) and its cascade (user-agent rules, style elements, style attributes, legacy attributes such as align, bgcolor, border, font) supplies a computed style per element. The importer reads those computed values; it does not interpret CSS itself. The result is an in-memory DOCX package that the hub wraps.

White space collapses as CSS says (runs of white space become one space, leading space in a block and trailing space at its end are dropped, a space between inline elements is kept once).

Sanitising

Import is HtmlSanitization.Strict unless told otherwise. Nothing is ever executed or fetched. Each of these is left out and reported once per occurrence in the loss report and as an html.dropped defect with the text position of the element:

HtmlImportOptions.Sanitization = HtmlSanitization.KeepInert keeps the raw-but-safe superset: the text of form controls (button labels, field values, option text) and the fallback text of frames and objects as plain text, and links with other schemes. It never admits scripts, handlers or javascript:, vbscript:, data:, blob: and file: targets, because a document cannot hold them. HtmlImportOptions.ImageResolver is the only way an external img is read: the importer hands it the src as written and uses the bytes it returns; it never opens a URL itself.

Limits

OfficeLimits.MaxPartSize bounds the input; MaxXmlDepth bounds element nesting (the parser stops at that many open elements with an OfficeLimitException) and the importer's recursion; MaxXmlAttributeCount bounds attributes per tag; MaxRecordCount bounds the cells of one sheet in the workbook export. Embedded pictures are bounded by MaxPartSize. The importer reads no file, no URL and no style sheet it was not given.

Templates

The template engine's html tag runs on this importer: the same parse, cascade and sanitising, flattened to the small vocabulary a tag can insert into an existing document (paragraphs, headings, bold, italic, underline, strike, code, links, breaks, quotes and nested lists). Tables, pictures and colours in the value are dropped and reported as template.markup-dropped.

Export

Document.ToHtml writes UTF-8 HTML5, deterministic and self-contained:

The style sheet puts white-space: pre-wrap on paragraph elements, so the spaces and breaks of the document are exactly those of the HTML.

Not written, each a loss item on Document.ExportLoss: loss.html-headers-footers (HTML has no pages), loss.html-comments, loss.html-revisions (deleted text; inserted text is written as plain text), loss.html-equations (plain text), loss.html-charts, loss.html-drawings (shapes, SmartArt, OLE objects without a picture), loss.html-floating-pictures (written in the line), loss.html-text-boxes, loss.html-metafile, loss.html-unsafe-link.

The page this writes reads back with Document.FromHtml to the same text, the same headings and styles, the same lists (levels, kinds, starts), the same tables (grid, spans, merges, header rows, shading) and the same bookmarks and links. Notes come back as an ordered list at the end; the other losses above stay lost.

Workbooks and presentations

Workbook.ToHtml writes one table per visible worksheet under an h2 with the sheet name. Values are shown as Excel shows them: numbers and dates go through the cell's number format (the shared number-format service), text as is, booleans and errors as text. Numbers are right-aligned (td.n). Merged ranges are colspan/rowspan. Not written: styles other than the number format, column widths, hidden sheets (loss.html-hidden-sheets), chart sheets, formulas (cached results are written, loss.formulas), drawings, charts, comments and pivot tables (loss.embedded-objects).

Presentation.ToHtml writes a section per slide: the title placeholder as h2, other text shapes as paragraphs (indented by level) in shape order, tables as tables, notes in an aside; hidden slides carry hidden. Not written: positions and sizes, pictures, charts and other graphic frames, animations, transitions, masters and layouts (loss.html-slide-layout, loss.html-pictures, loss.html-graphic-frames, loss.html-animations).

Defects

html.dropped (one per left-out element, with its offset), html.damaged and html.export-failed (wrapped unexpected failures); limits raise OfficeLimitException. See defects.md.

Not here

MHTML and single-file archives, CSS paged media (@page, running headers), float/position layout, <svg> and <canvas> content, Markdown (its own importer), and any rendering of HTML through OneRender's CSS engine: pages are mapped to the document model and laid out by the document layout core.

Oracles

LibreOffice opens the exported HTML (soffice --convert-to); Word's reading of our HTML, and Word's own HTML export of the same documents, are recorded for the desktop-Office run in testdata/html/word-cases.md.