From 552b631853ec17369f98976e87fd28665bf95ef7 Mon Sep 17 00:00:00 2001
From: Jan Calanog <jan.calanog@elastic.co>
Date: Tue, 14 Jan 2025 16:33:40 +0100
Subject: [PATCH] Warn about links with template expressions (#191)

Related https://github.com/elastic/docs-builder/issues/182

## Details

Add warning if a link contains `{{` or `}}` thus using a template
expression.

Because

1) it doesn't work
2) it's discouraged to use template variables in links
---
 docs/source/syntax/links.md                   | 10 +++++++++
 .../DiagnosticLinkInlineParser.cs             |  6 +++++
 .../Inline/InlineLinkTests.cs                 | 22 +++++++++++++++++++
 3 files changed, 38 insertions(+)

diff --git a/docs/source/syntax/links.md b/docs/source/syntax/links.md
index 527a030..4381acd 100644
--- a/docs/source/syntax/links.md
+++ b/docs/source/syntax/links.md
@@ -32,6 +32,16 @@ I link to the [Inline link](#inline-link) heading above.
 I link to the [Notes](tables.md#notes) heading on the [Tables](tables.md) page.
 ```
 
+## Cross Links
+
+Cross links are links that point to a different docset.
+
+```markdown
+[Cross link](kibana://cross-link.md)
+```
+
+The syntax is `<scheme>://<path>`, where <scheme> is the repository name and <path> is the path to the file.
+
 ## Heading anchors
 
 Headings will automatically create anchor links in the resulting html. 
diff --git a/src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs b/src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs
index 021c4dd..69fed5b 100644
--- a/src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs
+++ b/src/Elastic.Markdown/Myst/InlineParsers/DiagnosticLinkInlineParser.cs
@@ -62,6 +62,12 @@ public override bool Match(InlineProcessor processor, ref StringSlice slice)
 			return match;
 		}
 
+		if (url.Contains("{{") || url.Contains("}}"))
+		{
+			processor.EmitWarning(line, column, length, "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 match;
+		}
+
 		var uri = Uri.TryCreate(url, UriKind.Absolute, out var u) ? u : null;
 
 		if (IsCrossLink(uri))
diff --git a/tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs b/tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs
index d52b492..a4ff9f5 100644
--- a/tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs
+++ b/tests/Elastic.Markdown.Tests/Inline/InlineLinkTests.cs
@@ -173,3 +173,25 @@ public void EmitsCrossLink()
 		Collector.CrossLinks.Should().Contain("kibana://index.md");
 	}
 }
+
+public class LinksWithInterpolationWarning(ITestOutputHelper output) : LinkTestBase(output,
+	"""
+	[global search field]({{kibana-ref}}/introduction.html#kibana-navigation-search)
+	"""
+)
+{
+	[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>"""
+		);
+
+	[Fact]
+	public void HasWarnings()
+	{
+		Collector.Diagnostics.Should().HaveCount(1);
+		Collector.Diagnostics.First().Severity.Should().Be(Diagnostics.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.");
+	}
+}