Add directive block parsing for applies_to

Author: Mpdreamz

docs/syntax/applies.md

@@ -15,38 +15,42 @@ applies_to:
 
 # Applies to
 
+Allows you to annotate a page or section's applicability.
 
-Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status
-
+### Syntax
 
-```yaml
-applies_to:
-  stack: ga 9.1
-  deployment:
-    eck: ga 9.0
-    ess: beta 9.1
-    ece: discontinued 9.2.0
-    self: unavailable 9.3.0
-  serverless:
-    security: ga 9.0.0
-    elasticsearch: beta 9.1.0
-    observability: discontinued 9.2.0
-  product: coming 9.5, discontinued 9.7
+```
+<life-cycle> [version], <life-cycle> [version]
 ```
 
-Its syntax is
+Taking a mandatory [life-cycle](#life-cycle) with an optional version.
+
+#### Life cycle:
+  * `preview`
+  * `beta`
+  * `development`
+  * `deprecated`
+  * `coming`
+  * `discontinued`
+  * `unavailable`
+  * `ga`
+
+#### Version
+
+Can be in either `major.minor` or `major.minor.patch` format
+
+#### Examples
 
 ```
- <product>: <lifecycle> [version]
+coming 9.5, discontinued 9.7
+discontinued 9.2.0
+all
 ```
 
-Where version is optional.
-
 `all` and empty string mean generally available for all active versions
 
 ```yaml
 applies:
-  stack:
   serverless: all
 ```
 
@@ -58,19 +62,94 @@ applies:
   serverless: beta
 ```
 
-Are equivalent, note `all` just means we won't be rendering the version portion in the html.
+Both are equivalent, note `all` just means we won't be rendering the version portion in the html.
 
 
-## This section has its own applies annotations [#sections]
+## Structured model
 
-:::{applies}
-:serverless: unavailable
-:::
+![Applies To Model](img/applies.png)
+
+The above model is projected to the following structured yaml.
+
+```yaml
+---
+applies_to:
+  stack: 
+  deployment:
+    eck: 
+    ess: 
+    ece: 
+    self: 
+  serverless:
+    security: 
+    elasticsearch: 
+    observability: 
+  product: 
+---
+```
+This allows you to annotate various facets as defined in [](../migration/versioning.md)
+
+## Page annotations
+
+Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status
+
+
+```yaml
+---
+applies_to:
+  stack: ga 9.1
+  deployment:
+    eck: ga 9.0
+    ess: beta 9.1
+    ece: discontinued 9.2.0
+    self: unavailable 9.3.0
+  serverless:
+    security: ga 9.0.0
+    elasticsearch: beta 9.1.0
+    observability: discontinued 9.2.0
+  product: coming 9.5, discontinued 9.7
+---
+```
+
+
+## Section annotation [#sections]
+
+```yaml {applies_to}
+stack: ga 9.1
+deployment:
+  eck: ga 9.0
+  ess: beta 9.1
+  ece: discontinued 9.2.0
+  self: unavailable 9.3.0
+serverless:
+  security: ga 9.0.0
+  elasticsearch: beta 9.1.0
+  observability: discontinued 9.2.0
+product: coming 9.5, discontinued 9.7
+```
+
+A header may be followed by an `{applies_to}` directive which will contextualize the applicability 
+of the section further.
 
 :::{note}
-the `{applies}` directive **MUST** be preceded by a heading.
+the `{applies_to}` directive **MUST** be preceded by a heading directly.
 :::
 
 
