Implement ImageProcessingMode which dictates how images should be handled during conversion. (#216)

The idea of this commit is to provide a working example of being able to dictate how HtmlToOpenXml should handle images marked as HTTP/HTTPS. I've also provided handling for data uris so that only data URI images can be embedded.

Example implementation - taken from a modified form of examples\Demo\Program.cs

    string inputFile = "C:\\ConvertedHtml.html";
    string htmlContent = await File.ReadAllTextAsync(inputFile);

    string outputPath = "C:\\ConvertedHtml.docx";
    using WordprocessingDocument wordDoc = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);
    MainDocumentPart mainPart = wordDoc.AddMainDocumentPart();
    mainPart.Document = new Document(new DocumentFormat.OpenXml.Wordprocessing.Body());

    HtmlConverter htmlConverter = new(mainPart, new DefaultWebRequest())
    {
        ImageProcessing = ImageProcessingMode.LinkExternal
    };

    await htmlConverter.ParseBody(htmlContent);

    AssertThatOpenXmlDocumentIsValid(wordDoc);

    mainPart.Document.Save();

Author: DanAtkinson

src/Html2OpenXml/Configuration enum.cs

@@ -46,4 +46,27 @@ public readonly struct QuoteChars(string begin, string end)
 
     internal string Prefix { get; } = begin;
     internal string Suffix { get; } = end;
-}
+}
+
+/// <summary>
+/// Specifies how images should be processed during HTML to OpenXML conversion.
+/// </summary>
+public enum ImageProcessingMode
+{
+    /// <summary>
+    /// Downloads and embeds all images into the document (default behaviour).
+    /// This creates self-contained documents but may result in large file sizes.
+    /// </summary>
+    Embed = 0,
+    /// <summary>
+    /// Links to external images via external relationships instead of downloading them.
+    /// This keeps document size small but images won't display offline or if URLs become unavailable.
+    /// Data URI images (base64 encoded) are still embedded.
+    /// </summary>
+    LinkExternal = 1,
+    /// <summary>
+    /// Only embeds data URI images (base64 encoded inline images).
+    /// External images (http/https/file) are skipped entirely.
+    /// </summary>
+    EmbedDataUriOnly = 2,
+}

src/Html2OpenXml/Expressions/Image/ImageExpression.cs

@@ -94,6 +94,14 @@ class ImageExpression(IHtmlImageElement node) : ImageExpressionBase(node)
             preferredSize = ImageHeader.KeepAspectRatio(actualSize, preferredSize);
         }
 
+        // If size is still empty (e.g., for external linked images), use default dimensions
+        if (preferredSize.IsEmpty || preferredSize.Width <= 0 || preferredSize.Height <= 0)
+        {
+            // Use default size for external images or when size cannot be determined
+            // Default to a reasonable size (similar to how browsers handle images with unknown dimensions)
+            preferredSize = new Size(300, 200);
+        }
+
         long widthInEmus = new Unit(UnitMetric.Pixel, preferredSize.Width).ValueInEmus;
         long heightInEmus = new Unit(UnitMetric.Pixel, preferredSize.Height).ValueInEmus;
 
@@ -103,22 +111,26 @@ class ImageExpression(IHtmlImageElement node) : ImageExpressionBase(node)
                 new wp.Extent() { Cx = widthInEmus, Cy = heightInEmus },
                 new wp.EffectExtent() { LeftEdge = 19050L, TopEdge = 0L, RightEdge = 0L, BottomEdge = 0L },
                 new wp.DocProperties() { Id = drawingObjId, Name = "Picture " + imageObjId, Description = string.Empty },
