Add support for Myst inline role syntax with applies_to as first usecase (#875)

This PR adds support for Myst inline role syntax.

The first `role` we support is `{applies_to}` and `{preview}``

Author: Mpdreamz

docs/syntax/applies.md

@@ -154,6 +154,34 @@ stack: ga 9.1
 
 This will allow the yaml inside the `{applies-to}` directive to be fully highlighted.
 
+## Inline Applies To 
+
+Inline applies to can be placed anywhere using the following syntax
+
+```markdown
+This can live inline {applies_to}`section: <life-cycle> [version]`
+```
+
+An inline version example would be {applies_to}`stack: beta 9.1` this allows you to target elements more concretely visually.
+
+A common use case would be to place them on definition lists:
+
+Fruit {applies_to}`stack: preview 9.1`
+:   A sweet and fleshy product of a tree or other plant that contains seed and can be eaten as food. Common examples include apples, oranges, and bananas. Most fruits are rich in vitamins, minerals and fiber.
+
+Applies {preview}`9.1`
+:   A sweet and fleshy product of a tree or other plant that contains seed and can be eaten as food. Common examples include apples, oranges, and bananas. Most fruits are rich in vitamins, minerals and fiber.
+
+
+A specialized `{preview}` role exist to quickly mark something as a technical preview. It takes a required version number
+as argument.
+
+```markdown
+Property {preview}`<version>`
+:   definition body
+```
+
+
 
 ## Examples
 
@@ -162,6 +190,7 @@ This will allow the yaml inside the `{applies-to}` directive to be fully highlig
 stack: ga 9.1
 ```
 
+
 #### Stack with deployment
 ```yaml {applies_to}
 stack: ga 9.1

src/Elastic.Markdown/Assets/styles.css

@@ -103,13 +103,19 @@
 		@apply font-sans;
 		border-bottom: 1px solid var(--color-grey-20);
 		padding-bottom: calc(var(--spacing) * 3);
+		font-variant: all-petite-caps;
 
-		.applies-to-label {
-			display: block;
-			font-size: 1.5em;
-			font-weight: var(--font-weight-extrabold);
-			padding-bottom: calc(var(--spacing) * 3);
+		.applicable-meta-discontinued {
+			color: var(--color-red-90);
 		}
+		.applicable-meta-coming {
+			color: var(--color-blue-elastic-80);
+		}
+		.applicable-meta-technical-preview {
+			color: var(--color-yellow-80);
+		}
+
+
 		.applicable-info {
 			padding: calc(var(--spacing) * 0.5);
 			padding-left: calc(var(--spacing) * 2);
@@ -121,6 +127,52 @@
 			background-color: var(--color-white);
 			border: 1px solid var(--color-grey-20);
 		}
+		.applicable-version {
+			font-weight: bold;
+			margin-left: calc(var(--spacing) * 0.5);
+			font-variant: none;
+			font-size: 0.87em;
+		}
+		.applicable-lifecycle {
+			font-weight: bold;
+		}
+	}
+	.applies-inline {
+		@apply font-sans;
+		font-variant: all-petite-caps;
+
+		.applicable-meta-discontinued {
+			color: var(--color-red-90);
+		}
+		.applicable-meta-coming {
+			color: var(--color-blue-elastic-80);
+		}
+		.applicable-meta-technical-preview {
+			color: var(--color-blue-elastic-80);
+		}
+
+		.applicable-info {
+			padding: calc(var(--spacing) * 0.5);
+			padding-left: calc(var(--spacing) * 2);
+			padding-right: calc(var(--spacing) * 2);
+			margin-left: calc(var(--spacing) * 0.5);
+			margin-right: calc(var(--spacing) * 0.5);
+			display: inline-block;
+			font-size: 0.8em;
+			border-radius: 0.4em;
+			background-color: var(--color-white);
+			border: 1px solid var(--color-grey-20);
+			font-weight: normal;
+		}
+		.applicable-version {
+			font-weight: bold;
+			margin-left: calc(var(--spacing) * 0.5);
+			font-variant: none;
+			font-size: 0.87em;
+		}
+		.applicable-lifecycle {
+			font-weight: bold;
+		}
 	}
 }
 

src/Elastic.Markdown/Diagnostics/ProcessorDiagnosticExtensions.cs

@@ -12,6 +12,8 @@ namespace Elastic.Markdown.Diagnostics;
 
 public static class ProcessorDiagnosticExtensions
 {
+	private static string CreateExceptionMessage(string message, Exception? e) => message + (e != null ? Environment.NewLine + e : string.Empty);
+
 	public static void EmitError(this InlineProcessor processor, int line, int column, int length, string message)
 	{
 		var context = processor.GetContext();
@@ -55,7 +57,7 @@ public static void EmitError(this ParserContext context, string message, Excepti
 		{
 			Severity = Severity.Error,
 			File = context.MarkdownSourcePath.FullName,
-			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
+			Message = CreateExceptionMessage(message, e),
 		};
 		context.Build.Collector.Channel.Write(d);
 	}
@@ -82,7 +84,7 @@ public static void EmitError(this BuildContext context, IFileInfo file, string m
 		{
 			Severity = Severity.Error,
 			File = file.FullName,
-			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
+			Message = CreateExceptionMessage(message, e),
 		};
 		context.Collector.Channel.Write(d);
 	}
@@ -104,7 +106,7 @@ public static void EmitError(this DiagnosticsCollector collector, IFileInfo file
 		{
 			Severity = Severity.Error,
 			File = file.FullName,
-			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
+			Message = CreateExceptionMessage(message, e),
 		};
 		collector.Channel.Write(d);
 	}
@@ -132,11 +134,12 @@ public static void EmitError(this IBlockExtension block, string message, Excepti
 			Line = block.Line + 1,
 			Column = block.Column,
 			Length = block.OpeningLength + 5,
-			Message = message + (e != null ? Environment.NewLine + e : string.Empty),
+			Message = CreateExceptionMessage(message, e),
 		};
 		block.Build.Collector.Channel.Write(d);
 	}
 
+
 	public static void EmitWarning(this IBlockExtension block, string message)
 	{
 		if (block.SkipValidation)
@@ -154,12 +157,10 @@ public static void EmitWarning(this IBlockExtension block, string message)
 		block.Build.Collector.Channel.Write(d);
 	}
 
-	private static void LinkDiagnostic(InlineProcessor processor, Severity severity, LinkInline inline, string message)
+	private static void LinkDiagnostic(InlineProcessor processor, Severity severity, Inline inline, int length, string message, Exception? e = null)
 	{
-		var url = inline.Url;
 		var line = inline.Line + 1;
 		var column = inline.Column;
-		var length = url?.Length ?? 1;
 
 		var context = processor.GetContext();
 		if (context.SkipValidation)
@@ -170,18 +171,27 @@ private static void LinkDiagnostic(InlineProcessor processor, Severity severity,
 			File = processor.GetContext().MarkdownSourcePath.FullName,
 			Column = Math.Max(column, 1),
 			Line = line,
-			Message = message,
-			Length = length
+			Message = CreateExceptionMessage(message, e),
+			Length = Math.Max(length, 1)
 		};
 		context.Build.Collector.Channel.Write(d);
 	}
 
 	public static void EmitError(this InlineProcessor processor, LinkInline inline, string message) =>
-		LinkDiagnostic(processor, Severity.Error, inline, message);
+		LinkDiagnostic(processor, Severity.Error, inline, inline.Url?.Length ?? 1, message);
 
 	public static void EmitWarning(this InlineProcessor processor, LinkInline inline, string message) =>
-		LinkDiagnostic(processor, Severity.Warning, inline, message);
+		LinkDiagnostic(processor, Severity.Warning, inline, inline.Url?.Length ?? 1, message);
 
 	public static void EmitHint(this InlineProcessor processor, LinkInline inline, string message) =>
-		LinkDiagnostic(processor, Severity.Hint, inline, message);
+		LinkDiagnostic(processor, Severity.Hint, inline, inline.Url?.Length ?? 1, message);
+
+	public static void EmitError(this InlineProcessor processor, Inline inline, int length, string message, Exception? e = null) =>
+		LinkDiagnostic(processor, Severity.Error, inline, length, message, e);
+
+	public static void EmitWarning(this InlineProcessor processor, Inline inline, int length, string message) =>
+		LinkDiagnostic(processor, Severity.Warning, inline, length, message);
+
+	public static void EmitHint(this InlineProcessor processor, Inline inline, int length, string message) =>
+		LinkDiagnostic(processor, Severity.Hint, inline, length, message);
 }

src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlock.cs

@@ -10,12 +10,6 @@
 
 namespace Elastic.Markdown.Myst.CodeBlocks;
 
-public class AppliesToDirective(BlockParser parser, ParserContext context)
-	: EnhancedCodeBlock(parser, context)
-{
-	public ApplicableTo? AppliesTo { get; set; }
-}
-
 public class EnhancedCodeBlock(BlockParser parser, ParserContext context)
 	: FencedCodeBlock(parser), IBlockExtension
 {

src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockHtmlRenderer.cs

@@ -5,6 +5,7 @@
 using System.Diagnostics.CodeAnalysis;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Myst.Comments;
+using Elastic.Markdown.Myst.Directives;
 using Elastic.Markdown.Slices.Directives;
 using Markdig.Helpers;
 using Markdig.Renderers;
@@ -228,10 +229,10 @@ protected override void Write(HtmlRenderer renderer, EnhancedCodeBlock block)
 	private static void RenderAppliesToHtml(HtmlRenderer renderer, AppliesToDirective appliesToDirective)
 	{
 		var appliesTo = appliesToDirective.AppliesTo;
-		var slice2 = ApplicableTo.Create(appliesTo);
+		var slice = ApplicableToDirective.Create(appliesTo);
 		if (appliesTo is null || appliesTo == FrontMatter.ApplicableTo.All)
 			return;
-		var html = slice2.RenderAsync().GetAwaiter().GetResult();
+		var html = slice.RenderAsync().GetAwaiter().GetResult();
 		_ = renderer.Write(html);
 	}
 }

src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockParser.cs

@@ -5,6 +5,7 @@
 using System.Text.RegularExpressions;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Helpers;
+using Elastic.Markdown.Myst.Directives;
 using Elastic.Markdown.Myst.FrontMatter;
 using Markdig.Helpers;
 using Markdig.Parsers;

src/Elastic.Markdown/Myst/Directives/AppliesBlock.cs

@@ -0,0 +1,17 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using Elastic.Markdown.Myst.CodeBlocks;
+using Elastic.Markdown.Myst.FrontMatter;
+using Markdig.Parsers;
+
+namespace Elastic.Markdown.Myst.Directives;
+
+
+public class AppliesToDirective(BlockParser parser, ParserContext context)
+	: EnhancedCodeBlock(parser, context), IApplicableToElement
+{
+	public ApplicableTo? AppliesTo { get; set; }
+}
+

src/Elastic.Markdown/Myst/Directives/AppliesToDirective.cs

@@ -104,9 +104,6 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor)
 		if (info.IndexOf("{literalinclude}") > 0)
 			return new LiteralIncludeBlock(this, context);
 
-		if (info.IndexOf("{applies}") > 0)
-			return new AppliesBlock(this, context);
-
 		if (info.IndexOf("{settings}") > 0)
 			return new SettingsBlock(this, context);
 

src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs

@@ -4,8 +4,8 @@
 
 using System.Diagnostics.CodeAnalysis;
 using Elastic.Markdown.Diagnostics;
+using Elastic.Markdown.Myst.InlineParsers.Substitution;
 using Elastic.Markdown.Myst.Settings;
-using Elastic.Markdown.Myst.Substitution;
 using Elastic.Markdown.Slices.Directives;
 using Markdig;
 using Markdig.Renderers;
@@ -32,8 +32,6 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo
 			case MermaidBlock mermaidBlock:
 				WriteMermaid(renderer, mermaidBlock);
 				return;
-			case AppliesBlock: //deprecated scheduled for removal
-				return;
 			case FigureBlock imageBlock:
 				WriteFigure(renderer, imageBlock);
 				return;