Merge pull request #165 from jongalloway/copilot/support-marpit-image-alignment

Support Marpit image alignment keywords and split-background layout

Author: jongalloway

doc/marp-markdown.md

@@ -49,8 +49,8 @@ CLI options, theme CSS loading, template usage, and PPTX rendering behavior. The
 | Marpit | Spot directives with `_` prefix | Apply a local directive to one slide only | Supported | All recognised directive keys work with a `_` prefix (e.g. `_class`, `_paginate`, `_backgroundColor`, `_color`). Spot directives apply to the current slide only and do not carry forward to subsequent slides. |
 | Marpit | `headingDivider` | Split slides before headings automatically | Supported subset | Parsed from front matter as an integer 1–6; slides are split before headings at or above that level. |
 | Marpit | Header / footer directives | Per-slide repeated content | Supported | `header` and `footer` string values are stored in `SlideStyle` and emitted into PPTX text shapes on each slide. |
-| Marpit | Extended image syntax | Width, height, filters, `bg`, split backgrounds | Partially supported | Normal Markdown images are parsed; `![bg](url)` is promoted to a slide background. Other Marpit image keywords (width, height, percentage, split) are treated as alt text with no effect on sizing or layout. |
-| Marpit | Background image syntax via image alt text | `![bg](...)` and related | Supported subset | `![bg](url)` sets the slide background image. Modifiers in the alt text (`bg cover`, `bg contain`, `bg left`, `bg right`, percentage sizing) are not yet parsed; the image is always rendered full-bleed. A `backgroundImage` directive on the same slide takes precedence over `![bg](...)`. See [Background Image Precedence](#background-image-precedence) below. |
+| Marpit | Extended image syntax | Width, height, filters, `bg`, split backgrounds | Partially supported | Normal Markdown images are parsed; `![bg](url)` is promoted to a slide background. Marpit width/height/percentage sizing keywords (`w:`, `h:`, `N%`) are parsed and applied. Alignment keywords `left`/`right` are parsed and affect image placement within the content frame. Split backgrounds (`![bg left]`, `![bg right]`) are supported and render each image in its respective slide half. Other modifiers (filters, `bg cover`, `bg contain`, percentage-sized backgrounds) are not yet implemented. |
+| Marpit | Background image syntax via image alt text | `![bg](...)` and related | Supported subset | `![bg](url)` sets the slide background image (always full-bleed). `![bg left](url)` and `![bg right](url)` render the image in the left or right half of the slide respectively (split background layout). A `backgroundImage` directive on the same slide takes precedence over plain `![bg](...)`. Other modifiers (`bg cover`, `bg contain`, percentage sizing in the alt text) are not yet parsed. See [Background Image Precedence](#background-image-precedence) below. |
 | Marpit | Fragmented lists | Incremental list reveal | Not supported | No fragment model in parser or renderer. |
 | Marpit | Theme CSS | CSS-driven slide theming | Supported subset | CSS extraction for fonts, sizes, colors, padding, background, line-height, letter-spacing, text-transform, font-weight, and code style. See the CSS property reference below. |
 | Marp Core | Built-in theme names | Themes such as `default`, `gaia`, `uncover` | Name-only unless CSS is supplied | Theme name is stored, but real styling comes from parsed CSS or defaults. |

src/MarpToPptx.Core/Authoring/SlideIdentityGenerator.cs

@@ -146,6 +146,14 @@ public static string ComputeSlideContentHash(Slide slideModel)
         {
             sb.Append("\x01smartArt\x01").Append(smartArt);
         }
+        if (slideModel.Style.SplitBackgroundLeft is { } splitLeft)
+        {
+            sb.Append("\x01splitBgLeft\x01").Append(splitLeft);
+        }
+        if (slideModel.Style.SplitBackgroundRight is { } splitRight)
+        {
+            sb.Append("\x01splitBgRight\x01").Append(splitRight);
+        }
 
         var hash = SHA256.HashData(Encoding.UTF8.GetBytes(sb.ToString()));
         return "sha256:" + Convert.ToHexString(hash).ToLowerInvariant();

src/MarpToPptx.Core/Models/SlideDeck.cs

@@ -105,6 +105,18 @@ public sealed class SlideStyle
     /// </summary>
     public string? SmartArtHint { get; init; }
 
+    /// <summary>
+    /// Source path for the left-half split background image, promoted from a <c>![bg left](url)</c> syntax image.
+    /// When set, the image is rendered in the left half of the slide as a full-bleed background.
+    /// </summary>
+    public string? SplitBackgroundLeft { get; init; }
+
+    /// <summary>
+    /// Source path for the right-half split background image, promoted from a <c>![bg right](url)</c> syntax image.
+    /// When set, the image is rendered in the right half of the slide as a full-bleed background.
+    /// </summary>
+    public string? SplitBackgroundRight { get; init; }
+
     public Dictionary<string, string> Directives { get; } = new(StringComparer.OrdinalIgnoreCase);
 }
 
@@ -179,19 +191,26 @@ public sealed record BulletListItem(IReadOnlyList<InlineSpan> Spans, int Depth =
 /// image width to this percentage of the full slide width; height is preserved from aspect ratio.
 /// Ignored when <see cref="ExplicitWidth"/> or <see cref="ExplicitHeight"/> is set.
 /// </param>
+/// <param name="Alignment">
+/// Horizontal alignment hint parsed from a Marpit alignment keyword in the alt text
+/// (e.g. <c>![left](img.png)</c> or <c>![right](img.png)</c>).
+/// Accepted values are <c>"left"</c>, <c>"right"</c>, or <c>null</c> for the default centered placement.
+/// The keyword is stripped from the alt text when recognised.
+/// </param>
 public sealed record ImageElement(
     string Source,
     string AltText,
     string? Caption = null,
     double? ExplicitWidth = null,
     double? ExplicitHeight = null,
-    double? SizePercent = null) : ISlideElement
+    double? SizePercent = null,
+    string? Alignment = null) : ISlideElement
 {
     /// <summary>
     /// Backward-compatible constructor matching the original 3-parameter signature.
     /// </summary>
     public ImageElement(string Source, string AltText, string? Caption = null)
-        : this(Source, AltText, Caption, null, null, null)
+        : this(Source, AltText, Caption, null, null, null, null)
     {
     }
 }

src/MarpToPptx.Core/Parsing/MarpDirectiveParser.cs

@@ -11,6 +11,14 @@ public static SlideStyle ApplyDirective(SlideStyle style, string key, string val
         return ApplyKnownDirective(updatedStyle, key, value);
     }
 
+    /// <summary>
+    /// Returns a clone of <paramref name="style"/> with the split background image properties
+    /// set to the provided values. A <see langword="null"/> argument for either side preserves
+    /// the existing value from <paramref name="style"/>.
+    /// </summary>
+    internal static SlideStyle CloneWithSplitBackground(SlideStyle style, string? splitBackgroundLeft = null, string? splitBackgroundRight = null)
+        => Clone(style, splitBackgroundLeft: splitBackgroundLeft, splitBackgroundRight: splitBackgroundRight);
+
     /// <summary>
     /// Parses HTML-comment directives from a single slide chunk.
     /// Returns the effective style (local + spot directives applied),
@@ -202,7 +210,9 @@ private static SlideStyle Clone(
         SlideTransition? transition = null,
         int? fontSize = null,
         string? shrinkToFit = null,
-        string? smartArtHint = null)
+        string? smartArtHint = null,
+        string? splitBackgroundLeft = null,
+        string? splitBackgroundRight = null)
     {
         var clone = new SlideStyle
         {
@@ -222,6 +232,8 @@ private static SlideStyle Clone(
             FontSize = fontSize ?? source.FontSize,
             ShrinkToFit = shrinkToFit ?? source.ShrinkToFit,
             SmartArtHint = smartArtHint ?? source.SmartArtHint,
+            SplitBackgroundLeft = splitBackgroundLeft ?? source.SplitBackgroundLeft,
+            SplitBackgroundRight = splitBackgroundRight ?? source.SplitBackgroundRight,
         };
 
         foreach (var pair in source.Directives)

src/MarpToPptx.Core/Parsing/MarpMarkdownParser.cs

@@ -116,18 +116,35 @@ public SlideDeck Parse(string markdown, string? sourcePath = null, string? theme
 
             var allElements = ParseElements(cleaned);
 
-            // Promote any ![bg](url) images to slide background image.
-            // Only exact "bg" alt text (case-insensitive) is recognized in this slice.
-            // A directive-specified backgroundImage always takes precedence: if a directive
-            // (including an empty-value clear) has set BackgroundImage, bg syntax is ignored.
+            // Promote any ![bg](url) images to slide background.
+            // Supported forms:
+            //   ![bg](url)       — full-slide background (sets BackgroundImage)
+            //   ![bg left](url)  — left-half split background (sets SplitBackgroundLeft)
+            //   ![bg right](url) — right-half split background (sets SplitBackgroundRight)
+            // A directive-specified backgroundImage always takes precedence for the plain bg form:
+            // if a directive (including an empty-value clear) has set BackgroundImage, plain bg
+            // syntax is ignored. Split-background images are always promoted regardless.
             var bgImages = allElements
                 .OfType<ImageElement>()
                 .Where(img => IsBgAltText(img.AltText))
                 .ToList();
 
-            if (bgImages.Count > 0 && effectiveStyle.BackgroundImage is null)
+            foreach (var bgImg in bgImages)
             {
-                effectiveStyle = MarpDirectiveParser.ApplyDirective(effectiveStyle, "backgroundimage", bgImages[0].Source);
+                var trimmedAlt = bgImg.AltText.Trim();
+                if (IsBgLeftAltText(trimmedAlt))
+                {
+                    effectiveStyle = MarpDirectiveParser.CloneWithSplitBackground(effectiveStyle, splitBackgroundLeft: bgImg.Source);
+                }
+                else if (IsBgRightAltText(trimmedAlt))
+                {
+                    effectiveStyle = MarpDirectiveParser.CloneWithSplitBackground(effectiveStyle, splitBackgroundRight: bgImg.Source);
+                }
+                else if (effectiveStyle.BackgroundImage is null)
+                {
+                    // Plain ![bg](url) — only the first image is promoted; directive takes precedence.
+                    effectiveStyle = MarpDirectiveParser.ApplyDirective(effectiveStyle, "backgroundimage", bgImg.Source);
+                }
             }
 
             var slide = new Slide { Style = effectiveStyle, Notes = notes, NoteSpans = ParseNoteSpans(notes) };
@@ -543,8 +560,8 @@ private static IEnumerable<ISlideElement> ExtractMediaElements(ContainerInline?
 
                         if (!isBgAlt)
                         {
-                            var (explicitWidth, explicitHeight, sizePercent, cleanAltText) = MarpitImageSizingParser.Parse(altText);
-                            yield return new ImageElement(url, cleanAltText, caption, explicitWidth, explicitHeight, sizePercent);
+                            var (explicitWidth, explicitHeight, sizePercent, alignment, cleanAltText) = MarpitImageSizingParser.Parse(altText);
+                            yield return new ImageElement(url, cleanAltText, caption, explicitWidth, explicitHeight, sizePercent, alignment);
                         }
                         else
                         {
@@ -704,9 +721,29 @@ private static string ExtractInlineText(ContainerInline? inline)
     }
 
     /// <summary>
-    /// Returns <see langword="true"/> when <paramref name="altText"/> is exactly <c>bg</c>
-    /// (case-insensitive), indicating a Marpit background image marker.
+    /// Returns <see langword="true"/> when <paramref name="altText"/> is exactly <c>bg</c>,
+    /// <c>bg left</c>, or <c>bg right</c> (case-insensitive), indicating a Marpit background
+    /// image marker (full-slide, left-half, or right-half respectively).
+    /// </summary>
+    private static bool IsBgAltText(string altText)
+    {
+        var trimmed = altText.Trim();
+        return string.Equals(trimmed, "bg", StringComparison.OrdinalIgnoreCase)
+            || IsBgLeftAltText(trimmed)
+            || IsBgRightAltText(trimmed);
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> when <paramref name="trimmedAlt"/> is <c>bg left</c>
+    /// (case-insensitive), indicating a Marpit left-half split background image.
+    /// </summary>
+    private static bool IsBgLeftAltText(string trimmedAlt) =>
+        string.Equals(trimmedAlt, "bg left", StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Returns <see langword="true"/> when <paramref name="trimmedAlt"/> is <c>bg right</c>
+    /// (case-insensitive), indicating a Marpit right-half split background image.
     /// </summary>
-    private static bool IsBgAltText(string altText) =>
-        string.Equals(altText.Trim(), "bg", StringComparison.OrdinalIgnoreCase);
+    private static bool IsBgRightAltText(string trimmedAlt) =>
+        string.Equals(trimmedAlt, "bg right", StringComparison.OrdinalIgnoreCase);
 }

src/MarpToPptx.Core/Parsing/MarpitImageSizingParser.cs

@@ -11,6 +11,8 @@ namespace MarpToPptx.Core.Parsing;
 ///   <item><c>w:200px</c> — explicit width in CSS pixels</item>
 ///   <item><c>h:150px</c> — explicit height in CSS pixels</item>
 ///   <item><c>50%</c> — percentage of slide width</item>
+///   <item><c>left</c> — align image to the left of its frame</item>
+///   <item><c>right</c> — align image to the right of its frame</item>
 /// </list>
 /// Sizing tokens are stripped from the alt text; any remaining text becomes the
 /// accessible description. Units other than <c>px</c> are not currently supported
@@ -30,9 +32,13 @@ internal static partial class MarpitImageSizingParser
     [GeneratedRegex(@"(?<!\S)(\d+(?:\.\d+)?)%(?!\S)")]
     private static partial Regex PercentPattern();
 
+    // Matches standalone "left" or "right" alignment keywords (case-insensitive, whole word).
+    [GeneratedRegex(@"(?<!\S)(left|right)(?!\S)", RegexOptions.IgnoreCase)]
+    private static partial Regex AlignmentPattern();
+
     /// <summary>
-    /// Parses Marpit image sizing tokens from <paramref name="altText"/> and returns the
-    /// parsed sizing values along with the alt text with sizing tokens removed.
+    /// Parses Marpit image sizing and alignment tokens from <paramref name="altText"/> and returns the
+    /// parsed values along with the alt text with recognised tokens removed.
     /// </summary>
     /// <param name="altText">Raw alt-text string from the Markdown image (e.g. <c>"w:200px My photo"</c>).</param>
     /// <returns>
@@ -41,19 +47,21 @@ internal static partial class MarpitImageSizingParser
     ///   <item><c>ExplicitWidth</c> — layout units, or <c>null</c> if not specified.</item>
     ///   <item><c>ExplicitHeight</c> — layout units, or <c>null</c> if not specified.</item>
     ///   <item><c>SizePercent</c> — 0–100 value, or <c>null</c> if not specified.</item>
-    ///   <item><c>CleanAltText</c> — alt text with all recognised sizing tokens removed.</item>
+    ///   <item><c>Alignment</c> — <c>"left"</c>, <c>"right"</c>, or <c>null</c> if not specified.</item>
+    ///   <item><c>CleanAltText</c> — alt text with all recognised tokens removed.</item>
     /// </list>
     /// </returns>
-    public static (double? ExplicitWidth, double? ExplicitHeight, double? SizePercent, string CleanAltText) Parse(string altText)
+    public static (double? ExplicitWidth, double? ExplicitHeight, double? SizePercent, string? Alignment, string CleanAltText) Parse(string altText)
     {
         if (string.IsNullOrWhiteSpace(altText))
         {
-            return (null, null, null, altText ?? string.Empty);
+            return (null, null, null, null, altText ?? string.Empty);
         }
 
         double? explicitWidth = null;
         double? explicitHeight = null;
         double? sizePercent = null;
+        string? alignment = null;
 
         var cleaned = altText;
 
@@ -97,9 +105,20 @@ public static (double? ExplicitWidth, double? ExplicitHeight, double? SizePercen
             return string.Empty;
         });
 
+        // Process alignment keywords (left/right): strip and record the first one found.
+        cleaned = AlignmentPattern().Replace(cleaned, match =>
+        {
+            if (alignment is null)
+            {
+                alignment = match.Groups[1].Value.ToLowerInvariant();
+            }
+
+            return string.Empty;
+        });
+
         // Normalise whitespace left by removed tokens.
         cleaned = string.Join(' ', cleaned.Split(' ', StringSplitOptions.RemoveEmptyEntries));
 
-        return (explicitWidth, explicitHeight, sizePercent, cleaned);
+        return (explicitWidth, explicitHeight, sizePercent, alignment, cleaned);
     }
 }

src/MarpToPptx.Pptx/Rendering/OpenXmlPptxRenderer.cs

@@ -869,8 +869,14 @@ titleRect is not null
                     }
                     break;
                 case ImageElement image:
+                    var imageXAlign = image.Alignment switch
+                    {
+                        "left" => 0.0,
+                        "right" => 1.0,
+                        _ => 0.5,
+                    };
                     AddImage(context, frame, image.Source, image.AltText, image.Caption,
-                        explicitWidth: image.ExplicitWidth, explicitHeight: image.ExplicitHeight, sizePercent: image.SizePercent);
+                        xAlign: imageXAlign, explicitWidth: image.ExplicitWidth, explicitHeight: image.ExplicitHeight, sizePercent: image.SizePercent);
                     break;
                 case VideoElement video:
                     AddVideo(context, frame, video.Source, video.AltText);
@@ -1314,8 +1320,14 @@ element is HeadingElement h &&
                             }
                             break;
                         case ImageElement image:
