Add utility class for crosslink validation

Author: theletterf

docs/_docset.yml

@@ -129,6 +129,9 @@ toc:
       - file: req.md
       - folder: nested
       - file: cross-links.md
+        children:
+          - title: "Getting Started Guide"
+            crosslink: docs-content://get-started/introduction.md
       - file: custom-highlighters.md
       - hidden: archive.md
       - hidden: landing-page.md
@@ -153,8 +156,4 @@ toc:
           - file: bar.md
           - folder: baz
             children:
-              - file: qux.md
-      - title: "Getting Started Guide"
-        crosslink: docs-content://get-started/introduction.md
-      - title: "Test title"
-        crosslink: docs-content://solutions/search/elasticsearch-basics-quickstart.md
+              - file: qux.md

src/Elastic.Documentation.Configuration/Builder/TableOfContentsConfiguration.cs

@@ -6,6 +6,7 @@
 using System.Runtime.InteropServices;
 using Elastic.Documentation.Configuration.Plugins.DetectionRules.TableOfContents;
 using Elastic.Documentation.Configuration.TableOfContents;
+using Elastic.Documentation.Links;
 using Elastic.Documentation.Navigation;
 using YamlDotNet.RepresentationModel;
 
@@ -157,19 +158,9 @@ private IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyV
 					hiddenFile = false;
 					crossLink = reader.ReadString(entry);
 					// Validate crosslink URI early
-					if (string.IsNullOrWhiteSpace(crossLink))
+					if (!CrossLinkValidator.IsValidCrossLink(crossLink, out var errorMessage))
 					{
-						reader.EmitError("Cross-link entries must specify a non-empty 'crosslink' URI", tocEntry);
-						crossLink = null; // Reset to prevent further processing
-					}
-					else if (!Uri.TryCreate(crossLink, UriKind.Absolute, out var parsedUri))
-					{
-						reader.EmitError($"Cross-link URI '{crossLink}' is not a valid absolute URI format", tocEntry);
-						crossLink = null; // Reset to prevent further processing
-					}
-					else if (parsedUri.Scheme is "http" or "https" or "ftp" or "file")
-					{
-						reader.EmitError($"Cross-link URI '{crossLink}' cannot use standard web schemes (http, https, ftp, file). Use cross-repository schemes like 'docs-content://', 'kibana://', etc.", tocEntry);
+						reader.EmitError(errorMessage!, tocEntry);
 						crossLink = null; // Reset to prevent further processing
 					}
 					break;
@@ -197,6 +188,15 @@ private IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyV
 			return null;
 		}
 
