Automatically use alt text as title for images when no title is provided

docs/syntax/images.md

@@ -29,6 +29,8 @@ Or, use the `image` directive.
 :::
 ```
 
+Note: When using the image directive, if you specify an `:alt:` value but no `:title:` value, the alt text will automatically be used as the title.
+
 :::{image} /syntax/images/observability.png
 :alt: Elasticsearch
 :width: 250px
@@ -60,38 +62,39 @@ Here is the same image used inline ![Elasticsearch](/syntax/images/observability
 
 ### Inline image titles
 
-Titles are optional making this the minimal syntax required
+Titles are optional making this the minimal syntax required:
 
 ```markdown
 ![Elasticsearch](/syntax/images/observability.png)
 ```
 
-Including a title can be done by supplying it as an optional argument.
+When no title is explicitly provided, the alt text is automatically used as the title.
+
+If you want a different title, you can supply it as an optional argument:
 
 ```markdown
-![Elasticsearch](/syntax/images/observability.png "elasticsearch")
+![Elasticsearch](/syntax/images/observability.png "Different title")
 ```
 
 ### Inline image sizing
 
-Inline images are supplied at the end through the title argument.
-
-This is done to maintain maximum compatibility with markdown parsers
-and previewers. 
+Image sizing is specified through the title argument. You can specify just the size without needing to provide a redundant title:
 
 ```markdown
-![alt](img.png "title =WxH")
-![alt](img.png "title =W")
+![alt](img.png "=WxH")
+![alt](img.png "=W")
 ```
 
+In this case, the alt text will automatically be used as the title, and the size parameters will be applied.
+
 `W` and `H` can be either an absolute number in pixels or a number followed by `%` to indicate relative sizing.
 
 If `H` is omitted `W` is used as the height as well.
 
 ```markdown
-![alt](img.png "title =250x330")
-![alt](img.png "title =50%x40%")
-![alt](img.png "title =50%")
+![alt](img.png "=250x330")
+![alt](img.png "=50%x40%")
+![alt](img.png "=50%")
 ```
 
 
@@ -138,7 +141,7 @@ The image carousel directive builds upon the image directive.
 
 :::{image} images/applies.png
 :alt: Second image description
-:title: Second image title
+### Title is optional - alt text will be used as title if not specified
 :::
 
 ::::

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

@@ -74,7 +74,9 @@ public override void FinalizeAndValidate(ParserContext context)
 	{
 		Label = Prop("label", "name");
 		Alt = Prop("alt")?.ReplaceSubstitutions(context) ?? string.Empty;
-		Title = Prop("title")?.ReplaceSubstitutions(context);
+		// Use Alt as Title if no explicit Title is provided
+		var explicitTitle = Prop("title")?.ReplaceSubstitutions(context);
+		Title = explicitTitle ?? (!string.IsNullOrEmpty(Alt) ? Alt : null);
 
 		Align = Prop("align");
 		Height = Prop("height", "h");

tests/authoring/Blocks/ImageBlocks.fs

@@ -18,7 +18,7 @@ type ``static path to image`` () =
     [<Fact>]
     let ``validate src is anchored`` () =
         markdown |> convertsToContainingHtml """
-            <img loading="lazy" alt="Elasticsearch" src="/img/observability.png" style="width: 250px;" class="screenshot">
+            <img loading="lazy" title="Elasticsearch" alt="Elasticsearch" src="/img/observability.png" style="width: 250px;" class="screenshot">
        """
 
 type ``supports --url-path-prefix`` () =
@@ -45,13 +45,13 @@ type ``supports --url-path-prefix`` () =
     [<Fact>]
     let ``validate image src contains prefix`` () =
         docs |> convertsToContainingHtml """
-            <img loading="lazy" alt="Elasticsearch" src="/docs/img/observability.png" style="width: 250px;" class="screenshot">
+            <img loading="lazy" title="Elasticsearch" alt="Elasticsearch" src="/docs/img/observability.png" style="width: 250px;" class="screenshot">
        """
 
     [<Fact>]
     let ``validate image src contains prefix when referenced relatively`` () =
         docs |> converts "folder/relative.md" |> containsHtml """
-            <img loading="lazy" alt="Elasticsearch" src="/docs/img/observability.png" style="width: 250px;" class="screenshot">
+            <img loading="lazy" title="Elasticsearch" alt="Elasticsearch" src="/docs/img/observability.png" style="width: 250px;" class="screenshot">
        """
 
     [<Fact>]
@@ -73,7 +73,7 @@ type ``image ref out of scope`` () =
     [<Fact>]
     let ``validate image src contains prefix and is anchored to documentation scope root`` () =
         docs |> convertsToContainingHtml """
-            <img loading="lazy" alt="Elasticsearch" src="/docs/img/observability.png" style="width: 250px;" class="screenshot">
+            <img loading="lazy" title="Elasticsearch" alt="Elasticsearch" src="/docs/img/observability.png" style="width: 250px;" class="screenshot">
        """
 
     [<Fact>]