Restrict docset.yml configs that define toc.yml sections to ONLY link to sub toc.yml files

docs/_docset.yml

@@ -1,5 +1,8 @@
 project: 'doc-builder'
 max_toc_depth: 2
+# indicates this documentation set is not linkable by assembler.
+# relaxes a few restrictions around toc building and file placement
+dev_docs: true
 cross_links:
   - docs-content
 exclude:

src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs

@@ -44,6 +44,10 @@ public record ConfigurationFile : DocumentationFile
 	private FeatureFlags? _featureFlags;
 	public FeatureFlags Features => _featureFlags ??= new FeatureFlags(_features);
 
+	/// This is a documentation set that is not linked to by assembler.
+	/// Setting this to true relaxes a few restrictions such as mixing toc references with file and folder reference
+	public bool DevelopmentDocs { get; }
+
 	public ConfigurationFile(BuildContext context)
 		: base(context.ConfigurationPath, context.DocumentationSourceDirectory)
 	{
@@ -74,6 +78,9 @@ public ConfigurationFile(BuildContext context)
 					case "max_toc_depth":
 						MaxTocDepth = int.TryParse(reader.ReadString(entry.Entry), out var maxTocDepth) ? maxTocDepth : 1;
 						break;
+					case "dev_docs":
+						DevelopmentDocs = bool.TryParse(reader.ReadString(entry.Entry), out var devDocs) && devDocs;
+						break;
 					case "exclude":
 						var excludes = YamlStreamReader.ReadStringArray(entry.Entry);
 						Exclude = [.. excludes.Where(s => !string.IsNullOrEmpty(s)).Select(Glob.Parse)];
@@ -111,8 +118,11 @@ public ConfigurationFile(BuildContext context)
 				{
 					case "toc":
 						var toc = new TableOfContentsConfiguration(this, _context, 0, "");
-						var entries = toc.ReadChildren(reader, entry.Entry);
-						TableOfContents = entries;
+						var children = toc.ReadChildren(reader, entry.Entry);
+						var tocEntries = children.OfType<TocReference>().ToArray();
+						if (!DevelopmentDocs && tocEntries.Length > 0 && children.Count != tocEntries.Length)
+							reader.EmitError("toc links to other toc sections it may only contain other toc references", entry.Key);
+						TableOfContents = children;
 						Files = toc.Files; //side-effect ripe for refactor
 						break;
 				}

src/Elastic.Markdown/IO/Configuration/ITocItem.cs

@@ -9,3 +9,5 @@ public interface ITocItem;
 public record FileReference(string Path, bool Found, bool Hidden, IReadOnlyCollection<ITocItem> Children) : ITocItem;
 
 public record FolderReference(string Path, bool Found, bool InNav, IReadOnlyCollection<ITocItem> Children) : ITocItem;
+
+public record TocReference(string Path, bool Found, bool InNav, IReadOnlyCollection<ITocItem> Children) : FolderReference(Path, Found, InNav, Children);

src/Elastic.Markdown/IO/Configuration/TableOfContentsConfiguration.cs

@@ -112,7 +112,7 @@ public IReadOnlyCollection<ITocItem> ReadChildren(YamlStreamReader reader, KeyVa
 			foreach (var f in toc.Files)
 				_ = Files.Add(f);
 
-			return [new FolderReference($"{parentPath}".TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)];
+			return [new TocReference($"{parentPath}".TrimStart(Path.DirectorySeparatorChar), folderFound, inNav, toc.TableOfContents)];
 		}
 
 		if (file is not null)