-                new wp.NonVisualGraphicFrameDrawingProperties {
+                new wp.NonVisualGraphicFrameDrawingProperties
+                {
                     GraphicFrameLocks = new a.GraphicFrameLocks() { NoChangeAspect = true }
                 },
                 new a.Graphic(
                     new a.GraphicData(
                         new pic.Picture(
-                            new pic.NonVisualPictureProperties {
-                                NonVisualDrawingProperties = new pic.NonVisualDrawingProperties() { 
+                            new pic.NonVisualPictureProperties
+                            {
+                                NonVisualDrawingProperties = new pic.NonVisualDrawingProperties()
+                                {
                                     Id = imageObjId,
                                     Name = DataUri.IsWellFormed(src) ? string.Empty : src,
-                                    Description = alt },
+                                    Description = alt
+                                },
                                 NonVisualPictureDrawingProperties = new pic.NonVisualPictureDrawingProperties(
                                     new a.PictureLocks() { NoChangeAspect = true, NoChangeArrowheads = true })
                             },
                             new pic.BlipFill(
-                                new a.Blip() { Embed = iinfo.ImagePartId },
+                                CreateBlip(iinfo, src),
                                 new a.SourceRectangle(),
                                 new a.Stretch(
                                     new a.FillRectangle())),
@@ -128,10 +140,14 @@ class ImageExpression(IHtmlImageElement node) : ImageExpressionBase(node)
                                     new a.Extents() { Cx = widthInEmus, Cy = heightInEmus }),
                                 new a.PresetGeometry(
                                     new a.AdjustValueList()
-                                ) { Preset = a.ShapeTypeValues.Rectangle }
-                            ) { BlackWhiteMode = a.BlackWhiteModeValues.Auto })
-                    ) { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" })
-            ) { DistanceFromTop = (UInt32Value) 0U, DistanceFromBottom = (UInt32Value) 0U, DistanceFromLeft = (UInt32Value) 0U, DistanceFromRight = (UInt32Value) 0U }
+                                )
+                                { Preset = a.ShapeTypeValues.Rectangle }
+                            )
+                            { BlackWhiteMode = a.BlackWhiteModeValues.Auto })
+                    )
+                    { Uri = "http://schemas.openxmlformats.org/drawingml/2006/picture" })
+            )
+            { DistanceFromTop = (UInt32Value)0U, DistanceFromBottom = (UInt32Value)0U, DistanceFromLeft = (UInt32Value)0U, DistanceFromRight = (UInt32Value)0U }
         );
 
         return img;
@@ -147,11 +163,28 @@ private static int GetDimension(HtmlAttributeCollection styles, string primarySt
 
         if (unit.IsValid)
         {
-            return unit.Type == UnitMetric.Percent?
+            return unit.Type == UnitMetric.Percent ?
                 (int)(unit.Value * percentageBase / 100) :
                 unit.ValueInPx;
         }
 
         return 0;
     }
-}
+
+    /// <summary>
+    /// Creates a Blip element with either an embedded or external image reference.
+    /// </summary>
+    private static a.Blip CreateBlip(HtmlImageInfo iinfo, string? src)
+    {
+        if (iinfo.IsExternal)
+        {
+            // Use Link property for external images
+            return new a.Blip() { Link = iinfo.ImagePartId };
+        }
+        else
+        {
+            // Use Embed property for embedded images (default behaviour)
+            return new a.Blip() { Embed = iinfo.ImagePartId };
+        }
+    }
+}

src/Html2OpenXml/HtmlConverter.cs

@@ -58,20 +58,20 @@ public HtmlConverter(MainDocumentPart mainPart, IWebRequest? webRequester = null
     }
 
     /// <summary>
-    /// Parse some HTML content where the output is intented to be inserted in <see cref="MainDocumentPart"/>.
+    /// Parse some HTML content where the output is intended to be inserted in <see cref="MainDocumentPart"/>.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <returns>Returns a list of parsed paragraph.</returns>
     public IList<OpenXmlCompositeElement> Parse(string html)
     {
-        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester);
+        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester, ImageProcessing);
         return ParseCoreAsync(html, mainPart, bodyImageLoader,
             new ParallelOptions() { CancellationToken = CancellationToken.None })
             .ConfigureAwait(false).GetAwaiter().GetResult().ToList();
     }
 
     /// <summary>