-This section describes a feature that's unavailable in `stack` and `ga` in all cloud products
-however its tech preview on `serverless` since it overrides what `cloud` specified.
+Note that this directive needs triple backticks since its content is literal. See also [](index.md#literal-directives)
+
+````markdown
+```{applies_to}
+stack: ga 9.1
+```
+````
+
+In order to play even better with markdown editors the following is also supported:
+
+````markdown
+```yaml {applies_to}
+stack: ga 9.1
+```
+````
+
+This will allow the yaml inside the `{applies-to}` directive to be fully highlighted.

docs/syntax/img/applies.png

@@ -29,6 +29,8 @@ Nested content that will be parsed as markdown
 
 Defining directives with `:::` allows the nested markdown syntax to be highlighted properly by editors and web viewers.
 
+
+
 ### Nesting Directives
 
 Increase the number of leading semicolons to include nested directives.
@@ -46,6 +48,13 @@ Content displayed in the note admonition
 
 ## Literal directives
 
+All directive are indicated with semicolons except literal blocks. For these you need to use triple backticks.
+
+* [Code blocks](code.md)
+* [{applies-to} blocks](applies.md)
+
+Since their contents **should not** be parsed as markdown they use backticks. This also ensures maximum interopability with existing markdown editors and previews.
+
 Many Markdown editors support syntax highlighting for embedded code blocks. For compatibility with this feature, use triple backticks instead of triple colons for content that needs to be displayed literally:
 
 ````markdown

docs/syntax/index.md

@@ -4,11 +4,18 @@
 
 using System.IO.Abstractions;
 using Elastic.Markdown.Myst.Directives;
+using Elastic.Markdown.Myst.FrontMatter;
 using Markdig.Parsers;
 using Markdig.Syntax;
 
 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/EnhancedCodeBlock.cs

@@ -108,6 +108,12 @@ private static int CountIndentation(StringSlice slice)
 
 	protected override void Write(HtmlRenderer renderer, EnhancedCodeBlock block)
 	{
+		if (block is AppliesToDirective appliesToDirective)
+		{
+			RenderAppliesToHtml(renderer, appliesToDirective);
+			return;
+		}
+
 		var callOuts = block.UniqueCallOuts;
 
 		var slice = Code.Create(new CodeViewModel
@@ -184,4 +190,14 @@ protected override void Write(HtmlRenderer renderer, EnhancedCodeBlock block)
 			renderer.WriteLine("</ol>");
 		}
 	}
+
+	private static void RenderAppliesToHtml(HtmlRenderer renderer, AppliesToDirective appliesToDirective)
+	{
+		var appliesTo = appliesToDirective.AppliesTo;
+		var slice2 = ApplicableTo.Create(appliesTo);
+		if (appliesTo is null || appliesTo == FrontMatter.ApplicableTo.All)
+			return;
+		var html = slice2.RenderAsync().GetAwaiter().GetResult();
+		renderer.Write(html);
+	}
 }

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

@@ -5,6 +5,7 @@
 using System.Text.RegularExpressions;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Helpers;
+using Elastic.Markdown.Myst.FrontMatter;
 using Markdig.Helpers;
 using Markdig.Parsers;
 using Markdig.Syntax;
@@ -30,7 +31,10 @@ protected override EnhancedCodeBlock CreateFencedBlock(BlockProcessor processor)
 		if (processor.Context is not ParserContext context)
 			throw new Exception("Expected parser context to be of type ParserContext");
 
