diff --git a/docs/syntax/images.md b/docs/syntax/images.md
index 29b4e427e..8c04f5bbd 100644
--- a/docs/syntax/images.md
+++ b/docs/syntax/images.md
@@ -60,38 +60,40 @@ Here is the same image used inline 
```
-Including a title can be done by supplying it as an optional argument.
+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.
```markdown
-
+
```
-### Inline image sizing
+
+
-Inline images are supplied at the end through the title argument.
+### Inline image sizing
-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
-
-
+
+
```
+In this case, the alt text will be used as both the `alt` and `title` attributes, 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
-
-
-
+
+
+
```
@@ -138,7 +140,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
:::
::::
diff --git a/src/Elastic.Markdown/Myst/Directives/Image/ImageBlock.cs b/src/Elastic.Markdown/Myst/Directives/Image/ImageBlock.cs
index 6e900b6db..e9ede80fe 100644
--- a/src/Elastic.Markdown/Myst/Directives/Image/ImageBlock.cs
+++ b/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 = string.IsNullOrEmpty(explicitTitle) ? Alt : explicitTitle;
Align = Prop("align");
Height = Prop("height", "h");
diff --git a/src/Elastic.Markdown/Myst/Renderers/HtmxLinkInlineRenderer.cs b/src/Elastic.Markdown/Myst/Renderers/HtmxLinkInlineRenderer.cs
index c7dbede0c..9114f7fe8 100644
--- a/src/Elastic.Markdown/Myst/Renderers/HtmxLinkInlineRenderer.cs
+++ b/src/Elastic.Markdown/Myst/Renderers/HtmxLinkInlineRenderer.cs
@@ -20,7 +20,6 @@ protected override void Write(HtmlRenderer renderer, LinkInline link)
{
if (renderer.EnableHtmlForInline && !link.IsImage)
{
- // ReSharper disable once UnusedVariable
if (link.GetData(nameof(ParserContext.CurrentUrlPath)) is not string currentUrl)
{
base.Write(renderer, link);
@@ -70,9 +69,42 @@ protected override void Write(HtmlRenderer renderer, LinkInline link)
_ = renderer.Write("");
}
+ else if (link.IsImage)
+ {
+ // Handle inline images with ALT override logic
+ WriteImage(renderer, link);
+ }
else
base.Write(renderer, link);
}
+
+ private static void WriteImage(HtmlRenderer renderer, LinkInline link)
+ {
+ _ = renderer.Write("
");
+ }
}
public static class CustomLinkInlineRendererExtensions
diff --git a/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs b/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
index 040509985..079970d6b 100644
--- a/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
+++ b/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
@@ -203,7 +203,7 @@ public class ReplaceInImageTitle(ITestOutputHelper output) : InlineTest(output,
[Fact]
public void OnlySeesGlobalVariable() =>
Html.Should().NotContain("title=\"{{hello-world}}\"")
- .And.Contain("title=\"Hello World\"");
+ .And.Contain("title=\"Observability\"");
}
public class MutationOperatorTest(ITestOutputHelper output) : InlineTest(output,
diff --git a/tests/authoring/Blocks/ImageBlocks.fs b/tests/authoring/Blocks/ImageBlocks.fs
index 7231f8d5a..2230bb8f6 100644
--- a/tests/authoring/Blocks/ImageBlocks.fs
+++ b/tests/authoring/Blocks/ImageBlocks.fs
@@ -18,7 +18,7 @@ type ``static path to image`` () =
[]
let ``validate src is anchored`` () =
markdown |> convertsToContainingHtml """
-
+
"""
type ``supports --url-path-prefix`` () =
@@ -45,13 +45,13 @@ type ``supports --url-path-prefix`` () =
[]
let ``validate image src contains prefix`` () =
docs |> convertsToContainingHtml """
-
+
"""
[]
let ``validate image src contains prefix when referenced relatively`` () =
docs |> converts "folder/relative.md" |> containsHtml """
-
+
"""
[]
@@ -73,7 +73,7 @@ type ``image ref out of scope`` () =
[]
let ``validate image src contains prefix and is anchored to documentation scope root`` () =
docs |> convertsToContainingHtml """
-
+
"""
[]
diff --git a/tests/authoring/Inline/InlineAppliesTo.fs b/tests/authoring/Inline/InlineAppliesTo.fs
index e9258fb34..7b099111a 100644
--- a/tests/authoring/Inline/InlineAppliesTo.fs
+++ b/tests/authoring/Inline/InlineAppliesTo.fs
@@ -15,7 +15,7 @@ type ``static path to image`` () =
[]
let ``validate HTML: generates link and alt attr`` () =
markdown |> convertsToHtml """
- 
+ 
"""
type ``relative path to image`` () =
@@ -26,7 +26,7 @@ type ``relative path to image`` () =
[]
let ``validate HTML: preserves relative path`` () =
markdown |> convertsToHtml """
- 
+ 
"""
type ``supplying a tittle`` () =
@@ -37,7 +37,7 @@ type ``supplying a tittle`` () =
[]
let ``validate HTML: includes title`` () =
markdown |> convertsToHtml """
- 
+ 
"""
type ``supplying a tittle with width and height`` () =
@@ -48,7 +48,7 @@ type ``supplying a tittle with width and height`` () =
[]
let ``validate HTML: does not include width and height in title`` () =
markdown |> convertsToHtml """
- 
+ 
"""
type ``supplying a tittle with width and height in percentage`` () =
@@ -59,7 +59,7 @@ type ``supplying a tittle with width and height in percentage`` () =
[]
let ``validate HTML: does not include width and height in title`` () =
markdown |> convertsToHtml """
- 
+ 
"""
type ``supplying a tittle with width only`` () =
static let markdown = Setup.Markdown """
@@ -69,5 +69,5 @@ type ``supplying a tittle with width only`` () =
[]
let ``validate HTML: sets height to width if not supplied`` () =
markdown |> convertsToHtml """
- 
+ 
"""