-    /// Start the asynchroneous parse processing where the output is intented to be inserted in <see cref="MainDocumentPart"/>.
+    /// Start the asynchronous parse processing where the output is intended to be inserted in <see cref="MainDocumentPart"/>.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="cancellationToken">The cancellation token.</param>
@@ -84,7 +84,7 @@ public Task<IEnumerable<OpenXmlCompositeElement>> Parse(string html, Cancellatio
     }
 
     /// <summary>
-    /// Start the asynchroneous parse processing where the output is intented to be inserted in <see cref="MainDocumentPart"/>.
+    /// Start the asynchronous parse processing where the output is intended to be inserted in <see cref="MainDocumentPart"/>.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="cancellationToken">The cancellation token.</param>
@@ -95,20 +95,20 @@ public Task<IEnumerable<OpenXmlCompositeElement>> ParseAsync(string html, Cancel
     }
 
     /// <summary>
-    /// Start the asynchroneous parse processing where the output is intented to be inserted in <see cref="MainDocumentPart"/>.
+    /// Start the asynchronous parse processing where the output is intended to be inserted in <see cref="MainDocumentPart"/>.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="parallelOptions">The configuration of parallelism while downloading the remote resources.</param>
     /// <returns>Returns a list of parsed paragraph.</returns>
     public Task<IEnumerable<OpenXmlCompositeElement>> ParseAsync(string html, ParallelOptions parallelOptions)
     {
-        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester);
+        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester, ImageProcessing);
 
         return ParseCoreAsync(html, mainPart, bodyImageLoader, parallelOptions);
     }
 
     /// <summary>