-		var codeBlock = new EnhancedCodeBlock(this, context) { IndentCount = processor.Indent };
+        var lineSpan = processor.Line.AsSpan();
+		var codeBlock = lineSpan.IndexOf("{applies_to}") > -1
+			? new AppliesToDirective(this, context) { IndentCount = processor.Indent }
+			: new EnhancedCodeBlock(this, context) { IndentCount = processor.Indent };
 
 		if (processor.TrackTrivia)
 		{
@@ -91,8 +95,30 @@ public override bool Close(BlockProcessor processor, Block block)
 			codeBlock.EmitWarning($"Unknown language: {codeBlock.Language}");
 
 		var lines = codeBlock.Lines;
-		var callOutIndex = 0;
+		// ReSharper disable once ConditionIsAlwaysTrueOrFalseAccordingToNullableAPIContract
+		if (lines.Lines is null)
+			return base.Close(processor, block);
+
+		if (codeBlock is not AppliesToDirective appliesToDirective)
+			ProcessCallOuts(lines, language, codeBlock, context);
+		else
+			ProcessAppliesToDirective(appliesToDirective, lines, context);
+
+		return base.Close(processor, block);
+	}
+
+	private static void ProcessAppliesToDirective(AppliesToDirective appliesToDirective, StringLineGroup lines, ParserContext context)
+	{
+		var yaml = lines.ToSlice().AsSpan().ToString();
 
+		var applicableTo = YamlSerialization.Deserialize<ApplicableTo>(yaml);
+		appliesToDirective.AppliesTo = applicableTo;
+	}
+
+	private static void ProcessCallOuts(StringLineGroup lines, string language, EnhancedCodeBlock codeBlock,
+		ParserContext context)
+	{
+		var callOutIndex = 0;
 		var originatingLine = 0;
 		for (var index = 0; index < lines.Lines.Length; index++)
 		{
@@ -141,7 +167,6 @@ public override bool Close(BlockProcessor processor, Block block)
 		//update string slices to ignore call outs
 		if (codeBlock.CallOuts.Count > 0)
 		{
-
 			var callouts = codeBlock.CallOuts.Aggregate(new Dictionary<int, CallOut>(), (acc, curr) =>
 			{
 				if (acc.TryAdd(curr.Line, curr))
@@ -168,8 +193,6 @@ public override bool Close(BlockProcessor processor, Block block)
 
 		if (inlineAnnotations > 0)
 			codeBlock.InlineAnnotations = true;
-
-		return base.Close(processor, block);
 	}
 
 	private static List<CallOut> EnumerateAnnotations(Regex.ValueMatchEnumerator matches,

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

@@ -153,12 +153,19 @@ public override BlockState TryOpen(BlockProcessor processor)
 				return BlockState.None;
 		}
 
-		if (line.IndexOf("{") == -1)
+		if (line.IndexOf("{") <= -1)
 			return BlockState.None;
 
 		if (line.IndexOf("}") == -1)
 			return BlockState.None;
 
+		var span = line.AsSpan();
+		var lastIndent = span.LastIndexOf(":");
+		var startApplies = span.IndexOf("{applies_to}");
+		var startOpen = span.IndexOf("{");
+		if (startOpen > lastIndent + 1 || startApplies != -1)
+			return BlockState.None;
+
 		return base.TryOpen(processor);
 	}
 

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

@@ -0,0 +1,58 @@
+// 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
+
+module ``product availability``.``yaml directive``
+
+open Elastic.Markdown.Myst.FrontMatter
+open authoring
+open authoring.MarkdownDocumentAssertions
+open Swensen.Unquote
+open Xunit
+open Elastic.Markdown.Myst.CodeBlocks
+
+type ``piggy back off yaml formatting`` () =
+    static let markdown = Setup.Markdown """
+```yaml {applies_to}
+serverless:
+  security: ga 9.0.0
+  elasticsearch: beta 9.1.0
+  observability: discontinued 9.2.0
+```
+"""
+
+    [<Fact>]
+    let ``parses to AppliesDirective`` () =
+        let directives = markdown |> converts "index.md" |> parses<AppliesToDirective>
+        test <@ directives.Length = 1 @>
+
+        directives |> appliesToDirective (ApplicableTo(
+            Serverless=ServerlessProjectApplicability(
+                Security=ApplicabilityOverTime.op_Explicit "ga 9.0.0",
+                Elasticsearch=ApplicabilityOverTime.op_Explicit "beta 9.1.0",
+                Observability=ApplicabilityOverTime.op_Explicit "discontinued 9.2.0"
+            )
+        ))
+
+type ``plain block`` () =
+    static let markdown = Setup.Markdown """
+```{applies_to}
+serverless:
+  security: ga 9.0.0
+  elasticsearch: beta 9.1.0
+  observability: discontinued 9.2.0
+```
+"""
+
+    [<Fact>]
+    let ``parses to AppliesDirective`` () =
+        let directives = markdown |> converts "index.md" |> parses<AppliesToDirective>
+        test <@ directives.Length = 1 @>
+
+        directives |> appliesToDirective (ApplicableTo(
+            Serverless=ServerlessProjectApplicability(
+                Security=ApplicabilityOverTime.op_Explicit "ga 9.0.0",
+                Elasticsearch=ApplicabilityOverTime.op_Explicit "beta 9.1.0",
+                Observability=ApplicabilityOverTime.op_Explicit "discontinued 9.2.0"
+            )
+        ))

tests/authoring/Applicability/AppliesToDirective.fs

@@ -4,8 +4,6 @@
 
 module ``product availability``.``yaml frontmatter``
 
-open System.Collections
-open Elastic.Markdown.Helpers
 open Elastic.Markdown.Myst.FrontMatter
 open JetBrains.Annotations
 open Xunit