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 ![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. +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 -![Elasticsearch](/syntax/images/observability.png "elasticsearch") +![Elasticsearch](/syntax/images/observability.png "Different title") ``` -### Inline image sizing +![Elasticsearch](/syntax/images/observability.png "Different title =50%x50%") + -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 -![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 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 -![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 +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 """ - Elasticsearch + Elasticsearch """ type ``supports --url-path-prefix`` () = @@ -45,13 +45,13 @@ type ``supports --url-path-prefix`` () = [] let ``validate image src contains prefix`` () = docs |> convertsToContainingHtml """ - Elasticsearch + Elasticsearch """ [] let ``validate image src contains prefix when referenced relatively`` () = docs |> converts "folder/relative.md" |> containsHtml """ - Elasticsearch + Elasticsearch """ [] @@ -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 """ - Elasticsearch + Elasticsearch """ [] 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 """ -

Elasticsearch

+

Elasticsearch

""" type ``relative path to image`` () = @@ -26,7 +26,7 @@ type ``relative path to image`` () = [] let ``validate HTML: preserves relative path`` () = markdown |> convertsToHtml """ -

Elasticsearch

+

Elasticsearch

""" type ``supplying a tittle`` () = @@ -37,7 +37,7 @@ type ``supplying a tittle`` () = [] let ``validate HTML: includes title`` () = markdown |> convertsToHtml """ -

Elasticsearch

+

Elasticsearch

""" 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 """ -

o

+

o

""" 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 """ -

o

+

o

""" 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 """ -

o

+

o

"""