Implement border option for images

Co-authored-by: theletterf <[email protected]>

Author: Copilot

docs/syntax/images.md

@@ -77,6 +77,30 @@ Screenshots are images displayed with a box-shadow. Define a screenshot by addin
 :screenshot:
 :::
 
+## Borders
+
+Images can have a border to improve contrast with the page background. Add the `:border:` attribute to a block-level image directive to add a 1px border.
+
+```markdown
+:::{image} /syntax/images/observability.png
+:alt: Elasticsearch with border
+:width: 400px
+:border:
+:::
+```
+
+:::{image} /syntax/images/observability.png
+:alt: Elasticsearch with border
+:width: 400px
+:border:
+:::
+
+The border is especially useful for screenshots with white or light backgrounds that might blend with the documentation page.
+
+:::{note}
+The `:border:` option only applies to images used with the image directive. Inline images do not support borders.
+:::
+
 ## Inline images
 
 ```markdown

src/Elastic.Documentation.Site/Assets/markdown/images.css

@@ -21,5 +21,8 @@
 		.screenshot {
 			@apply border-grey-20 bg-grey-10 border-1 p-4 shadow-md;
 		}
+		.border {
+			@apply border-grey-20 border-1;
+		}
 	}
 }

src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs

@@ -126,6 +126,7 @@ private static void WriteImage(HtmlRenderer renderer, ImageBlock block)
 			Target = block.Target,
 			Width = block.Width,
 			Screenshot = block.Screenshot,
+			Border = block.Border,
 			ImageUrl = imageUrl,
 		});
 		RenderRazorSlice(slice, renderer);
@@ -147,6 +148,7 @@ private static void WriteImageCarousel(HtmlRenderer renderer, ImageCarouselBlock
 				Width = img.Width,
 				Scale = img.Scale ?? string.Empty,
 				Screenshot = img.Screenshot,
+				Border = img.Border,
 				Target = img.Target,
 				ImageUrl = img.ImageUrl
 			}).ToList(),
@@ -191,6 +193,7 @@ private static void WriteFigure(HtmlRenderer renderer, ImageBlock block)
 			Target = block.Target,
 			Width = block.Width,
 			Screenshot = block.Screenshot,
+			Border = block.Border,
 			ImageUrl = imageUrl,
 		});
 		RenderRazorSlice(slice, renderer);

src/Elastic.Markdown/Myst/Directives/Image/ImageBlock.cs

@@ -45,6 +45,11 @@ public class ImageBlock(DirectiveBlockParser parser, ParserContext context)
 	/// </summary>
 	public string? Screenshot { get; set; }
 
+	/// <summary>
+	/// When set, adds a border to the image.
+	/// </summary>
+	public string? Border { get; set; }
+
 	/// <summary>
 	/// The uniform scaling factor of the image. The default is “100 %”, i.e. no scaling.
 	/// </summary>
@@ -88,6 +93,9 @@ public override void FinalizeAndValidate(ParserContext context)
 		// Set Screenshot to "screenshot" if the :screenshot: option is present
 		Screenshot = Prop("screenshot") != null ? "screenshot" : null;
 
+		// Set Border to "border" if the :border: option is present
+		Border = Prop("border") != null ? "border" : null;
+
 		ExtractImageUrl(context);
 	}
 

src/Elastic.Markdown/Myst/Directives/Image/ImageView.cshtml

@@ -1,6 +1,9 @@
 @inherits RazorSlice<Elastic.Markdown.Myst.Directives.Image.ImageViewModel>
+@{
+	var cssClasses = string.Join(" ", new[] { Model.Screenshot, Model.Border }.Where(c => !string.IsNullOrEmpty(c)));
+}
 <a class="reference internal image-reference" href="javascript:void(0)" onclick="document.getElementById('[email protected]').style.display='flex'">
-	<img loading="lazy" title="@Model.Title" alt="@(Model.Alt == string.Empty ? HtmlString.Empty : new HtmlString(Model.Alt))" src="@Model.ImageUrl" style="@Model.Style" class="@Model.Screenshot" />
+	<img loading="lazy" title="@Model.Title" alt="@(Model.Alt == string.Empty ? HtmlString.Empty : new HtmlString(Model.Alt))" src="@Model.ImageUrl" style="@Model.Style" class="@cssClasses" />
 	@Model.RenderBlock()
 </a>
 

src/Elastic.Markdown/Myst/Directives/Image/ImageViewModel.cs

@@ -26,6 +26,7 @@ public class ImageViewModel : DirectiveViewModel
 			? Guid.NewGuid().ToString("N")[..8] // fallback to a random ID if ImageUrl is null or empty
 			: ShortId.Create(ImageUrl);
 	public required string? Screenshot { get; init; }
+	public required string? Border { get; init; }
 
 	public string Style
 	{

tests/Elastic.Markdown.Tests/Directives/ImageTests.cs

@@ -66,3 +66,36 @@ public void WarnsOnExternalUri()
 			.And.OnlyContain(d => d.Severity == Severity.Warning);
 	}
 }
+
+public class ImageBlockWithBorderTests(ITestOutputHelper output) : DirectiveTest<ImageBlock>(output,
+"""
+:::{image} img/observability.png
+:alt: Elasticsearch
+:width: 400px
+:border:
+:::
+"""
+)
+{
+	protected override void AddToFileSystem(MockFileSystem fileSystem) =>
+		fileSystem.AddFile(@"docs/img/observability.png", "");
+
+	[Fact]
+	public void ParsesBlock() => Block.Should().NotBeNull();
+
+	[Fact]
+	public void ParsesBorderProperty()
+	{
+		Block!.Alt.Should().Be("Elasticsearch");
+		Block!.Width.Should().Be("400px");
+		Block!.ImageUrl.Should().Be("/img/observability.png");
+		Block!.Border.Should().Be("border");
+	}
+
+	[Fact]
+	public void ImageIsFoundSoNoErrorIsEmitted()
+	{
+		Block!.Found.Should().BeTrue();
+		Collector.Diagnostics.Count.Should().Be(0);
+	}
+}