#NuSpec.AI/v2 HtmlToOpenXml 4.0.0
#desc Convert simple or advanced HTML into OpenXML Word content while reusing existing document styles, numbering, and templates.
#tfm netstandard2.0;net462;net8.0;net10.0
#dep AngleSharp|1.8.0|0;DocumentFormat.OpenXml|3.5.1|0;Microsoft.Extensions.Logging.Abstractions|6.0.0|0;System.ValueTuple|4.5.0|0
@e AcronymPosition "Controls where the definition of an acronym or abbreviation is rendered during conversion. AcronymFor example, the definition assocaited with an HTML abbr element can be rendered at the end of the page or collected at the end of the document."
 .ev PageEnd=0,DocumentEnd=1
@c DefaultStyles [entity] "Contains the default OpenXml style mappings used by HtmlToOpenXml.HtmlConverter. Styles selected through these mappings provide the base formatting. CSS attributes defined on HTML elements are still applied on top of the resulting Word style. Several commonly used Word styles such as headings, hyperlinks, captions, tables, footnotes and quotes can be created automatically when missing from the document. Customise these mappings to use your own style names during conversion."
 .p CaptionStyle:string "Default style for captions (figcaption, caption)."
 .p EndnoteTextStyle:string "Default style for endnote texts (abbr, acronym)."
 .p EndnoteReferenceStyle:string "Default style for endnote references (e.g., the index number of this endnote)."
 .p FootnoteTextStyle:string "Default style for new footnote texts (abbr, acronym)."
 .p FootnoteReferenceStyle:string "Default style for new footnote references (e.g., the index number of this endnote)."
 .p HeadingStyle:string "Default style for headings. The converter will automatically appends the heading depth level at the end of the style name."
 .p NumberedHeadingStyle:string "Default style for recognized numbered headings, when HtmlToOpenXml.HtmlConverter.SupportsHeadingNumbering is true. The converter will automatically appends the heading depth level at the end of the style name. When HtmlToOpenXml.HtmlConverter.SupportsHeadingNumbering is true, using NumberedHeadingStyle allows the converter to properly handle the back-end sequencing (1., 1.1, 1.2)."
 .p HyperlinkStyle:string "Default style for hyperlinks (a)."
 .p ListParagraphStyle:string "Default style for list paragraphs (li)."
 .p PreTableStyle:string "Default style for the pre when HtmlToOpenXml.HtmlConverter.RenderPreAsTable is true."
 .p QuoteStyle:string "Default style for quotes (quote, cite)."
 .p IntenseQuoteStyle:string "Default style for intense quotes (blockquote)."
 .p TableStyle:string "Default style for tables (table)."
 .p HeaderStyle:string "Default style for any paragraphs (p) in the header section (DocumentFormat.OpenXml.Packaging.HeaderPart )."
 .p ParagraphHeaderStyle:string "Default style for any paragraphs (p) in the header section (DocumentFormat.OpenXml.Packaging.HeaderPart )."
 .p FooterStyle:string "Default style for any paragraphs (p) in the footer section (DocumentFormat.OpenXml.Packaging.FooterPart )."
 .p ParagraphFooterStyle:string "Default style for any paragraphs (p) in the footer section (DocumentFormat.OpenXml.Packaging.FooterPart )."
 .p Paragraph:string "Default style for body paragraph (body or any top level tag in HTML source)."
 .p ParagraphBodyStyle:string "Default style for paragraph (p or body or any top level tag in HTML source) in the body section."
