Add support for plain admonitions (#275)

* Add support for plain admonitions Updated the `AdmonitionBlock` to differentiate plain admonitions with minimal styling and adjusted related tests and documentation. Simplifies styling options while expanding customization for callouts. * fix failing test --------- Co-authored-by: Jan Calanog <[email protected]>
elastic · Jan 20, 2025 · 3166716 · 3166716
1 parent bfa8b3b
commit 3166716
Show file tree

Hide file tree

Showing 6 changed files with 66 additions and 13 deletions.
diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md
@@ -11,6 +11,27 @@ Available admonition types include:
 - Warning
 - Tip
 - Important
+- Plain
+
+### Plain
+
+A plain admonition is a callout with no further styling. Useful to create a callout that does not quite fit the mold of the stylized admonitions
+
+```markdown
+:::{admonition} This is my callout
+
+It can *span* multiple lines and supports inline formatting.
+
+:::
+```
+
+:::{admonition} This is my callout
+
+It can *span* multiple lines and supports inline formatting.
+
+:::
+
+
 
 ### Note
 

diff --git a/src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs b/src/Elastic.Markdown/Myst/Directives/AdmonitionBlock.cs
@@ -3,12 +3,20 @@
 // See the LICENSE file in the project root for more information
 namespace Elastic.Markdown.Myst.Directives;
 
-public class DropdownBlock(DirectiveBlockParser parser, ParserContext context) : AdmonitionBlock(parser, "admonition", context);
+public class DropdownBlock(DirectiveBlockParser parser, ParserContext context) : AdmonitionBlock(parser, "dropdown", context);
 
-public class AdmonitionBlock(DirectiveBlockParser parser, string admonition, ParserContext context)
-	: DirectiveBlock(parser, context)
+public class AdmonitionBlock : DirectiveBlock
 {
-	public string Admonition => admonition == "admonition" ? Classes?.Trim() ?? "note" : admonition;
+	private readonly string _admonition;
+
+	public AdmonitionBlock(DirectiveBlockParser parser, string admonition, ParserContext context) : base(parser, context)
+	{
+		_admonition = admonition;
+		if (_admonition is "admonition")
+			Classes = "plain";
+	}
+
+	public string Admonition => _admonition;
 
 	public override string Directive => Admonition;
 
@@ -21,7 +29,7 @@ public string Title
 		{
 			var t = Admonition;
 			var title = Thread.CurrentThread.CurrentCulture.TextInfo.ToTitleCase(t);
-			if (admonition is "admonition" && !string.IsNullOrEmpty(Arguments))
+			if (_admonition is "admonition" or "dropdown" && !string.IsNullOrEmpty(Arguments))
 				title = Arguments;
 			else if (!string.IsNullOrEmpty(Arguments))
 				title += $" {Arguments}";

diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs
@@ -28,7 +28,7 @@ public DirectiveBlockParser()
 		InfoPrefix = null;
 	}
 
-	private readonly string[] _admonitions = ["important", "warning", "note", "tip"];
+	private readonly string[] _admonitions = ["important", "warning", "note", "tip", "admonition"];
 
 	private readonly string[] _versionBlocks = ["versionadded", "versionchanged", "versionremoved", "deprecated"];
 
@@ -54,7 +54,6 @@ public DirectiveBlockParser()
 		{ "margin", 4 },
 		{ "sidebar", 4 },
 		{ "code-cell", 8 },
-		{ "admonition", 3 },
 		{ "attention", 3 },
 		{ "caution", 3 },
 		{ "danger", 3 },

diff --git a/src/Elastic.Markdown/_static/custom.css b/src/Elastic.Markdown/_static/custom.css
@@ -125,4 +125,13 @@ See https://github.com/elastic/docs-builder/issues/219 for further details
 	padding-right: 0 !important;
 	border-bottom-right-radius: 0 !important;
 	border-top-right-radius: 0 !important;
+}
+
+
+.admonition.plain {
+	--icon-url: var(--lucide-chevron-right-url);
+	--color-4: var(--gray-12);
+	--color-1: var(--gray-2);
+	--color-2: var(--gray-a4);
+	--color-3: var(--gray-10);
 }
diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs
@@ -7,7 +7,7 @@
 
 namespace Elastic.Markdown.Tests.Directives;
 
-public abstract class AdmonitionTests(ITestOutputHelper output, string directive) : DirectiveTest<AdmonitionBlock>(output,
+public abstract class AdmonitionBaseTests(ITestOutputHelper output, string directive) : DirectiveTest<AdmonitionBlock>(output,
 $$"""
 :::{{{directive}}}
 This is an attention block
@@ -23,25 +23,25 @@ A regular paragraph.
 	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be(directive);
 }
 
-public class WarningTests(ITestOutputHelper output) : AdmonitionTests(output, "warning")
+public class WarningTests(ITestOutputHelper output) : AdmonitionBaseTests(output, "warning")
 {
 	[Fact]
 	public void SetsTitle() => Block!.Title.Should().Be("Warning");
 }
 
-public class NoteTests(ITestOutputHelper output) : AdmonitionTests(output, "note")
+public class NoteTests(ITestOutputHelper output) : AdmonitionBaseTests(output, "note")
 {
 	[Fact]
 	public void SetsTitle() => Block!.Title.Should().Be("Note");
 }
 
-public class TipTests(ITestOutputHelper output) : AdmonitionTests(output, "tip")
+public class TipTests(ITestOutputHelper output) : AdmonitionBaseTests(output, "tip")
 {
 	[Fact]
 	public void SetsTitle() => Block!.Title.Should().Be("Tip");
 }
 
-public class ImportantTests(ITestOutputHelper output) : AdmonitionTests(output, "important")
+public class ImportantTests(ITestOutputHelper output) : AdmonitionBaseTests(output, "important")
 {
 	[Fact]
 	public void SetsTitle() => Block!.Title.Should().Be("Important");
@@ -63,6 +63,23 @@ A regular paragraph.
 	public void SetsCustomTitle() => Block!.Title.Should().Be("Note This is my custom note");
 }
 
+
+public class AdmonitionTitleTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
+"""
+```{admonition} This is my custom title
+This is an attention block
+```
+A regular paragraph.
+"""
+)
+{
+	[Fact]
+	public void SetsCorrectAdmonitionType() => Block!.Admonition.Should().Be("admonition");
+
+	[Fact]
+	public void SetsCustomTitle() => Block!.Title.Should().Be("This is my custom title");
+}
+
 public class DropdownTitleTests(ITestOutputHelper output) : DirectiveTest<AdmonitionBlock>(output,
 """
 :::{dropdown} This is my custom dropdown

diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionUnsupportedTests.cs
@@ -32,5 +32,4 @@ public class HintTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(ou
 public class AttentionTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "attention");
 public class CautionTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "caution");
 public class SeeAlsoTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "seealso");
-public class AdmonitionTitleTests(ITestOutputHelper output) : AdmonitionUnsupportedTests(output, "admonition");
 // ReSharper restore UnusedType.Global