Add :applies_to: prop to admonitions

reakaleek · reakaleek · commit e4ce6485137c · 2025-09-29T15:08:11.000+02:00
diff --git a/docs/syntax/admonitions.md b/docs/syntax/admonitions.md
@@ -150,38 +150,53 @@ It can *span* multiple lines and supports inline formatting.
 
 :::::
 
-## Collapsible admonitions
+## Applies to information
 
-:::{warning}
-Collapsible admonitions are deprecated. Do not use them. Use [dropdowns](./dropdowns.md) instead.
-:::
-
-Use `:open: <bool>` to make an admonition collapsible.
+Admonitions support the `applies_to` property to indicate which products or versions the information applies to.
 
 :::::{tab-set}
 
 ::::{tab-item} Output
 
 :::{note}
-:open:
+:applies_to: stack: ga 9.1.0
+
+This note applies to the Elastic Stack GA version 9.1.0.
+:::
 
-Longer content can be collapsed to take less space.
+:::{warning}
+:applies_to: serverless: ga
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+This warning applies to serverless GA.
 :::
 
+:::{tip}
+:applies_to: { ess:, ece: }
+
+This tip applies to ECH and ECE.
+:::
 
 ::::
 
 ::::{tab-item} Markdown
 
 ```markdown
 :::{note}
-:open:
+:applies_to: stack: ga 9.1.0
+
+This note applies to the Elastic Stack GA version 9.1.0.
+:::
+
+:::{warning}
+:applies_to: serverless: ga
+
+This warning applies to serverless GA.
+:::
 
-Longer content can be collapsed to take less space.
+:::{tip}
+:applies_to: { ess:, ece: }
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+This tip applies to ECH and ECE.
 :::
 ```
 
