From 31667169455761182dbe41b7a9eac458f9986311 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Mon, 20 Jan 2025 19:28:14 +0100 Subject: [PATCH] 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 --- docs/source/syntax/admonitions.md | 21 +++++++++++++++ .../Myst/Directives/AdmonitionBlock.cs | 18 +++++++++---- .../Myst/Directives/DirectiveBlockParser.cs | 3 +-- src/Elastic.Markdown/_static/custom.css | 9 +++++++ .../Directives/AdmonitionTests.cs | 27 +++++++++++++++---- .../Directives/AdmonitionUnsupportedTests.cs | 1 - 6 files changed, 66 insertions(+), 13 deletions(-) diff --git a/docs/source/syntax/admonitions.md b/docs/source/syntax/admonitions.md index 763a27f9..1a001a95 100644 --- 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 index 16f55ec7..1ef15172 100644 --- 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 index c73db19e..45358b18 100644 --- 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 index d3326540..f0b4e397 100644 --- 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); } \ No newline at end of file diff --git a/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs b/tests/Elastic.Markdown.Tests/Directives/AdmonitionTests.cs index 456dda63..a0bc4bd8 100644 --- 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(output, +public abstract class AdmonitionBaseTests(ITestOutputHelper output, string directive) : DirectiveTest(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(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(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 index 675646d5..77fe64e6 100644 --- 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