@c HtmlConverter "Primary entry point for converting HTML into OpenXml Word document. The converter can be used with newly created documents as well as existing document templates. When a template is used, styles, themes, numbering definitions, bookmarks, and other Word settings are automatically reused. Supports both left-to-right (LTR) and right-to-left (LTR) visual flow content. Direction can be specified using the HTML dir attribute (recommended) or inferred from the lang attribute. When not specified, the converter preserves the layout defined by the target Word document. Supports full OpenXML table translation, including complex structural elements (nested tables, `colspan`/`rowspan`) and precise dimension mapping (`px`, `%`), column definitions, vertical text, and automatic conversion of table widths. Table widths can be specified using auto, percentages, or fixed dimensions (px/pt). Use HtmlToOpenXml.HtmlConverter.HtmlStyles to customise styling and HtmlToOpenXml.IO.IWebRequest to customise external resource retrieval. Typical usage: Create an HtmlConverter from a MainDocumentPart obtained from a WordProcessingDocument. Call ParseBody() to append the converted content to the document body. Advanced scenarios can use ParseAsync() to control where the generated OpenXml elements are inserted."
 .ctor (MainDocumentPart mainPart, IWebRequest? webRequester = null) "Create a converter bound to a Word document. Reuse the same HtmlConverter instance for the lifetime of a document to avoid reloading cached configuration such as styles and bookmarks. Do not use the same converter instance with multiple documents."
 .m Parse:IList<OpenXmlCompositeElement>(string html) "Convert HTML into OpenXml elements and return them to the caller. Use this method when your HTML is simple and don't need to download any external resources. Parse() is equivalent to ParseAsync() and is retained for backward compatibility. New code should prefer ParseBody(), ParseHeader() or ParseFooter() to make the target document section explicit."
 .m ParseAsync:Task<IEnumerable<OpenXmlCompositeElement>>(string html, CancellationToken cancellationToken = null) "Convert HTML into OpenXml elements and return them to the caller. However, the conversion process itself may still update the underlying document by creating styles, numbering definitions, image parts, bookmarks, or other resources required by the generated content. Use this method when you need full control over the insertion point or need to inspect or modify the generated elements before adding them to the document. For most scenarios, prefer ParseBody()."
 .m ParseAsync:Task<IEnumerable<OpenXmlCompositeElement>>(string html, ParallelOptions parallelOptions) "Convert HTML into OpenXml elements and return them to the caller. Use this method when you need full control over the insertion point or need to inspect or modify the generated elements before adding them to the document. For most scenarios, prefer ParseBody()."
 .m ParseHeader:Task(string html, HeaderFooterValues? headerType = null, CancellationToken cancellationToken = null) "Parse some HTML and append the genereated content to a Word header. Typical uses include company logos, document titles, confidentiality notices, report identifiers, and other recurring content displayed at the top of each page."
 .m ParseFooter:Task(string html, HeaderFooterValues? footerType = null, CancellationToken cancellationToken = null) "Parse some HTML and append the generated content into a Word footer. Typical uses include legal disclaimers, contact information, page numbering, copyright notices, and other recurring content displayed at the bottom of each page."
 .m ParseBody:Task(string html, CancellationToken cancellationToken = null) "Parses some Html and appends the generated content to the document body. This is the recommended method for most scenarios. Page Break can be inserted using the CSS properties page-break-before and page-break-after with the value "always". Useful for reports, invoices, contracts, and other multi-page business documents. Page Orientation can be changed through the non-standard page-orientation attribute (supported values: portrait and landscape). This is useful for wide tables, reports and other content that benefits from a landscape layout. Currently, the attribute is supported on the body element and applies to the main document."
 .m RefreshStyles:void() "Reloads the style cache from the current Word document (HtmlToOpenXml.WordDocumentStyle). Call this method if styles are added after the HtmlConverter instance has been created."
 .p AcronymPosition:AcronymPosition "Defines the location where to add the acronym or abbreviation explanation tag. Defaults to the end of the page (HtmlToOpenXml.AcronymPosition.PageEnd)."
 .p SupportsAnchorLinks:bool "Defines whether internal anchor hyperlinks are converted to Word bookmarks. Anchor links target another location within the document, such as #_top or a bookmark reference (#bookmarkReference). Bookmars can be created automatically from HTML anchors or explicitely using the data-bookmark attribute. When data-bookmark is present, the library uses this target name to jump to an existing structural element in the destination DOCX file rather than creating a new anchor. <h1 data-bookmark="chapter1">Introduction</h1> Anchor links are enabled by default. If the target cannot be resolved in the current Word document, the content will be rendered as a simple text."
 .p HtmlStyles:WordDocumentStyle "Gets the style manager for the current conversion. HtmlStyles controls how HTML elements are translated into Word styles. Through this object you can customize the default style mappings, add custom styles, and react when a referenced style is missing from the document."
 .p TableCaptionPosition:CaptionPositionValues "Defines where the Legend tag (caption) should be rendered above or below the table. Defaults above the table."
 .p RenderPreAsTable:bool "Defines whether the preformatted blocks (pre) are rendered as tables. When enabled, pre elements are converted to a single-cell table to preserve whitespace, indentation and line breaks. This is particularly useful for source code, console output, and technical blog posts. When disabled, preformatted content is rendered using regular Word paragraphs. Defaults to false."
 .p ImageProcessing:ImageProcessingMode "Controls how images are handled during conversion. Images are embedded in the generated document by default. External resources are resolved through HtmlToOpenXml.IO.IWebRequest, which can be customised to provide authentication, support additional formats such as WebP (see the wiki), or resolve relative URLs. Default: HtmlToOpenXml.ImageProcessingMode.Embed."
 .p ContinueNumbering:bool "Defines whether consecutive ordered lists continue the numbering sequence from previous lists. By default, numbering continues across multiple ol elements. Use the HTML start attribute to restart numbering or begin at a specific value. When disabled, each ordered list starts a new numbering sequence."
 .p SupportsHeadingNumbering:bool "Defines whether (h1-h6) elements are mapped to the corresponding Word heading style. Missing heading styles are added automatically when required. When heading text begins with a numbering pattern such as "1.", "1.1.", or "1 " or when the heading uses the `decimal-tiered` CSS class, the converter interprets it as a numbered heading. Any associated heading numbering is then managed by Word through the Heading styles. This feature is enabled by default."
