Release 3.8

Author: onizet

.github/workflows/publish_nuget.yml

@@ -31,6 +31,8 @@ jobs:
       - name: Pack
         run: dotnet pack src/Html2OpenXml/HtmlToOpenXml.csproj --configuration Release --output ./nupkg
       - name: Push nuget to NuGet.org
-        run: dotnet nuget push ./nupkg/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} -s https://api.nuget.org/v3/index.json
+        run: dotnet nuget push ./nupkg/*.nupkg --api-key $NUGET_API_KEY -s https://api.nuget.org/v3/index.json
+        env:
+          NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
       - name: Create Release and Upload Artifact to Release
         run: gh release create ${{github.ref_name}} -t "Release ${{github.ref_name}}" *.nupkg --generate-notes --draft

CHANGELOG.md

@@ -1,10 +1,21 @@
 # Changelog
 
-## 3.2.6
+## 3.2.8
+
+- Fix a fatal crash when trying to convert multiple images #215
+- New feature to allow to reference external image instead of embedding them #216
+- Fix a potential issue on image streams that are disposed too early.
+- Support table col with percentage width #206
+
+## 3.2.7
 
 - Fix handling Uri with an anchor #209
 - New option DefaultStyles.NumberedHeadingStyle to support an alternate heading style #210
 
+## 3.2.6
+
+(wrong packaging, same code as 3.2.5)
+
 ## 3.2.5
 
 - Fix a crash with the new whitespace handling introduced in 3.2.3 #191

examples/Demo/Program.cs

@@ -24,7 +24,7 @@ static async Task Main(string[] args)
                 // instead of creating it from scratch.
                 using (var buffer = ResourceHelper.GetStream("Resources.template.docx"))
                 {
-                    buffer.CopyTo(generatedDocument);
+                    await buffer.CopyToAsync(generatedDocument);
                 }
 
                 generatedDocument.Position = 0L;

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/BlockElementExpression.cs

@@ -143,16 +143,14 @@ public override void CascadeStyles(OpenXmlElement element)
                 return;
 
             var knownTags = new HashSet<string>();
-            foreach (var prop in props)
+            foreach (var prop in props.Where(p => !knownTags.Contains(p.LocalName)))
             {
-                if (!knownTags.Contains(prop.LocalName))
-                    knownTags.Add(prop.LocalName);
+                knownTags.Add(prop.LocalName);
             }
 
-            foreach (var prop in tableProperties)
+            foreach (var prop in tableProperties.Where(p => !knownTags.Contains(p.LocalName)))
             {
-                if (!knownTags.Contains(prop.LocalName))
-                    props.AddChild(prop.CloneNode(true));
+                props.AddChild(prop.CloneNode(true));
             }
         }
     }

src/Html2OpenXml/Expressions/BodyExpression.cs

@@ -26,18 +26,27 @@ namespace HtmlToOpenXml.Expressions;
 sealed class BodyExpression(IHtmlElement node, ParagraphStyleId? defaultStyle)
     : BlockElementExpression(node, defaultStyle)
 {
+    private const uint PortraitPageWidth = 11906U;
+    private const uint PortraitPageHeight = 16838U;
     private bool shouldRegisterTopBookmark;
+    private ParsingContext? overridenContext;
 
     public override IEnumerable<OpenXmlElement> Interpret(ParsingContext context)
     {
         MarkAllBookmarks();
 
+        var body = context.MainPart.Document.Body!;
+        var sectionProperties = body.Descendants<SectionProperties>().LastOrDefault();
+        if (sectionProperties != null)
+        {
+            context.IsLandscape = sectionProperties.GetFirstChild<PageSize>()?.Width?.Value >= PortraitPageHeight;
+        }
+
         var elements = base.Interpret(context);
 
         if (shouldRegisterTopBookmark && elements.Any())
         {
             // Check whether it already exists
-            var body = context.MainPart.Document.Body!;
             if (body.Descendants<BookmarkStart>().Where(b => b.Name?.Value == "_top").Any())
             {
                 return elements;
@@ -70,6 +79,7 @@ protected override void ComposeStyles(ParsingContext context)
             var sectionProperties = mainPart.Document.Body!.GetFirstChild<SectionProperties>();
             if (sectionProperties == null || sectionProperties.GetFirstChild<PageSize>() == null)
             {
+                context.IsLandscape = orientation == PageOrientationValues.Landscape;
                 mainPart.Document.Body.Append(ChangePageOrientation(orientation));
             }
             else
@@ -80,6 +90,9 @@ protected override void ComposeStyles(ParsingContext context)
                     SectionProperties validSectionProp = ChangePageOrientation(orientation);
                     pageSize?.Remove();
                     sectionProperties.PrependChild(validSectionProp.GetFirstChild<PageSize>()!.CloneNode(true));
+
+                    overridenContext = context.CreateChild(this);
+                    overridenContext.IsLandscape = orientation == PageOrientationValues.Landscape;
                 }
             }
         }
@@ -101,14 +114,14 @@ protected override void ComposeStyles(ParsingContext context)
     /// </summary>
     private static SectionProperties ChangePageOrientation(PageOrientationValues orientation)
     {
-        PageSize pageSize = new() { Width = (UInt32Value) 16838U, Height = (UInt32Value) 11906U };
+        PageSize pageSize = new() { Width = PortraitPageWidth, Height = PortraitPageHeight };
         if (orientation == PageOrientationValues.Portrait)
         {
-            (pageSize.Height, pageSize.Width) = (pageSize.Width, pageSize.Height);
+            pageSize.Orient = orientation;
         }
         else
         {
-            pageSize.Orient = orientation;
+            (pageSize.Height, pageSize.Width) = (pageSize.Width, pageSize.Height);
         }
 
         return new SectionProperties (

src/Html2OpenXml/Expressions/FigureCaptionExpression.cs

@@ -52,7 +52,7 @@ public override IEnumerable<OpenXmlElement> Interpret (ParsingContext context)
         }
 
         //Add the figure number references to the start of the first paragraph.
-        if(childElements.FirstOrDefault() is Paragraph p)
+        if(childElements.First() is Paragraph p)
         {
            var properties = p.GetFirstChild<ParagraphProperties>();
            p.InsertAfter(new Run(

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),
                                 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)
+    {
+        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/Expressions/Table/TableColExpression.cs

@@ -23,21 +23,33 @@ namespace HtmlToOpenXml.Expressions;
 /// </summary>
 sealed class TableColExpression(IHtmlTableColumnElement node) : TableElementExpressionBase(node)
 {
+    private const int MaxTablePortraitWidth = 9622;
+    private const int MaxTableLandscapeWidth = 12996;
     private readonly IHtmlTableColumnElement colNode = node;
+    private double? percentWidth;
 
 
     /// <inheritdoc/>
-    public override IEnumerable<OpenXmlElement> Interpret (ParsingContext context)
+    public override IEnumerable<OpenXmlElement> Interpret(ParsingContext context)
     {
         ComposeStyles(context);
 
         var column = new GridColumn();
         var width = styleAttributes!.GetUnit("width");
-        if (width.IsValid && width.IsFixed)
+        if (width.IsValid)
         {
-            // This value is specified in twentieths of a point.
-            // If this attribute is omitted, then the last saved width of the grid column is assumed to be zero.
-            column.Width = Math.Round( width.ValueInPoint * 20 ).ToString(CultureInfo.InvariantCulture);
+            if (width.IsFixed)
+            {
+                // This value is specified in twentieths of a point.
+                // If this attribute is omitted, then the last saved width of the grid column is assumed to be zero.
+                column.Width = Math.Round(width.ValueInPoint * 20).ToString(CultureInfo.InvariantCulture);
+            }
+            else if (width.Type == UnitMetric.Percent)
+            {
+                var maxWidth = context.IsLandscape ? MaxTableLandscapeWidth : MaxTablePortraitWidth;
+                percentWidth = Math.Max(0, Math.Min(100, width.Value));
+                column.Width = Math.Ceiling(maxWidth / 100d * percentWidth.Value).ToString(CultureInfo.InvariantCulture);
+            }
         }
 
         if (colNode.Span == 0)
@@ -51,4 +63,18 @@ public override IEnumerable<OpenXmlElement> Interpret (ParsingContext context)
 
         return elements;
     }
+
+    public override void CascadeStyles(OpenXmlElement element)
+    {
+        base.CascadeStyles(element);
+
+        if (percentWidth.HasValue && element is TableCell cell &&
+            cell.TableCellProperties?.TableCellWidth is null)
+        {
+            cell.TableCellProperties!.TableCellWidth = new() {
+                Type = TableWidthUnitValues.Pct,
+                Width = ((int) (percentWidth.Value * 50)).ToString(CultureInfo.InvariantCulture)
+            };
+        }
+    }
 }

src/Html2OpenXml/Expressions/TextExpression.cs

@@ -96,14 +96,11 @@ public override IEnumerable<OpenXmlElement> Interpret (ParsingContext context)
             }
 
             // if previous element is an image, append a space separator
-            // if this is a non-empty phrasing element, append a space separator
-            if (startsWithSpace && node.PreviousSibling is IHtmlImageElement)
-            {
-                text = " " + text;
-            }
-            else if (startsWithSpace && prevIsPhrasing
+            if ((startsWithSpace && node.PreviousSibling is IHtmlImageElement)
+                // if this is a non-empty phrasing element, append a space separator
+                || (startsWithSpace && prevIsPhrasing
                 && node.PreviousSibling!.TextContent.Length > 0
-                && !node.PreviousSibling!.TextContent[node.PreviousSibling.TextContent.Length - 1].IsWhiteSpaceCharacter())
+                && !node.PreviousSibling!.TextContent[node.PreviousSibling.TextContent.Length - 1].IsWhiteSpaceCharacter()))
             {
                 text = " " + text;
             }