-    /// Parse asynchroneously the Html and append the output into the Header of the document.
+    /// Parse asynchronously the Html and append the output into the Header of the document.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="headerType">Determines the page(s) on which the current header shall be displayed.
@@ -122,7 +122,7 @@ public async Task ParseHeader(string html, HeaderFooterValues? headerType = null
         var headerPart = ResolveHeaderFooterPart<HeaderReference, HeaderPart>(headerType);
 
         headerPart.Header ??= new();
-        headerImageLoader ??= new ImagePrefetcher<HeaderPart>(headerPart, webRequester);
+        headerImageLoader ??= new ImagePrefetcher<HeaderPart>(headerPart, webRequester, ImageProcessing);
 
         var paragraphs = await ParseCoreAsync(html, headerPart, headerImageLoader,
             new ParallelOptions() { CancellationToken = cancellationToken },
@@ -133,7 +133,7 @@ public async Task ParseHeader(string html, HeaderFooterValues? headerType = null
     }
 
     /// <summary>
-    /// Parse asynchroneously the Html and append the output into the Footer of the document.
+    /// Parse asynchronously the Html and append the output into the Footer of the document.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="footerType">Determines the page(s) on which the current footer shall be displayed.
@@ -147,7 +147,7 @@ public async Task ParseFooter(string html, HeaderFooterValues? footerType = null
         var footerPart = ResolveHeaderFooterPart<FooterReference, FooterPart>(footerType);
 
         footerPart.Footer ??= new();
-        footerImageLoader ??= new ImagePrefetcher<FooterPart>(footerPart, webRequester);
+        footerImageLoader ??= new ImagePrefetcher<FooterPart>(footerPart, webRequester, ImageProcessing);
 
         var paragraphs = await ParseCoreAsync(html, footerPart, footerImageLoader,
             new ParallelOptions() { CancellationToken = cancellationToken },
@@ -158,14 +158,14 @@ public async Task ParseFooter(string html, HeaderFooterValues? footerType = null
     }
 
     /// <summary>
-    /// Parse asynchroneously the Html and append the output into the Body of the document.
+    /// Parse asynchronously the Html and append the output into the Body of the document.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="cancellationToken">The cancellation token.</param>
     /// <seealso cref="MainDocumentPart"/>
     public async Task ParseBody(string html, CancellationToken cancellationToken = default)
     {
-        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester);
+        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester, ImageProcessing);
         var paragraphs = await ParseCoreAsync(html, mainPart, bodyImageLoader,
             new ParallelOptions() { CancellationToken = cancellationToken },
             htmlStyles.GetParagraphStyle(htmlStyles.DefaultStyles.Paragraph))
@@ -201,7 +201,7 @@ public async Task ParseBody(string html, CancellationToken cancellationToken = d
     }
 
     /// <summary>
-    /// Start the asynchroneous parse processing. Use this overload if you want to control the downloading of images.
+    /// Start the asynchronous parse processing. Use this overload if you want to control the downloading of images.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="parallelOptions">The configuration of parallelism while downloading the remote resources.</param>
@@ -210,13 +210,13 @@ public async Task ParseBody(string html, CancellationToken cancellationToken = d
     [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
     public Task<IEnumerable<OpenXmlCompositeElement>> Parse(string html, ParallelOptions parallelOptions)
     {
-        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester);
+        bodyImageLoader ??= new ImagePrefetcher<MainDocumentPart>(mainPart, webRequester, ImageProcessing);
 
         return ParseCoreAsync(html, mainPart, bodyImageLoader, parallelOptions);
     }
 
     /// <summary>
-    /// Start the asynchroneous parse processing and append the output into the Body of the document.
+    /// Start the asynchronous parse processing and append the output into the Body of the document.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="cancellationToken">The cancellation token.</param>
@@ -236,7 +236,7 @@ public void RefreshStyles()
     }
 
     /// <summary>
-    /// Start the asynchroneous parse processing. Use this overload if you want to control the downloading of images.
+    /// Start the asynchronous parse processing. Use this overload if you want to control the downloading of images.
     /// </summary>
     /// <param name="html">The HTML content to parse</param>
     /// <param name="hostingPart">The OpenXml container where the content will be inserted into.</param>
@@ -394,6 +394,26 @@ public WordDocumentStyle HtmlStyles
     /// <remarks>The table will contains only one cell.</remarks>
     public bool RenderPreAsTable { get; set; }
 
+    /// <summary>
+    /// Gets or sets how images should be processed during conversion.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Use <see cref="ImageProcessingMode.Embed"/> (default) to download and embed all images,
+    /// creating self-contained documents but potentially large file sizes.
+    /// </para>
+    /// <para>
+    /// Use <see cref="ImageProcessingMode.LinkExternal"/> to link to external images via relationships,
+    /// keeping document size small but requiring internet access to view images.
+    /// Data URI images (base64 encoded) are still embedded.
+    /// </para>
+    /// <para>
+    /// Use <see cref="ImageProcessingMode.EmbedDataUriOnly"/> to only embed data URI images
+    /// and skip external images entirely.
+    /// </para>
+    /// </remarks>
+    public ImageProcessingMode ImageProcessing { get; set; } = ImageProcessingMode.Embed;
+
     /// <summary>
     /// Defines whether ordered lists (<c>ol</c>) continue incrementing existing numbering
     /// or restarts to 1 (defaults continues numbering).

src/Html2OpenXml/IO/ImagePrefetcher.cs

@@ -53,6 +53,7 @@ sealed class ImagePrefetcher<T> : IImageLoader
     private readonly IWebRequest resourceLoader;
     private readonly HtmlImageInfoCollection prefetchedImages;
     private readonly object lockObject = new object();
+    private readonly ImageProcessingMode processingMode;
 
 
     /// <summary>
@@ -61,10 +62,12 @@ sealed class ImagePrefetcher<T> : IImageLoader
     /// <param name="hostingPart">The image will be linked to that hosting part.
     /// Images are not shared between header, footer and body.</param>
     /// <param name="resourceLoader">Service to resolve an image.</param>
-    public ImagePrefetcher(T hostingPart, IWebRequest resourceLoader)
+    /// <param name="processingMode">Specifies how images should be processed (embed, link, or data URI only).</param>
+    public ImagePrefetcher(T hostingPart, IWebRequest resourceLoader, ImageProcessingMode processingMode = ImageProcessingMode.Embed)
     {
         this.hostingPart = hostingPart;
         this.resourceLoader = resourceLoader;
+        this.processingMode = processingMode;
         this.prefetchedImages = new HtmlImageInfoCollection();
     }
 
@@ -91,7 +94,22 @@ public ImagePrefetcher(T hostingPart, IWebRequest resourceLoader)
         }
         else
         {
-            iinfo = await DownloadRemoteImage(imageUri, cancellationToken).ConfigureAwait(false);
+            // Handle external images based on processing mode
+            if (processingMode == ImageProcessingMode.EmbedDataUriOnly)
+            {
+                // Skip external images entirely
+                return null;
+            }
+            else if (processingMode == ImageProcessingMode.LinkExternal)
+            {
+                // Create external link without downloading
+                iinfo = CreateExternalImageLink(imageUri);
+            }
+            else
+            {
+                // Default: Download and embed
+                iinfo = await DownloadRemoteImage(imageUri, cancellationToken).ConfigureAwait(false);
+            }
         }
 
         // Add to cache using thread-safe operation
@@ -168,6 +186,48 @@ public ImagePrefetcher(T hostingPart, IWebRequest resourceLoader)
         }
     }
 
