Allow _docset.yml and _toc.yml as configuration filenames (#361)

* Allow _docset.yml and _toc.yml as configuration filenames

* revert enhanced code block parser changes

* fix slow lookup and randomly use underscore docset.yml in tests

* target known locations first before initiating a folder scan

src/Elastic.Markdown/BuildContext.cs

@@ -49,29 +49,42 @@ public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, str
 		var rootFolder = !string.IsNullOrWhiteSpace(source)
 			? ReadFileSystem.DirectoryInfo.New(source)
 			: ReadFileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName));
-		SourcePath = FindDocsFolderFromRoot(rootFolder);
+
+		(SourcePath, ConfigurationPath) = FindDocsFolderFromRoot(rootFolder);
 
 		OutputPath = !string.IsNullOrWhiteSpace(output)
 			? WriteFileSystem.DirectoryInfo.New(output)
 			: WriteFileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName, ".artifacts/docs/html"));
 
-		ConfigurationPath =
-			ReadFileSystem.FileInfo.New(Path.Combine(SourcePath.FullName, "docset.yml"));
-
 		if (ConfigurationPath.FullName != SourcePath.FullName)
 			SourcePath = ConfigurationPath.Directory!;
 
 		Git = GitCheckoutInformation.Create(ReadFileSystem);
 	}
 
-	private IDirectoryInfo FindDocsFolderFromRoot(IDirectoryInfo rootPath)
+	private (IDirectoryInfo, IFileInfo) FindDocsFolderFromRoot(IDirectoryInfo rootPath)
 	{
-		if (rootPath.Exists &&
-			ReadFileSystem.File.Exists(Path.Combine(rootPath.FullName, "docset.yml")))
-			return rootPath;
-
-		var docsFolder = rootPath.EnumerateFiles("docset.yml", SearchOption.AllDirectories).FirstOrDefault();
-		return docsFolder?.Directory ?? throw new Exception($"Can not locate docset.yml file in '{rootPath}'");
+		string[] files = ["docset.yml", "_docset.yml"];
+		string[] knownFolders = [rootPath.FullName, Path.Combine(rootPath.FullName, "docs")];
+		var mostLikelyTargets =
+			from file in files
+			from folder in knownFolders
+			select Path.Combine(folder, file);
+
+		var knownConfigPath = mostLikelyTargets.FirstOrDefault(ReadFileSystem.File.Exists);
+		var configurationPath = knownConfigPath is null ? null : ReadFileSystem.FileInfo.New(knownConfigPath);
+		if (configurationPath is not null)
+			return (configurationPath.Directory!, configurationPath);
+
+		configurationPath = rootPath
+			.EnumerateFiles("*docset.yml", SearchOption.AllDirectories)
+			.FirstOrDefault()
+			?? throw new Exception($"Can not locate docset.yml file in '{rootPath}'");
+
+		var docsFolder = configurationPath.Directory
+			?? throw new Exception($"Can not locate docset.yml file in '{rootPath}'");
+
+		return (docsFolder, configurationPath);
 	}
 
 }

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

@@ -257,8 +257,17 @@ private Dictionary<string, string> ReadDictionary(KeyValuePair<YamlNode, YamlNod
 		var rootPath = _context.ReadFileSystem.DirectoryInfo.New(Path.Combine(_rootPath.FullName, tocPath));
 		var path = Path.Combine(rootPath.FullName, "toc.yml");
 		var source = _context.ReadFileSystem.FileInfo.New(path);
+
+		var errorMessage = $"Nested toc: '{source.Directory}' directory has no toc.yml or _toc.yml file";
+
+		if (!source.Exists)
+		{
+			path = Path.Combine(rootPath.FullName, "_toc.yml");
+			source = _context.ReadFileSystem.FileInfo.New(path);
+		}
+
 		if (!source.Exists)
-			EmitError($"Nested toc: '{source.FullName}' does not exist", entry.Key);
+			EmitError(errorMessage, entry.Key);
 		else
 			found = true;
 

tests/authoring/Framework/Setup.fs

@@ -5,6 +5,7 @@
 namespace authoring
 
 
+open System
 open System.Collections.Generic
 open System.IO
 open System.IO.Abstractions.TestingHelpers
@@ -53,7 +54,8 @@ type Setup =
             )
         | _ -> ()
 
-        fileSystem.AddFile(Path.Combine(root.FullName, "docset.yml"), MockFileData(yaml.ToString()));
+        let name = if Random().Next(0, 10) % 2 = 0 then "_docset.yml" else "docset.yml"
+        fileSystem.AddFile(Path.Combine(root.FullName, name), MockFileData(yaml.ToString()));
 
     static member Generator (files: TestFile seq) : Task<GeneratorResults> =