fix: force box-mode rendering for left-only paragraph borders (#61)

csharp-version/src/MarkdownToDocx.Core/OpenXml/OpenXmlDocumentBuilder.cs

@@ -156,6 +156,21 @@
             paragraphBorders.AppendChild(border);
         }
 
+        // When only "left" is specified, Word anchors the border at the paragraph indent (flush
+        // with text) instead of at the page content edge. Adding Nil borders for the unspecified
+        // sides forces Word into box-mode rendering, which anchors the left border at position 0
+        // so that LeftIndent creates a visible gap between the border line and the text.
+        var specifiedPositions = new HashSet<string>(positions);
+        if (specifiedPositions.Contains("left"))
+        {
+            if (!specifiedPositions.Contains("top"))
+                paragraphBorders.AppendChild(new TopBorder { Val = BorderValues.Nil });
+            if (!specifiedPositions.Contains("bottom"))
+                paragraphBorders.AppendChild(new BottomBorder { Val = BorderValues.Nil });
+            if (!specifiedPositions.Contains("right"))
+                paragraphBorders.AppendChild(new RightBorder { Val = BorderValues.Nil });
+        }
+
         return paragraphBorders;
     }
 
@@ -810,7 +825,7 @@
         // Adding indent equal to BorderSpace * 20 twips anchors the border at the margin boundary.
         if (style.BorderSpace > 0)
         {
             string indentTwips = (style.BorderSpace * 20).ToString();
             props.AppendChild(new Indentation { Left = indentTwips, Right = indentTwips });
         }
 
@@ -917,7 +932,7 @@
         var indentation = new Indentation { Left = style.LeftIndent };
         if (hasPadding && style.PaddingSpace > 0)
         {
             indentation.Right = (style.PaddingSpace * 20).ToString();
         }
         props.AppendChild(indentation);
 

csharp-version/tests/MarkdownToDocx.Tests/Unit/OpenXmlDocumentBuilderTests.cs

@@ -2229,6 +2229,103 @@ public void AddHeading_WithLeftIndentAndBorderExtentText_ShouldRenderIndentation
         indentation!.Left!.Value.Should().Be("400");
     }
 
+    [Fact]
+    public void AddHeading_WithLeftBorderOnly_ShouldAddNilBordersForBoxMode()
+    {
+        // Arrange
+        using var builder = new OpenXmlDocumentBuilder(_stream, _horizontalProvider);
+        var style = CreateDefaultHeadingStyle() with
+        {
+            ShowBorder = true,
+            BorderPosition = "left",
+            BorderColor = "0066cc",
+            BorderSize = 24,
+            BorderSpace = 8,
+            LeftIndent = "200"
+        };
+
+        // Act
+        builder.AddHeading(3, "Section", style);
+        builder.Save();
+
+        // Assert: left border is Single; top/bottom/right are Nil to force box-mode rendering
+        _stream.Position = 0;
+        using var doc = WordprocessingDocument.Open(_stream, false);
+        var paragraph = doc.MainDocumentPart!.Document.Body!
+            .Descendants<Paragraph>()
+            .First(p => p.ParagraphProperties?.ParagraphBorders != null);
+
+        var borders = paragraph.ParagraphProperties!.ParagraphBorders!;
+        borders.GetFirstChild<LeftBorder>()!.Val!.Value.Should().Be(BorderValues.Single);
+        borders.GetFirstChild<TopBorder>()!.Val!.Value.Should().Be(BorderValues.Nil);
+        borders.GetFirstChild<BottomBorder>()!.Val!.Value.Should().Be(BorderValues.Nil);
+        borders.GetFirstChild<RightBorder>()!.Val!.Value.Should().Be(BorderValues.Nil);
+    }
+
+    [Fact]
+    public void AddHeading_WithAllFourBorders_ShouldNotAddNilBorders()
+    {
+        // Arrange
+        using var builder = new OpenXmlDocumentBuilder(_stream, _horizontalProvider);
+        var style = CreateDefaultHeadingStyle() with
+        {
+            ShowBorder = true,
+            BorderPosition = "left,top,right,bottom",
+            BorderColor = "0066cc",
+            BorderSize = 12,
+            BorderSpace = 4
+        };
+
+        // Act
+        builder.AddHeading(2, "Section", style);
+        builder.Save();
+
+        // Assert: all four borders are Single, none are Nil
+        _stream.Position = 0;
+        using var doc = WordprocessingDocument.Open(_stream, false);
+        var paragraph = doc.MainDocumentPart!.Document.Body!
+            .Descendants<Paragraph>()
+            .First(p => p.ParagraphProperties?.ParagraphBorders != null);
+
+        var borders = paragraph.ParagraphProperties!.ParagraphBorders!;
+        borders.GetFirstChild<LeftBorder>()!.Val!.Value.Should().Be(BorderValues.Single);
+        borders.GetFirstChild<TopBorder>()!.Val!.Value.Should().Be(BorderValues.Single);
+        borders.GetFirstChild<BottomBorder>()!.Val!.Value.Should().Be(BorderValues.Single);
+        borders.GetFirstChild<RightBorder>()!.Val!.Value.Should().Be(BorderValues.Single);
+    }
+
+    [Fact]
+    public void AddHeading_WithBottomBorderOnly_ShouldNotAddNilBorders()
+    {
+        // Arrange
+        using var builder = new OpenXmlDocumentBuilder(_stream, _horizontalProvider);
+        var style = CreateDefaultHeadingStyle() with
+        {
+            ShowBorder = true,
+            BorderPosition = "bottom",
+            BorderColor = "cccccc",
+            BorderSize = 8,
+            BorderSpace = 2
+        };
+
+        // Act
+        builder.AddHeading(2, "Section", style);
+        builder.Save();
+
+        // Assert: only bottom border exists, no Nil borders added (box-mode only applies to left)
+        _stream.Position = 0;
+        using var doc = WordprocessingDocument.Open(_stream, false);
+        var paragraph = doc.MainDocumentPart!.Document.Body!
+            .Descendants<Paragraph>()
+            .First(p => p.ParagraphProperties?.ParagraphBorders != null);
+
+        var borders = paragraph.ParagraphProperties!.ParagraphBorders!;
+        borders.GetFirstChild<BottomBorder>()!.Val!.Value.Should().Be(BorderValues.Single);
+        borders.GetFirstChild<LeftBorder>().Should().BeNull();
+        borders.GetFirstChild<TopBorder>().Should().BeNull();
+        borders.GetFirstChild<RightBorder>().Should().BeNull();
+    }
+
     public void Dispose()
     {
         _stream?.Dispose();