@e ImageProcessingMode "Controls whether images are embedded in the generated document or kept as external references."
 .ev Embed=0,LinkExternal=1,EmbedDataUriOnly=2
@c DataUri "Represents a Data URI containing inline content encoded directly in the URI string, typically using Base64 encoding. Data URIs are commonly used to embed images in HTML without referencing an external resource, for example: data:image/png;base64,..."
 .m TryCreate:bool(string uri, out DataUri? result) "Parse an instance of the Data URI scheme."
 .m IsWellFormed:bool(string uri) "Indicates whether the string is well-formed by attempting to construct a DataUri with the string."
 .p Mime:string "Gets the MIME type declared by the Data URI, such as image/png or image/jpeg."
 .p Data:byte[] "Gets the decoded binary content extracted from the Data URI."
@c DefaultWebRequest "Default implementation of HtmlToOpenXml.IO.IWebRequest. Supports http, https, local file and inline data (base64). Derive from this class to customise resource retrieval, authentication, image processing, URL resolution, or content transformation while reusing the built-in behaviour."
 .ctor (ILogger? logger = null) "Initialize a new instance of the HtmlToOpenXml.IO.DefaultWebRequest class."
 .ctor (HttpClient httpClient, ILogger? logger = null) "Initialize a new instance of the HtmlToOpenXml.IO.DefaultWebRequest class with the specified HttpClient. Supply your own HttpClient to customise how external resources are retrieved, for example to configure cookies, authentication headers, API keys, proxies, or message handlers."
 .m FetchAsync:Task<Resource?>(Uri requestUri, CancellationToken cancellationToken)
 .m SupportsProtocol:bool(string protocol)
 .p BaseImageUrl:Uri? "Defines the base URI used to resolve image URLs. Use this property when HTML content contains relative images references such as /images/logo.png or /../assets/banner.jpg. During conversion, relative URLs are combined with this base URI to locate and download the image resource"
@i IWebRequest "Handle retrieval of external resources referenced during HTML conversion. Resources may include images, stylesheets, scripts and local files. Implement this interface to customize resource resolution, provide authentication, support additional formats, rewrite URLs, or transform downlaoded content before it is inserted into the document. Implementations are expected to support the http, https and file protocols."
 .m FetchAsync:Task<Resource?>(Uri requestUri, CancellationToken cancellationToken) "Retrieves a resource referenced by the HTML document. Returns null when the resource cannot be retrieved. The returned HtmlToOpenXml.IO.Resource must provide a readable content stream. Returned HtmlToOpenXml.IO.Resource instances are disposed by HtmlToOpenXml after processing."
 .m SupportsProtocol:bool(string protocol) "Checks if the given protocol is supported."
@c Resource "Represents a download resource returned by HtmlToOpenXml.IO.IWebRequest. HtmlToOpenXml takes ownership of instances returned by HtmlToOpenXml.IO.IWebRequest and will dispose them after processing."
 .p StatusCode:HttpStatusCode "Gets the status code that has been send with the response."
 .p Headers:string> "Optional response Http headers. Content-Type is used when the resource type cannot be determined from the URL."
 .p Content:Stream "Gets the resource content stream. The stream must be readable.Resource type detection may inspect the beginning of the stream and reset its position afterwards, therefore the stream should support seeking."
 .m Dispose:void()
@s QuoteChars "Predefined quote style as defined by the browser (used for the q HTML tag)."
 .ctor (string begin, string end) "Predefined quote style as defined by the browser (used for the q HTML tag)."
 .f IE:QuoteChars "Internet Explorer style: « abc »"
 .f Gecko:QuoteChars "Firefox style: “abc”"
 .f WebKit:QuoteChars "Chrome/Safari/Opera style: "abc""
@c StyleEventArgs [entity] "Provides information about a style requested during conversion that could not be found in the Word document. The HtmlToOpenXml.WordDocumentStyle.StyleMissing event uses these arguments to indicate which style should be dynamically provisioned and which OpenXml style type is expected."
 .p Name:string "Gets the identifier of the missing style. Use this value when creating and registering the style."
 .p Type:StyleValues "Gets the OpenXml style type expected by the converter, such as paragraph, table or character."
@c WordDocumentStyle "Provides style-related services used during HTML conversion. HTML class names may be mapped directly to Word styles with the same name (case insensitive). When a referenced style cannot be found, the HtmlToOpenXml.WordDocumentStyle.StyleMissing event allows it to be provisioned dynamically."
 .m AddStyle:void(Style style) "Adds a new style to the Word document and refreshes the converter's internal style cache. Use this method in conjunction with the HtmlToOpenXml.WordDocumentStyle.StyleMissing event to inject styles required by a template that are absent from the source document."
 .p DefaultStyles:DefaultStyles "Contains the default styles for new OpenXml elements, created during the conversion process."
 .p QuoteCharacters:QuoteChars "Defines the beginning and ending characters used in the <q> tag. Defaults follow the style: « abc »."