+		// Validate that standalone titles (without content) are not allowed
+		if (!string.IsNullOrWhiteSpace(title) &&
+			file is null && crossLink is null && folder is null && toc is null &&
+			(detectionRules is null || detectionRules.Length == 0))
+		{
+			reader.EmitError($"Table of contents entries with only a 'title' are not allowed. Entry must specify content (file, crosslink, folder, or toc). Title: '{title}'", tocEntry);
+			return null;
+		}
+
 		if (toc is not null)
 		{
 			foreach (var f in toc.Files)

src/Elastic.Documentation/Links/CrossLinkValidator.cs

@@ -0,0 +1,69 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Collections.Immutable;
+
+namespace Elastic.Documentation.Links;
+
+/// <summary>
+/// Utility class for validating and identifying cross-repository links
+/// </summary>
+public static class CrossLinkValidator
+{
+	/// <summary>
+	/// URI schemes that are excluded from being treated as cross-repository links.
+	/// These are standard web/protocol schemes that should not be processed as crosslinks.
+	/// </summary>
+	private static readonly ImmutableHashSet<string> ExcludedSchemes =
+		ImmutableHashSet.Create(StringComparer.OrdinalIgnoreCase,
+			"http", "https", "ftp", "file", "tel", "jdbc", "mailto");
+
+	/// <summary>
+	/// Validates that a URI string is a valid cross-repository link.
+	/// </summary>
+	/// <param name="uriString">The URI string to validate</param>
+	/// <param name="errorMessage">Error message if validation fails</param>
+	/// <returns>True if valid crosslink, false otherwise</returns>
+	public static bool IsValidCrossLink(string? uriString, out string? errorMessage)
+	{
+		errorMessage = null;
+
+		if (string.IsNullOrWhiteSpace(uriString))
+		{
+			errorMessage = "Cross-link entries must specify a non-empty URI";
+			return false;
+		}
+
+		if (!Uri.TryCreate(uriString, UriKind.Absolute, out var uri))
+		{
+			errorMessage = $"Cross-link URI '{uriString}' is not a valid absolute URI format";
+			return false;
+		}
+
+		if (ExcludedSchemes.Contains(uri.Scheme))
+		{
+			errorMessage = $"Cross-link URI '{uriString}' cannot use standard web/protocol schemes ({string.Join(", ", ExcludedSchemes)}). Use cross-repository schemes like 'docs-content://', 'kibana://', etc.";
+			return false;
+		}
+
+		return true;
+	}
+
+	/// <summary>
+	/// Determines if a URI is a cross-repository link (for identification purposes).
+	/// This is more permissive than validation and is used by the Markdown parser.
+	/// </summary>
+	/// <param name="uri">The URI to check</param>
+	/// <returns>True if this should be treated as a crosslink</returns>
+	public static bool IsCrossLink(Uri? uri) =>
+		uri != null
+		&& !ExcludedSchemes.Contains(uri.Scheme)
+		&& !uri.IsFile
+		&& !string.IsNullOrEmpty(uri.Scheme);
+
+	/// <summary>
+	/// Gets the list of excluded URI schemes for reference
+	/// </summary>
+	public static IReadOnlySet<string> GetExcludedSchemes() => ExcludedSchemes;
+}

src/Elastic.Markdown/IO/Navigation/DocumentationGroup.cs

@@ -7,6 +7,7 @@
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Configuration.TableOfContents;
 using Elastic.Documentation.Extensions;
+using Elastic.Documentation.Links;
 using Elastic.Documentation.Site.Navigation;
 
 namespace Elastic.Markdown.IO.Navigation;
@@ -123,19 +124,10 @@ void AddToNavigationItems(INavigationItem item, ref int fileIndex)
 		{
 			if (tocItem is CrossLinkReference crossLink)
 			{
-				// Validate that cross-link URI is not empty
-				if (string.IsNullOrWhiteSpace(crossLink.CrossLinkUri))
+				// Validate crosslink URI and title
+				if (!CrossLinkValidator.IsValidCrossLink(crossLink.CrossLinkUri, out var errorMessage))
 				{
-					context.EmitError(context.ConfigurationPath,
-						"Cross-link entries must have a 'crosslink' URI specified.");
-					continue;
-				}
-
-				// Validate that cross-link URI is a valid URI format
-				if (!Uri.TryCreate(crossLink.CrossLinkUri, UriKind.Absolute, out var parsedUri))
-				{
-					context.EmitError(context.ConfigurationPath,
-						$"Cross-link URI '{crossLink.CrossLinkUri}' is not a valid absolute URI format.");
+					context.EmitError(context.ConfigurationPath, errorMessage!);
 					continue;
 				}
 

src/Elastic.Markdown/Links/CrossLinks/CrossLinkValidator.cs

@@ -0,0 +1,69 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Collections.Immutable;
+
+namespace Elastic.Markdown.Links.CrossLinks;
+
+/// <summary>
+/// Utility class for validating and identifying cross-repository links
+/// </summary>
+public static class CrossLinkValidator
+{
+	/// <summary>
+	/// URI schemes that are excluded from being treated as cross-repository links.
+	/// These are standard web/protocol schemes that should not be processed as crosslinks.
+	/// </summary>
+	private static readonly ImmutableHashSet<string> ExcludedSchemes =
+		ImmutableHashSet.Create(StringComparer.OrdinalIgnoreCase,
+			"http", "https", "ftp", "file", "tel", "jdbc", "mailto");
+
+	/// <summary>
+	/// Validates that a URI string is a valid cross-repository link.
+	/// </summary>
+	/// <param name="uriString">The URI string to validate</param>
+	/// <param name="errorMessage">Error message if validation fails</param>
+	/// <returns>True if valid crosslink, false otherwise</returns>
+	public static bool IsValidCrossLink(string? uriString, out string? errorMessage)
+	{
+		errorMessage = null;
+
+		if (string.IsNullOrWhiteSpace(uriString))
+		{
+			errorMessage = "Cross-link entries must specify a non-empty URI";
+			return false;
+		}
+
+		if (!Uri.TryCreate(uriString, UriKind.Absolute, out var uri))
+		{
+			errorMessage = $"Cross-link URI '{uriString}' is not a valid absolute URI format";
+			return false;
+		}
+
+		if (ExcludedSchemes.Contains(uri.Scheme))
+		{
+			errorMessage = $"Cross-link URI '{uriString}' cannot use standard web/protocol schemes ({string.Join(", ", ExcludedSchemes)}). Use cross-repository schemes like 'docs-content://', 'kibana://', etc.";
+			return false;
+		}
+
+		return true;
+	}
+
+	/// <summary>
+	/// Determines if a URI is a cross-repository link (for identification purposes).
+	/// This is more permissive than validation and is used by the Markdown parser.
+	/// </summary>
+	/// <param name="uri">The URI to check</param>
+	/// <returns>True if this should be treated as a crosslink</returns>
+	public static bool IsCrossLink(Uri? uri) =>
+		uri != null
+		&& !ExcludedSchemes.Contains(uri.Scheme)
+		&& !uri.IsFile
+		&& !string.IsNullOrEmpty(uri.Scheme);
+
+	/// <summary>
+	/// Gets the list of excluded URI schemes for reference
+	/// </summary>
+	public static IReadOnlySet<string> GetExcludedSchemes() => ExcludedSchemes;
+}

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

@@ -7,6 +7,7 @@
 using System.IO.Abstractions;
 using System.Runtime.InteropServices;
 using System.Text.RegularExpressions;
+using Elastic.Documentation.Links;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Helpers;
 using Elastic.Markdown.IO;
@@ -46,9 +47,6 @@ internal sealed partial class LinkRegexExtensions
 
 public class DiagnosticLinkInlineParser : LinkInlineParser
 {
-	// See https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml for a list of URI schemes
-	private static readonly ImmutableHashSet<string> ExcludedSchemes = ["http", "https", "tel", "jdbc", "mailto"];
-
 	public override bool Match(InlineProcessor processor, ref StringSlice slice)
 	{
 		var match = base.Match(processor, ref slice);
@@ -389,8 +387,5 @@ public static string UpdateRelativeUrl(ParserContext context, string url)
 	}
 
 	private static bool IsCrossLink([NotNullWhen(true)] Uri? uri) =>
-		uri != null // This means it's not a local
-		&& !ExcludedSchemes.Contains(uri.Scheme)
-		&& !uri.IsFile
-		&& !string.IsNullOrEmpty(uri.Scheme);
+		CrossLinkValidator.IsCrossLink(uri);
 }