+    /// <summary>
+    /// Create an external relationship to an image without downloading it.
+    /// </summary>
+    private HtmlImageInfo? CreateExternalImageLink(string src)
+    {
+        Uri imageUri = new Uri(src, UriKind.RelativeOrAbsolute);
+
+        // Resolve relative URIs if possible (only for DefaultWebRequest which has BaseImageUrl)
+        if (!imageUri.IsAbsoluteUri && resourceLoader is DefaultWebRequest defaultWebRequest
+            && defaultWebRequest.BaseImageUrl != null)
+        {
+            string url1 = defaultWebRequest.BaseImageUrl.AbsoluteUri.TrimEnd('/', '\\');
+            string path = src.TrimStart('/', '\\');
+            imageUri = new Uri(string.Format("{0}/{1}", url1, path), UriKind.Absolute);
+        }
+
+        // Only create external links for absolute URIs with supported protocols
+        if (!imageUri.IsAbsoluteUri || !resourceLoader.SupportsProtocol(imageUri.Scheme))
+            return null;
+
+        // Generate a unique GUID-based relationship ID for the external relationship
+        string relationshipId = "imgext_" + Guid.NewGuid().ToString("N");
+
+        // Create external relationship
+        lock (lockObject)
+        {
+            hostingPart.AddExternalRelationship(
+                "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+                imageUri,
+                relationshipId);
+        }
+
+        // Return image info with external flag set
+        // Note: Size will be empty as we don't download the image
+        return new HtmlImageInfo(src, relationshipId)
+        {
+            IsExternal = true,
+            Size = Size.Empty,
+            TypeInfo = ImagePartType.Png // Default type, actual type doesn't matter for external links
+        };
+    }
+
     /// <summary>
     /// Parse the Data inline image.
     /// </summary>

src/Html2OpenXml/Primitives/HtmlImageInfo.cs

@@ -37,6 +37,12 @@ sealed class HtmlImageInfo(string source, string partId)
     /// Gets the content type of the image.
     /// </summary>
     public PartTypeInfo TypeInfo { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether this image is linked externally rather than embedded.
+    /// When true, <see cref="ImagePartId"/> contains an external relationship ID instead of an embedded image part ID.
+    /// </summary>
+    public bool IsExternal { get; set; }
 }
 
 /// <summary>