Fix settings directive LLM markdown output (#2009)

Author: reakaleek

src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs

@@ -9,12 +9,14 @@
 using Elastic.Markdown.Myst.Directives.Diagram;
 using Elastic.Markdown.Myst.Directives.Image;
 using Elastic.Markdown.Myst.Directives.Include;
+using Elastic.Markdown.Myst.Directives.Settings;
 using Markdig.Extensions.DefinitionLists;
 using Markdig.Extensions.Tables;
 using Markdig.Extensions.Yaml;
 using Markdig.Renderers;
 using Markdig.Syntax;
 using Markdig.Syntax.Inlines;
+using YamlDotNet.Core;
 using CodeBlock = Markdig.Syntax.CodeBlock;
 
 namespace Elastic.Markdown.Myst.Renderers.LlmMarkdown;
@@ -388,6 +390,9 @@ protected override void Write(LlmMarkdownRenderer renderer, DirectiveBlock obj)
 			case DiagramBlock diagramBlock:
 				WriteDiagramBlock(renderer, diagramBlock);
 				return;
+			case SettingsBlock settingsBlock:
+				WriteSettingsBlock(renderer, settingsBlock);
+				return;
 		}
 
 		// Ensure single empty line before directive
@@ -509,6 +514,99 @@ private void WriteIncludeBlock(LlmMarkdownRenderer renderer, IncludeBlock block)
 		renderer.EnsureLine();
 	}
 
+	private void WriteSettingsBlock(LlmMarkdownRenderer renderer, SettingsBlock block)
+	{
+		if (!block.Found || block.IncludePath is null)
+		{
+			var path = block.IncludePath ?? "(no path specified)";
+			renderer.BuildContext.Collector.EmitError(
+				block.IncludePath ?? string.Empty,
+				$"Settings directive error: Could not resolve path '{path}'. Ensure the file exists and the path is correct.");
+			return;
+		}
+
+		var file = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);
+
+		// Check if file exists before attempting to read
+		if (!file.Exists)
+		{
+			renderer.BuildContext.Collector.EmitError(
+				block.IncludePath,
+				$"Settings file not found: '{block.IncludePath}' does not exist. Check that the file path is correct and the file has been committed to the repository.");
+			return;
+		}
+
+		YamlSettings? settings;
+		try
+		{
+			var yaml = file.FileSystem.File.ReadAllText(file.FullName);
+			settings = YamlSerialization.Deserialize<YamlSettings>(yaml, block.Context.Build.ProductsConfiguration);
+		}
+		catch (FileNotFoundException e)
+		{
+			renderer.BuildContext.Collector.EmitError(
+				block.IncludePath,
+				$"Settings file not found: Unable to read '{block.IncludePath}'. The file may have been moved or deleted.",
+				e);
+			return;
+		}
+		catch (DirectoryNotFoundException e)
+		{
+			renderer.BuildContext.Collector.EmitError(
+				block.IncludePath,
+				$"Settings directory not found: The directory containing '{block.IncludePath}' does not exist. Check that the path is correct.",
+				e);
+			return;
+		}
+		catch (YamlException e)
+		{
+			renderer.BuildContext.Collector.EmitError(
+				block.IncludePath,
+				$"Invalid YAML in settings file: '{block.IncludePath}' contains invalid YAML syntax. Please check the file format matches the expected settings structure (groups, settings, etc.).",
+				e.InnerException ?? e);
+			return;
+		}
+		catch (Exception e)
+		{
+			renderer.BuildContext.Collector.EmitError(
+				block.IncludePath,
+				$"Failed to process settings file: Unable to parse '{block.IncludePath}'. Error: {e.Message}",
+				e);
+			return;
+		}
+
+		renderer.EnsureBlockSpacing();
+
+		foreach (var group in settings.Groups)
+		{
+			renderer.WriteLine();
+			renderer.Write("## ");
+			renderer.WriteLine(group.Name ?? string.Empty);
+
+			foreach (var setting in group.Settings)
+			{
+				renderer.WriteLine();
+				renderer.Write("#### ");
+				renderer.WriteLine(setting.Name ?? string.Empty);
+
+				if (!string.IsNullOrEmpty(setting.Description))
+				{
+					var document = MarkdownParser.ParseMarkdownStringAsync(
+						block.Build,
+						block.Context,
+						setting.Description,
+						block.IncludeFrom,
+						block.Context.YamlFrontMatter,
+						MarkdownParser.Pipeline);
+					_ = renderer.Render(document);
+					renderer.EnsureBlockSpacing();
+				}
+			}
+		}
+
+		renderer.EnsureLine();
+	}
+
 	private static void WriteChildrenWithIndentation(LlmMarkdownRenderer renderer, Block container, string indent)
 	{
 		// Capture output and manually add indentation

tests/authoring/LlmMarkdown/LlmMarkdownOutput.fs

@@ -602,3 +602,44 @@ sub:
         markdown |> convertsToNewLLM """
 ## Hello, World!
 """
+
+type ``settings directive`` () =
+    static let generator = Setup.Generate [
+        Index """
+:::{settings} _settings/example-settings.yml
+:::
+"""
+        File("_settings/example-settings.yml", """groups:
+  - group: General settings
+    settings:
+      - setting: xpack.example.setting
+        description: |
+          This is a test setting with **bold** text and a [link](https://example.com).
+      - setting: xpack.another.setting
+        description: Another setting description.
+  - group: Advanced settings
+    settings:
+      - setting: xpack.advanced.option
+        description: An advanced option.
+""")
+    ]
+
+    [<Fact>]
+    let ``renders settings as markdown headings`` () =
+        generator |> convertsToNewLLM """
+## General settings
+
+#### xpack.example.setting
+
+This is a test setting with **bold** text and a [link](https://example.com).
+
+#### xpack.another.setting
+
+Another setting description.
+
+## Advanced settings
+
+#### xpack.advanced.option
+
+An advanced option.
+"""