+                            var residualXAlign = image.Alignment switch
+                            {
+                                "left" => 0.0,
+                                "right" => 1.0,
+                                _ => 0.5,
+                            };
                             AddImage(context, frame, image.Source, image.AltText, image.Caption,
-                                explicitWidth: image.ExplicitWidth, explicitHeight: image.ExplicitHeight, sizePercent: image.SizePercent);
+                                xAlign: residualXAlign, explicitWidth: image.ExplicitWidth, explicitHeight: image.ExplicitHeight, sizePercent: image.SizePercent);
                             break;
                         case VideoElement video:
                             AddVideo(context, frame, video.Source, video.AltText);
@@ -2300,6 +2312,22 @@ private static void AddBackground(SlideStyle style, SlideRenderContext context)
             var (xAlign, yAlign) = ParseBackgroundPosition(backgroundPosition);
             AddImage(context, new Rect(0, 0, SlideWidthEmu / LayoutScale, SlideHeightEmu / LayoutScale), backgroundImage, string.Empty, useFullBleed: useFullBleed, xAlign: xAlign, yAlign: yAlign);
         }
+
+        // Render split background images (from ![bg left] / ![bg right] syntax).
+        // Each image is placed in the corresponding half of the slide as a full-bleed background.
+        var slideWidth = SlideWidthEmu / LayoutScale;
+        var slideHeight = SlideHeightEmu / LayoutScale;
+        var halfWidth = slideWidth / 2.0;
+
+        if (!string.IsNullOrWhiteSpace(style.SplitBackgroundLeft))
+        {
+            AddImage(context, new Rect(0, 0, halfWidth, slideHeight), style.SplitBackgroundLeft, string.Empty, useFullBleed: true);
+        }
+
+        if (!string.IsNullOrWhiteSpace(style.SplitBackgroundRight))
+        {
+            AddImage(context, new Rect(halfWidth, 0, halfWidth, slideHeight), style.SplitBackgroundRight, string.Empty, useFullBleed: true);
+        }
     }
 
     private static void AddTextShape(SlideRenderContext context, Rect frame, string text, TextStyle style, bool isTitle = false)