Settings: stop stripping {applies_to} inline role in descriptions (#3158)

The SettingsMarkdownNormalizer was unconditionally rewriting
`{applies_to}` to the literal text "Applies to" and collapsing the
following backtick span to parenthesized text. This swallowed the
valid MyST inline role syntax, so per-version badges inside a
setting `description` rendered as plain text instead of badges.

Drop the rewrite so descriptions pass through to the MyST parser
intact. Add a regression test and extend the example YAML + syntax
reference page to document the usage.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: theletterf

docs/syntax/automated_settings.md

@@ -73,6 +73,7 @@ It demonstrates:
 - `note`, `tip`, `warning`, `important`, and `deprecation_details`.
 - Nested `settings`.
 - `applies_to` inheritance and override behavior.
+- Inline `{applies_to}` badges inside a setting `description` (for example, to label per-version defaults in a bulleted list).
 - Top-level `page_description`.
 
 ### Result

docs/syntax/settings-with-applies-example.yml

@@ -54,6 +54,15 @@ groups:
           xpack.example.mode: strict
           ```
 
+      - setting: xpack.example.defaultModel
+        id: xpack-example-default-model
+        description: |
+          Default model used by the feature. The default varies by version:
+
+          * {applies_to}`stack: ga 9.2` Defaults to `model-v2`.
+          * {applies_to}`stack: ga 9.1` Defaults to `model-v1`.
+        datatype: string
+
   - group: Advanced settings
     id: advanced-settings
     description: |

src/Elastic.Markdown/Myst/Directives/Settings/SettingsMarkdownNormalizer.cs

@@ -17,8 +17,6 @@ public static string Normalize(string markdown, string? product = null)
 		var result = markdown.Replace("\r\n", "\n", StringComparison.Ordinal);
 		if (result.Contains("[source,", StringComparison.Ordinal))
 			result = NormalizeAsciiDocSourceBlocks(result);
-		if (result.Contains('{'))
-			result = NormalizeKibanaMarkupArtifacts(result);
 		if (result.Contains("](/", StringComparison.Ordinal)
 			|| result.Contains("](docs-content://", StringComparison.Ordinal)
 			|| result.Contains("(elasticsearch://", StringComparison.Ordinal)
@@ -28,45 +26,6 @@ public static string Normalize(string markdown, string? product = null)
 		return result;
 	}
 
-	private static string NormalizeKibanaMarkupArtifacts(string markdown)
-	{
-		var s = markdown.Replace("{applies_to}", "Applies to", StringComparison.Ordinal);
-		return NormalizeAppliesToBacktickArtifacts(s);
-	}
-
-	/// <summary>Kibana-exported blurbs sometimes emit `` `key: value` `` pairs that break markdown code spans.</summary>
-	private static string NormalizeAppliesToBacktickArtifacts(string markdown)
-	{
-		const string prefix = "Applies to`";
-		var idx = 0;
-		var output = new StringBuilder(markdown.Length);
-		while (idx < markdown.Length)
-		{
-			var found = markdown.IndexOf(prefix, idx, StringComparison.OrdinalIgnoreCase);
-			if (found < 0)
-			{
-				_ = output.Append(markdown.AsSpan(idx));
-				break;
-			}
-
-			_ = output.Append(markdown.AsSpan(idx, found - idx));
-			var valueStart = found + prefix.Length;
-			var close = markdown.IndexOf('`', valueStart);
-			if (close < 0)
-			{
-				_ = output.Append(markdown.AsSpan(found));
-				break;
-			}
-
-			_ = output.Append("Applies to (");
-			_ = output.Append(markdown.AsSpan(valueStart, close - valueStart));
-			_ = output.Append(')');
-			idx = close + 1;
-		}
-
-		return output.ToString();
-	}
-
 	/// <summary>
 	/// Kibana-generated YAML often uses repo-root paths and cross-repo schemes. For docsets that only ship settings fixtures
 	/// (for example docs-builder), rewrite to resolvable targets.

tests/Elastic.Markdown.Tests/SettingsInclusion/IncludeTests.cs

@@ -251,3 +251,35 @@ public void DoesNotRenderGenericStackBadgeOrUnavailableSupportedOnEntry()
 		Html.Should().NotContain("Unavailable");
 	}
 }
+
+public class AppliesToInlineRoleInDescriptionRendersAsBadge(ITestOutputHelper output) : DirectiveTest<SettingsBlock>(output,
+"""
+:::{settings} _settings/applies-to-in-description.yml
+::::
+"""
+)
+{
+	protected override void AddToFileSystem(MockFileSystem fileSystem)
+	{
+		// language=yaml
+		fileSystem.AddFile("docs/_settings/applies-to-in-description.yml", """
+groups:
+  - group: Example
+    settings:
+      - setting: xpack.sample.versioned
+        description: |
+          Behavior depends on version:
+
+          * {applies_to}`stack: ga 9.2` Defaults to `model-a`.
+          * {applies_to}`stack: ga 9.1` Defaults to `model-b`.
+""");
+	}
+
+	[Fact]
+	public void RendersAppliesToRoleAsBadgeNotLiteralText()
+	{
+		Html.Should().Contain("applies-to-popover");
+		Html.Should().NotContain("Applies to (stack: ga 9.2)");
+		Html.Should().NotContain("Applies to (stack: ga 9.1)");
+	}
+}