Rework applies blocks to applies_to with new semantics (#527)

* Rework applies blocks to applies_to with new semantics

* Add directive block parsing for applies_to

* update styling

* cleanup and fix tests

* formatting and BOM files cleanup

* fix visibility on constructor

* update {applies} to {applies_to}

Author: Mpdreamz

docs-builder.sln

@@ -1,4 +1,4 @@
-
+
 Microsoft Visual Studio Solution File, Format Version 12.00
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Elastic.Markdown", "src\Elastic.Markdown\Elastic.Markdown.csproj", "{4D198E25-C211-41DC-9E84-B15E89BD7048}"
 EndProject

docs/syntax/applies.md

@@ -1,40 +1,56 @@
 ---
-applies:
-  stack: ga 8.1
-  serverless: tech-preview
-  hosted: beta 8.1.1
-  eck: beta 3.0.2
-  ece: unavailable
+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
 ---
 
 # 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:
-  stack: ga 8.1
-  serverless: tech-preview
-  hosted: beta 8.1.1
-  eck: beta 3.0.2
-  ece: unavailable
 ```
+<life-cycle> [version], <life-cycle> [version]
+```
+
+Taking a mandatory [life-cycle](#life-cycle) with an optional version.
 
-Its syntax is
+#### 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
 ```
 
@@ -46,19 +62,134 @@ 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.
+
+
+## Examples
+
+#### Stack only
+```yaml {applies_to}
+stack: ga 9.1
+```
+
+#### Stack with deployment
+```yaml {applies_to}
+stack: ga 9.1
+deployment:
+  eck: ga 9.0
+  ess: beta 9.1
+```
+
+#### Deployment only
+```yaml {applies_to}
+deployment:
+  ece: discontinued 9.2.0
+  self: unavailable 9.3.0
+```
+
+#### Serverless only
+```yaml {applies_to}
+serverless: ga 9.0.0
+```
+
+#### Serverless with project differences
+```yaml {applies_to}
+serverless:
+  security: ga 9.0.0
+  elasticsearch: beta 9.1.0
+  observability: discontinued 9.2.0
+```
+#### Stack with product
+```yaml {applies_to}
+stack: ga 9.1
+```

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

@@ -31,12 +31,13 @@ See [Versions and lifecycle states](/versions/index.md#versions-and-lifecycle-st
 
 ## Section/heading-level `applies` tags
 
-:::{applies}
-:ece: all
-:hosted: all
-:eck: all
-:stack: all
-:::
+```yaml {applies_to}
+stack: ga 9.1
+deployment:
+  eck: ga 9.0
+  ece: discontinued 9.2.0
+  self: unavailable 9.3.0
+```
 
 *see [`applies`](/syntax/applies.md#sections)*
 

docs/versions/content-patterns.md

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <TargetFramework>net9.0</TargetFramework>

src/Elastic.Markdown.Refactor/Elastic.Markdown.Refactor.csproj

@@ -87,6 +87,30 @@
 	.content-container {
 		@apply w-full max-w-[80ch];
 	}
+
+	.applies {
+		border-bottom: 1px solid var(--color-gray-300);
+		padding-bottom: calc(var(--spacing) * 3);
+		font-family: "Mier B", "Inter", sans-serif;
+
+		.applies-to-label {
+			display: block;
+			font-size: 1.5em;
+			font-weight: var(--font-weight-extrabold);
+			padding-bottom: calc(var(--spacing) * 3);
+		}
+		.applicable-info {
+			padding: calc(var(--spacing) * 0.5);
+			padding-left: calc(var(--spacing) * 2);
+			padding-right: calc(var(--spacing) * 2);
+			margin: 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-gray-300);
+		}
+	}
 }
 
 * {

src/Elastic.Markdown/Assets/styles.css

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk.Razor">
+<Project Sdk="Microsoft.NET.Sdk.Razor">
 
   <PropertyGroup>
     <TargetFramework>net9.0</TargetFramework>

src/Elastic.Markdown/Elastic.Markdown.csproj

@@ -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);
+	}
 }