Use the Markdown title for inline image title attributes

docs/syntax/images.md

@@ -93,7 +93,7 @@ Titles are optional making this the minimal syntax required:
 ![Elasticsearch](/syntax/images/observability.png)
 ```
 
-For inline images, the alt text always overrides any title specified in the Markdown. This ensures consistent accessibility where both the `alt` and `title` attributes contain the same descriptive text.
+For inline images, the Markdown title is used as the `title` attribute, and the alt text is used as the `alt` attribute. If you don't specify a title, the alt text is used for both attributes.
 
 ```markdown
 ![Elasticsearch](/syntax/images/observability.png "Different title")
@@ -110,7 +110,7 @@ Image sizing is specified through the title argument. You can specify just the s
 ![alt](img.png "=W")
 ```
 
-In this case, the alt text will be used as both the `alt` and `title` attributes, and the size parameters will be applied.
+In this case, the alt text is used as both the `alt` and `title` attributes, and the size parameters are applied.
 
 `W` and `H` can be either an absolute number in pixels or a number followed by `%` to indicate relative sizing.
 

src/Elastic.Markdown/Myst/Renderers/HtmxLinkInlineRenderer.cs

@@ -71,7 +71,7 @@ protected override void Write(HtmlRenderer renderer, LinkInline link)
 		}
 		else if (link.IsImage)
 		{
-			// Handle inline images with ALT override logic
+			// Handle inline images
 			WriteImage(renderer, link);
 		}
 		else
@@ -95,8 +95,14 @@ private static void WriteImage(HtmlRenderer renderer, LinkInline link)
 		// Write any additional attributes (like width/height from styling instructions)
 		_ = renderer.WriteAttributes(link);
 
-		// Always use alt text as title for accessibility consistency
-		if (link.FirstChild != null)
+		// Use the Markdown title when provided, otherwise fall back to the alt text
+		if (!string.IsNullOrEmpty(link.Title))
+		{
+			_ = renderer.Write(" title=\"");
+			_ = renderer.WriteEscape(link.Title);
+			_ = renderer.Write('"');
+		}
+		else if (link.FirstChild != null)
 		{
 			_ = renderer.Write(" title=\"");
 			renderer.WriteChildren(link);

tests/Elastic.Authoring.Tests/Inline/InlineImages.cs

@@ -44,7 +44,7 @@ public class SupplyingATitle : MarkdownTest
 	public async Task ValidateHtml() =>
 		await Docs.ConvertsToHtml(
 			"""
-		<p><img src="/_static/img/observability.png" alt="Elasticsearch" title="Elasticsearch" /></p>
+		<p><img src="/_static/img/observability.png" alt="Elasticsearch" title="Hello world" /></p>
 		"""
 		);
 }
@@ -58,7 +58,7 @@ public class SupplyingATitleWithWidthAndHeight : MarkdownTest
 	[Test, DisplayName("validate HTML: does not include width and height in title")]
 	public async Task ValidateHtml() =>
 		await Docs.ConvertsToHtml("""
-		<p><img src="/obs.png" width="250px" height="400px" alt="o" title="o"/></p>
+		<p><img src="/obs.png" width="250px" height="400px" alt="o" title="Title"/></p>
 		""");
 }
 
@@ -71,7 +71,7 @@ public class SupplyingATitleWithWidthAndHeightInPercentage : MarkdownTest
 	[Test, DisplayName("validate HTML: does not include width and height in title")]
 	public async Task ValidateHtml() =>
 		await Docs.ConvertsToHtml("""
-		<p><img src="/obs.png" width="50%" height="40%" alt="o" title="o"/></p>
+		<p><img src="/obs.png" width="50%" height="40%" alt="o" title="Title"/></p>
 		""");
 }
 
@@ -84,6 +84,6 @@ public class SupplyingATitleWithWidthOnly : MarkdownTest
 	[Test, DisplayName("validate HTML: sets height to width if not supplied")]
 	public async Task ValidateHtml() =>
 		await Docs.ConvertsToHtml("""
-		<p><img src="/obs.png" width="30%" height="30%" alt="o" title="o"/></p>
+		<p><img src="/obs.png" width="30%" height="30%" alt="o" title="Title"/></p>
 		""");
 }

tests/Elastic.Markdown.Tests/Inline/InlineImageTest.cs

@@ -89,7 +89,7 @@ public void GeneratesAttributesInHtml() =>
 		);
 }
 
-// Test image sizing with title and sizing — explicit title in markdown is ignored; alt text is always used as title
+// Test image sizing with title and sizing — explicit title in markdown is used as the title; alt text stays as alt
 [InheritsTests]
 public class InlineImageWithTitleAndSizingTest() : InlineTest<LinkInline>(
 	"""
@@ -104,7 +104,7 @@ public class InlineImageWithTitleAndSizingTest() : InlineTest<LinkInline>(
 	public void GeneratesAttributesInHtml() =>
 		// language=html
 		Html.ShouldContainHtml(
-			"""<p><img src="/docs/_static/img/observability.png" alt="Elasticsearch" width="50%" height="50%" title="Elasticsearch" /></p>"""
+			"""<p><img src="/docs/_static/img/observability.png" alt="Elasticsearch" width="50%" height="50%" title="My Title" /></p>"""
 		);
 }