Emit hints for deep-linking virtual files during validation:

- Add checks to identify files with deep paths and children, suggesting the use of `folder` for better structure.
- Extend test coverage for virtual file scenarios to validate hint emission and suppression.
- Refactor diagnostics in physical docset navigation to include hints while ensuring no errors or warnings occur.

Author: Mpdreamz

src/Elastic.Documentation.Configuration/DocSet/DocumentationSetFile.cs

@@ -229,6 +229,14 @@ private static ITableOfContentsItem ResolveFileRef(
 				: new FileRef(fullPath, fileRef.Hidden, [], context);
 		}
 
+		// Emit hint if file has children and uses deep-linking (path contains '/')
+		// This suggests using 'folder' instead of 'file' would be better
+		if (fileRef.Path.Contains('/') && fileRef.Children.Count > 0)
+		{
+			collector.EmitHint(context,
+				$"File '{fileRef.Path}' uses deep-linking with children. Consider using 'folder' instead of 'file' for better navigation structure. Virtual files are primarily intended to group sibling files together.");
+		}
+
 		// Children of a file should be resolved in the same directory as the parent file.
 		// Special handling for FolderIndexFileRef (folder+file combinations from YAML):
 		// - These are created when both folder and file keys exist (e.g., "folder: path/to/dir, file: index.md")

tests/Navigation.Tests/Isolation/PhysicalDocsetTests.cs

@@ -5,6 +5,7 @@
 using System.IO.Abstractions;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Configuration.DocSet;
+using Elastic.Documentation.Diagnostics;
 using Elastic.Documentation.Navigation.Isolated;
 using FluentAssertions;
 
@@ -118,8 +119,17 @@ public async Task PhysicalDocsetCanBeNavigated()
 		var folderUrls = folders.Select(f => f.Url).ToList();
 		folderUrls.Should().Contain("/contribute");
 
-		// No errors should be emitted during navigation construction
-		context.Diagnostics.Should().BeEmpty();
+		// No errors or warnings should be emitted during navigation construction
+		// Hints are acceptable for best practice guidance
+		context.Collector.Errors.Should().Be(0, "no errors should be emitted");
+		context.Collector.Warnings.Should().Be(0, "no warnings should be emitted");
+
+		// Verify that the hint about deep-linking virtual file was emitted
+		var hints = context.Diagnostics.Where(d => d.Severity == Severity.Hint).ToList();
+		hints.Should().Contain(d =>
+			d.Message.Contains("nest-under-index/index.md") &&
+			d.Message.Contains("deep-linking"),
+			"should emit hint for deep-linking virtual file");
 	}
 
 	[Fact]

tests/Navigation.Tests/Isolation/ValidationTests.cs

@@ -4,6 +4,7 @@
 
 using System.IO.Abstractions.TestingHelpers;
 using Elastic.Documentation.Configuration.DocSet;
+using Elastic.Documentation.Diagnostics;
 using Elastic.Documentation.Extensions;
 using Elastic.Documentation.Navigation.Isolated;
 using FluentAssertions;
@@ -169,4 +170,119 @@ public async Task ValidationEmitsErrorWhenTocYmlFileNotFound()
 			d.Message.Contains("Table of contents file not found") &&
 			d.Message.Contains("api/toc.yml"));
 	}
+
+	[Fact]
+	public async Task ValidationEmitsHintForDeepLinkingVirtualFiles()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - file: a/b/c/getting-started.md
+		               children:
+		                 - file: a/b/c/setup.md
+		                 - file: a/b/c/install.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		var context = CreateContext(fileSystem);
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+		_ = context.Collector.StartAsync(TestContext.Current.CancellationToken);
+
+		_ = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, GenericDocumentationFileFactory.Instance);
+
+		await context.Collector.StopAsync(TestContext.Current.CancellationToken);
+
+		context.Collector.Hints.Should().BeGreaterThan(0, "should have emitted a hint for deep-linking virtual file");
+		var diagnostics = context.Diagnostics;
+		diagnostics.Should().Contain(d =>
+			d.Severity == Severity.Hint &&
+			d.Message.Contains("a/b/c/getting-started.md") &&
+			d.Message.Contains("deep-linking") &&
+			d.Message.Contains("folder"));
+	}
+
+	[Fact]
+	public async Task ValidationEmitsHintForNestedPathVirtualFiles()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - file: guides/api/overview.md
+		               children:
+		                 - file: guides/api/authentication.md
+		                 - file: guides/api/endpoints.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		var context = CreateContext(fileSystem);
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+		_ = context.Collector.StartAsync(TestContext.Current.CancellationToken);
+
+		_ = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, GenericDocumentationFileFactory.Instance);
+
+		await context.Collector.StopAsync(TestContext.Current.CancellationToken);
+
+		context.Collector.Hints.Should().BeGreaterThan(0);
+		var diagnostics = context.Diagnostics;
+		diagnostics.Should().Contain(d =>
+			d.Severity == Severity.Hint &&
+			d.Message.Contains("guides/api/overview.md") &&
+			d.Message.Contains("Virtual files are primarily intended to group sibling files together"));
+	}
+
+	[Fact]
+	public async Task ValidationDoesNotEmitHintForSimpleVirtualFiles()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - file: guide.md
+		               children:
+		                 - file: chapter1.md
+		                 - file: chapter2.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		var context = CreateContext(fileSystem);
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+		_ = context.Collector.StartAsync(TestContext.Current.CancellationToken);
+
+		_ = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, GenericDocumentationFileFactory.Instance);
+
+		await context.Collector.StopAsync(TestContext.Current.CancellationToken);
+
+		context.Collector.Hints.Should().Be(0, "simple virtual files without deep-linking should not trigger hints");
+		context.Diagnostics.Should().BeEmpty();
+	}
+
+	[Fact]
+	public async Task ValidationDoesNotEmitHintForFilesWithoutChildren()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - file: a/b/c/getting-started.md
+		             - file: guides/setup.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		var context = CreateContext(fileSystem);
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+		_ = context.Collector.StartAsync(TestContext.Current.CancellationToken);
+
+		_ = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, GenericDocumentationFileFactory.Instance);
+
+		await context.Collector.StopAsync(TestContext.Current.CancellationToken);
+
+		context.Collector.Hints.Should().Be(0, "files without children should not trigger hints, even with deep paths");
+		context.Diagnostics.Should().BeEmpty();
+	}
 }