Fix cross-links to markdown files to preserve .md extensions

- Store original cross-link URL before resolution
- Detect cross-links pointing to .md files
- Extract relative path with .md extension for LLM output
- Update test to validate cross-link behavior
- Maintain absolute URLs for non-markdown cross-links

Co-authored-by: reakaleek <[email protected]>

Author: Copilot

src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs

@@ -179,6 +179,9 @@ private static void ProcessCrossLink(LinkInline link, InlineProcessor processor,
 		if (url != null)
 			context.Build.Collector.EmitCrossLink(url);
 
+		// Store the original cross-link URL for LLM rendering
+		link.SetData("originalCrossLinkUrl", uri.ToString());
+
 		if (context.CrossLinkResolver.TryResolve(
 				s => processor.EmitError(link, s),
 				uri, out var resolvedUri)

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

@@ -37,16 +37,24 @@ protected override void Write(LlmMarkdownRenderer renderer, LinkInline obj)
 			// Check if this is an internal link to a markdown page
 			var isCrossLink = (obj.GetData("isCrossLink") as bool?) == true;
 			var hasTargetNavigationRoot = obj.GetData($"Target{nameof(MarkdownFile.NavigationRoot)}") != null;
+			var originalCrossLinkUrl = obj.GetData("originalCrossLinkUrl") as string;
 			var isInternalMarkdownLink = !isCrossLink && hasTargetNavigationRoot;
+			var isCrossLinkToMarkdown = isCrossLink && originalCrossLinkUrl != null && IsCrossLinkToMarkdown(originalCrossLinkUrl);
 
 			if (isInternalMarkdownLink)
 			{
 				// For internal markdown links, preserve the .md extension
 				renderer.Writer.Write(EnsureMarkdownExtension(url) ?? string.Empty);
 			}
+			else if (isCrossLinkToMarkdown)
+			{
+				// For cross-links to markdown files, extract relative path with .md extension
+				var markdownPath = ExtractMarkdownPath(originalCrossLinkUrl!);
+				renderer.Writer.Write(markdownPath ?? string.Empty);
+			}
 			else
 			{
-				// For external links and cross-links, make absolute
+				// For external links and non-markdown cross-links, make absolute
 				var absoluteUrl = LlmRenderingHelpers.MakeAbsoluteUrl(renderer, url);
 				renderer.Writer.Write(absoluteUrl ?? string.Empty);
 			}
@@ -78,6 +86,44 @@ protected override void Write(LlmMarkdownRenderer renderer, LinkInline obj)
 		// Add .md extension to internal markdown links
 		return processedUrl + ".md";
 	}
+
+	/// <summary>
+	/// Checks if a cross-link URL points to a markdown file
+	/// </summary>
+	private static bool IsCrossLinkToMarkdown(string originalCrossLinkUrl)
+	{
+		if (string.IsNullOrEmpty(originalCrossLinkUrl))
+			return false;
+
+		// Parse the cross-link URI to extract the path
+		if (Uri.TryCreate(originalCrossLinkUrl, UriKind.Absolute, out var uri))
+		{
+			var path = uri.AbsolutePath;
+			return path.EndsWith(".md", StringComparison.OrdinalIgnoreCase);
+		}
+
+		return false;
+	}
+
+	/// <summary>
+	/// Extracts the relative markdown path from a cross-link URL
+	/// </summary>
+	private static string? ExtractMarkdownPath(string originalCrossLinkUrl)
+	{
+		if (string.IsNullOrEmpty(originalCrossLinkUrl))
+			return null;
+
+		// Parse the cross-link URI to extract the path
+		if (Uri.TryCreate(originalCrossLinkUrl, UriKind.Absolute, out var uri))
+		{
+			var path = uri.AbsolutePath;
+			if (path.StartsWith('/'))
+				path = path.TrimStart('/');
+			return path;
+		}
+
+		return null;
+	}
 }
 
 public class LlmEmphasisInlineRenderer : MarkdownObjectRenderer<LlmMarkdownRenderer, EmphasisInline>

tests/authoring/LlmMarkdown/LlmMarkdownOutput.fs

@@ -546,7 +546,7 @@ This is a [link to another page](another-page.md).
 
 This is an [external link](https://example.com).
 
-This is a [cross-link](https://docs.elastic.co/some-page).
+This is a [cross-link](docs-content:/solutions/observability/apps/apm-server-binary.md).
 """
         Markdown "another-page.md" """
 # Another Page
@@ -560,5 +560,5 @@ This is another page for testing internal links.
         generator |> convertsToNewLLM """
 This is a [link to another page](another-page.md).
 This is an [external link](https://example.com).
-This is a [cross-link](https://docs.elastic.co/some-page).
+This is a [cross-link](solutions/observability/apps/apm-server-binary.md).
 """