Allow substitutions in external links (#715)

* Allow substitutions in external links

* Better error messages

* Fix typo

Author: reakaleek

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

@@ -7,6 +7,7 @@
 using System.IO.Abstractions;
 using System.Text.RegularExpressions;
 using Elastic.Markdown.Diagnostics;
+using Elastic.Markdown.Helpers;
 using Elastic.Markdown.IO;
 using Elastic.Markdown.Myst.Comments;
 using Markdig;
@@ -100,6 +101,26 @@ private static void ValidateAndProcessLink(LinkInline link, InlineProcessor proc
 	{
 		var url = link.Url;
 
+		if (url?.Contains("{{") == true)
+		{
+			var replacedUrl = url.ReplaceSubstitutions(processor.GetContext());
+			if (replacedUrl.Contains("{{"))
+			{
+				processor.EmitError(link,
+					$"The url contains unresolved template expressions: '{replacedUrl}'. Please check if there is an appropriate global or frontmatter subs variable."
+				);
+				return;
+			}
+
+			if (!replacedUrl.StartsWith("http"))
+			{
+				processor.EmitError(link, $"Link is resolved to '{replacedUrl}'. Only external links are allowed to be resolved from template expressions.");
+				return;
+			}
+			url = replacedUrl;
+			link.Url = replacedUrl;
+		}
+
 		if (!ValidateBasicUrl(link, processor, url))
 			return;
 
@@ -124,15 +145,6 @@ private static bool ValidateBasicUrl(LinkInline link, InlineProcessor processor,
 			processor.EmitError(link, "Found empty url");
 			return false;
 		}
-
-		if (url.Contains("{{") || url.Contains("}}"))
-		{
-			processor.EmitWarning(link,
-				"The url contains a template expression. Please do not use template expressions in links. " +
-				"See https://github.com/elastic/docs-builder/issues/182 for further information.");
-			return false;
-		}
-
 		return true;
 	}
 

tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs

@@ -11,7 +11,15 @@
 namespace Elastic.Markdown.Tests.Inline;
 
 public abstract class LinkTestBase(ITestOutputHelper output, [LanguageInjection("markdown")] string content)
-	: InlineTest<LinkInline>(output, content)
+	: InlineTest<LinkInline>(
+		output,
+		content,
+		new Dictionary<string, string>
+		{
+			{ "some-url-with-a-version", "https://github.com/elastic/fake-repo/tree/v1.17.0" },
+			{ "some-url-path-prefix", "/something" },
+		}
+	)
 {
 	[Fact]
 	public void ParsesBlock() => Block.Should().NotBeNull();
@@ -161,28 +169,59 @@ public void EmitsCrossLink()
 	}
 }
 
-public class LinksWithInterpolationWarning(ITestOutputHelper output) : LinkTestBase(output,
+public class LinkWithUnresolvedInterpolationError(ITestOutputHelper output) : LinkTestBase(output,
 	"""
-	[global search field]({{kibana-ref}}/introduction.html#kibana-navigation-search)
+	[global search field]({{this-variable-does-not-exist}}/introduction.html#kibana-navigation-search)
+	"""
+)
+{
+	[Fact]
+	public void HasErrors()
+	{
+		Collector.Diagnostics.Should().HaveCount(1);
+		Collector.Diagnostics.First().Severity.Should().Be(Severity.Error);
+		Collector.Diagnostics.First().Message.Should().Contain("he url contains unresolved template expressions: '{{this-variable-does-not-exist}}/introduction.html#kibana-navigation-search'. Please check if there is an appropriate global or frontmatter subs variable.");
+	}
+}
+
+public class ExternalLinksWithInterpolationSuccess(ITestOutputHelper output) : LinkTestBase(output,
+	"""
+	[link to app]({{some-url-with-a-version}})
 	"""
 )
 {
 	[Fact]
 	public void GeneratesHtml() =>
 		// language=html
 		Html.Should().Contain(
-			"""<p><a href="%7B%7Bkibana-ref%7D%7D/introduction.html#kibana-navigation-search">global search field</a></p>"""
+			"""<p><a href="https://github.com/elastic/fake-repo/tree/v1.17.0">link to app</a></p>"""
 		);
 
+	[Fact]
+	public void HasNoWarningsOrErrors()
+	{
+		Collector.Diagnostics.Should().HaveCount(0);
+	}
+}
+
+public class InternalLinksWithInterpolationWarning(ITestOutputHelper output) : LinkTestBase(output,
+	"""
+	[link to app]({{some-url-path-prefix}}/hello-world)
+	"""
+)
+{
 	[Fact]
 	public void HasWarnings()
 	{
 		Collector.Diagnostics.Should().HaveCount(1);
-		Collector.Diagnostics.First().Severity.Should().Be(Severity.Warning);
-		Collector.Diagnostics.First().Message.Should().Contain("The url contains a template expression. Please do not use template expressions in links. See https://github.com/elastic/docs-builder/issues/182 for further information.");
+		Collector.Diagnostics.First().Severity.Should().Be(Severity.Error);
+		Collector.Diagnostics.First().Message.Should().Contain("Link is resolved to '/something/hello-world'. Only external links are allowed to be resolved from template expressions.");
 	}
 }
 
+
+
+
 public class NonExistingLinks(ITestOutputHelper output) : LinkTestBase(output,
 	"""
 	[Non Existing Link](/non-existing.md)

tests/Elastic.Markdown.Tests/Inline/InlneBaseTests.cs

@@ -48,8 +48,8 @@ public override async ValueTask InitializeAsync()
 
 }
 
-public abstract class InlineTest<TDirective>(ITestOutputHelper output, [LanguageInjection("markdown")] string content)
-	: InlineTest(output, content)
+public abstract class InlineTest<TDirective>(ITestOutputHelper output, [LanguageInjection("markdown")] string content, Dictionary<string, string>? globalVariables = null)
+	: InlineTest(output, content, globalVariables)
 	where TDirective : ContainerInline
 {
 	protected TDirective? Block { get; private set; }