diff --git a/src/Elastic.Documentation.Site/Assets/markdown/admonition.css b/src/Elastic.Documentation.Site/Assets/markdown/admonition.css
@@ -3,9 +3,29 @@
 		@apply mt-4 rounded-sm border-1 pb-4;
 
 		.admonition-title {
-			@apply flex items-center gap-2 rounded-t-sm px-4 py-2 font-bold;
-			svg {
-				@apply size-6;
+			@apply flex items-center gap-3 rounded-t-sm px-4 py-2 font-bold;
+		}
+
+		.admonition-title__text {
+			@apply text-sm tracking-wider uppercase;
+		}
+
+		.applies-admonition {
+			@apply flex items-center gap-1 font-normal;
+			color: inherit;
+			.applicable-info {
+				@apply border-none bg-transparent p-0;
+				&:not(:last-child):after {
+					@apply text-sm;
+					content: ',';
+				}
+			}
+			.applicable-name,
+			.applicable-meta {
+				@apply text-sm;
+			}
+			.applicable-separator {
+				mix-blend-mode: multiply;
 			}
 		}
 		.admonition-content {
diff --git a/src/Elastic.Markdown/Myst/Directives/Admonition/AdmonitionBlock.cs b/src/Elastic.Markdown/Myst/Directives/Admonition/AdmonitionBlock.cs
@@ -9,7 +9,7 @@ namespace Elastic.Markdown.Myst.Directives.Admonition;
 
 public class DropdownBlock(DirectiveBlockParser parser, ParserContext context) : AdmonitionBlock(parser, "dropdown", context);
 
-public class AdmonitionBlock : DirectiveBlock, IBlockTitle
+public class AdmonitionBlock : DirectiveBlock, IBlockTitle, IBlockAppliesTo
 {
 	public AdmonitionBlock(DirectiveBlockParser parser, string admonition, ParserContext context) : base(parser, context)
 	{
@@ -65,6 +65,7 @@ public override void FinalizeAndValidate(ParserContext context)
 		catch
 		{
 			// If parsing fails, return null
+			// Note: Error handling is done in the YamlSerialization.Deserialize method
 			return null;
 		}
 	}
diff --git a/src/Elastic.Markdown/Myst/Directives/Admonition/AdmonitionView.cshtml b/src/Elastic.Markdown/Myst/Directives/Admonition/AdmonitionView.cshtml
@@ -1,36 +1,19 @@
+@using Elastic.Markdown.Myst.Components
 @inherits RazorSlice<Elastic.Markdown.Myst.Directives.Admonition.AdmonitionViewModel>
 <div class="admonition @Model.Directive @Model.Classes" id="@Model.CrossReferenceName" open="@Model.Open">
 	<div class="admonition-title">
-		
-		@{ 
-			switch (Model.Directive)
-			{
-				case "tip":
-					<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
-						<path stroke-linecap="round" stroke-linejoin="round" d="M12 18v-5.25m0 0a6.01 6.01 0 0 0 1.5-.189m-1.5.189a6.01 6.01 0 0 1-1.5-.189m3.75 7.478a12.06 12.06 0 0 1-4.5 0m3.75 2.383a14.406 14.406 0 0 1-3 0M14.25 18v-.192c0-.983.658-1.823 1.508-2.316a7.5 7.5 0 1 0-7.517 0c.85.493 1.509 1.333 1.509 2.316V18"/>
-					</svg>
-				   break;
-				case "warning":
-					<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
-						<path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126ZM12 15.75h.007v.008H12v-.008Z"/>
-					</svg>
-				   break;
-				case "note":
-					<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="size-6">
-						<path stroke-linecap="round" stroke-linejoin="round" d="m11.25 11.25.041-.02a.75.75 0 0 1 1.063.852l-.708 2.836a.75.75 0 0 0 1.063.853l.041-.021M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Zm-9-3.75h.008v.008H12V8.25Z" />
-					</svg>
-					break;
-				case "important":
-					<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
-						<path stroke-linecap="round" stroke-linejoin="round" d="M12 9v3.75m9-.75a9 9 0 1 1-18 0 9 9 0 0 1 18 0Zm-9 3.75h.008v.008H12v-.008Z"/>
-					</svg>
-					break;
-				default:
-					<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="size-6">
-						<path stroke-linecap="round" stroke-linejoin="round" d="M7.5 8.25h9m-9 3H12m-9.75 1.51c0 1.6 1.123 2.994 2.707 3.227 1.129.166 2.27.293 3.423.379.35.026.67.21.865.501L12 21l2.755-4.133a1.14 1.14 0 0 1 .865-.501 48.172 48.172 0 0 0 3.423-.379c1.584-.233 2.707-1.626 2.707-3.228V6.741c0-1.602-1.123-2.995-2.707-3.228A48.394 48.394 0 0 0 12 3c-2.392 0-4.744.175-7.043.513C3.373 3.746 2.25 5.14 2.25 6.741v6.018Z" />
-					</svg>
-					break;
-			}
+		@if (Model.AppliesTo is not null)
+		{
+			<span class="applies applies-admonition">
+				@await RenderPartialAsync(ApplicableToComponent.Create(new ApplicableToViewModel
+				{
+					AppliesTo = Model.AppliesTo,
+					Inline = true,
+					ShowTooltip = false,
+					VersionsConfig = Model.BuildContext.VersionsConfiguration
+				}))
+			</span>
+			<span class="admonition-title__separator"></span>
 		}
 		<span>@Model.Title</span>
 	</div>
diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlock.cs
@@ -18,6 +18,11 @@ public interface IBlockTitle
 	string Title { get; }
 }
 
+public interface IBlockAppliesTo
+{
+	string? AppliesToDefinition { get; }
+}
+
 public interface IBlockExtension : IBlock
 {
 	BuildContext Build { get; }
diff --git a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs
@@ -383,6 +383,13 @@ protected override void Write(LlmMarkdownRenderer renderer, DirectiveBlock obj)
 				break;
 		}
 
+		switch (obj)
+		{
+			case IBlockAppliesTo appliesBlock when !string.IsNullOrEmpty(appliesBlock.AppliesToDefinition):
+				renderer.Writer.Write($" applies-to=\"{appliesBlock.AppliesToDefinition}\"");
+				break;
+		}
+
 		renderer.WriteLine(">");
 		renderer.EnsureLine();
 
diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs
@@ -236,3 +236,163 @@ public void ParsesAppliesToWithComplexValue()
 		Block!.AppliesTo.Should().NotBeNull();
 	}
 }
+
+public class NoteAppliesToTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+:::{note}
+:applies_to: stack: ga
+This is a note with applies_to information
+:::
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("note");
+
+	[Fact]
+	public void SetsTitle() => Block!.Title.Should().Be("Note");
+
+	[Fact]
+	public void SetsAppliesToDefinition() => Block!.AppliesToDefinition.Should().Be("stack: ga");
+
+	[Fact]
+	public void ParsesAppliesTo() => Block!.AppliesTo.Should().NotBeNull();
+
+	[Fact]
+	public void RendersAppliesToInHtml()
+	{
+		var html = Html;
+		html.Should().Contain("applies applies-admonition");
+		html.Should().Contain("admonition-title__separator");
+		html.Should().Contain("applicable-info");
+	}
+}
+
+public class WarningAppliesToTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+:::{warning}
+:applies_to: stack: ga
+This is a warning with applies_to information
+:::
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("warning");
+
+	[Fact]
+	public void SetsTitle() => Block!.Title.Should().Be("Warning");
+
+	[Fact]
+	public void SetsAppliesToDefinition() => Block!.AppliesToDefinition.Should().Be("stack: ga");
+
+	[Fact]
+	public void ParsesAppliesTo() => Block!.AppliesTo.Should().NotBeNull();
+
+	[Fact]
+	public void RendersAppliesToInHtml()
+	{
+		var html = Html;
+		html.Should().Contain("applies applies-admonition");
+		html.Should().Contain("admonition-title__separator");
+		html.Should().Contain("applicable-info");
+	}
+}
+
+public class TipAppliesToTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+:::{tip}
+:applies_to: stack: ga
+This is a tip with applies_to information
+:::
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("tip");
+
+	[Fact]
+	public void SetsTitle() => Block!.Title.Should().Be("Tip");
+
+	[Fact]
+	public void SetsAppliesToDefinition() => Block!.AppliesToDefinition.Should().Be("stack: ga");
+
+	[Fact]
+	public void ParsesAppliesTo() => Block!.AppliesTo.Should().NotBeNull();
+
+	[Fact]
+	public void RendersAppliesToInHtml()
+	{
+		var html = Html;
+		html.Should().Contain("applies applies-admonition");
+		html.Should().Contain("admonition-title__separator");
+		html.Should().Contain("applicable-info");
+	}
+}
+
+public class ImportantAppliesToTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+:::{important}
+:applies_to: stack: ga
+This is an important notice with applies_to information
+:::
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("important");
+
+	[Fact]
+	public void SetsTitle() => Block!.Title.Should().Be("Important");
+
+	[Fact]
+	public void SetsAppliesToDefinition() => Block!.AppliesToDefinition.Should().Be("stack: ga");
+
+	[Fact]
+	public void ParsesAppliesTo() => Block!.AppliesTo.Should().NotBeNull();
+
+	[Fact]
+	public void RendersAppliesToInHtml()
+	{
+		var html = Html;
+		html.Should().Contain("applies applies-admonition");
+		html.Should().Contain("admonition-title__separator");
+		html.Should().Contain("applicable-info");
+	}
+}
+
+public class AdmonitionAppliesToTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+:::{admonition} Custom Admonition
+:applies_to: stack: ga
+This is a custom admonition with applies_to information
+:::
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("admonition");
+
+	[Fact]
+	public void SetsCustomTitle() => Block!.Title.Should().Be("Custom Admonition");
+
+	[Fact]
+	public void SetsAppliesToDefinition() => Block!.AppliesToDefinition.Should().Be("stack: ga");
+
+	[Fact]
+	public void ParsesAppliesTo() => Block!.AppliesTo.Should().NotBeNull();
+
+	[Fact]
+	public void RendersAppliesToInHtml()
+	{
+		var html = Html;
+		html.Should().Contain("applies applies-admonition");
+		html.Should().Contain("admonition-title__separator");
+		html.Should().Contain("applicable-info");
+	}
+}
diff --git a/tests/authoring/Blocks/Admonitions.fs b/tests/authoring/Blocks/Admonitions.fs
diff --git a/tests/authoring/Container/DefinitionLists.fs b/tests/authoring/Container/DefinitionLists.fs
diff --git a/tests/authoring/LlmMarkdown/LlmMarkdownOutput.fs b/tests/authoring/LlmMarkdown/LlmMarkdownOutput.fs

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ namespace Elastic.Markdown.Myst.Directives.Admonition;`
`9`	`9`
`10`	`10`	`public class DropdownBlock(DirectiveBlockParser parser, ParserContext context) : AdmonitionBlock(parser, "dropdown", context);`
`11`	`11`
`12`		`-public class AdmonitionBlock : DirectiveBlock, IBlockTitle`
	`12`	`+public class AdmonitionBlock : DirectiveBlock, IBlockTitle, IBlockAppliesTo`
`13`	`13`	`{`
`14`	`14`	`public AdmonitionBlock(DirectiveBlockParser parser, string admonition, ParserContext context) : base(parser, context)`
`15`	`15`	`{`
`@@ -65,6 +65,7 @@ public override void FinalizeAndValidate(ParserContext context)`
`65`	`65`	`catch`
`66`	`66`	`{`
`67`	`67`	`// If parsing fails, return null`
	`68`	`+ // Note: Error handling is done in the YamlSerialization.Deserialize method`
`68`	`69`	`return null;`
`69`	`70`	`}`
`70`	`71`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,11 @@ public interface IBlockTitle`
`18`	`18`	`string Title { get; }`
`19`	`19`	`}`
`20`	`20`
	`21`	`+public interface IBlockAppliesTo`
	`22`	`+{`
	`23`	`+ string? AppliesToDefinition { get; }`
	`24`	`+}`
	`25`	`+`
`21`	`26`	`public interface IBlockExtension : IBlock`
`22`	`27`	`{`
`23`	`28`	`BuildContext Build { get; }`