Merge branch 'main' into add-automated-guide

Author: bmorelli25

src/Elastic.Markdown/BuildContext.cs

@@ -48,7 +48,7 @@ public BuildContext(IFileSystem readFileSystem, IFileSystem writeFileSystem, str
 
 		var rootFolder = !string.IsNullOrWhiteSpace(source)
 			? ReadFileSystem.DirectoryInfo.New(source)
-			: ReadFileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName, "docs"));
+			: ReadFileSystem.DirectoryInfo.New(Path.Combine(Paths.Root.FullName));
 		SourcePath = FindDocsFolderFromRoot(rootFolder);
 
 		OutputPath = !string.IsNullOrWhiteSpace(output)

src/Elastic.Markdown/DocumentationGenerator.cs

@@ -50,8 +50,12 @@ ILoggerFactory logger
 	}
 
 
-	public async Task ResolveDirectoryTree(Cancel ctx) =>
+	public async Task ResolveDirectoryTree(Cancel ctx)
+	{
+		_logger.LogInformation("Resolving tree");
 		await DocumentationSet.Tree.Resolve(ctx);
+		_logger.LogInformation("Resolved tree");
+	}
 
 	public async Task GenerateAll(Cancel ctx)
 	{
@@ -62,11 +66,30 @@ public async Task GenerateAll(Cancel ctx)
 		if (CompilationNotNeeded(generationState, out var offendingFiles, out var outputSeenChanges))
 			return;
 
-		_logger.LogInformation("Resolving tree");
 		await ResolveDirectoryTree(ctx);
-		_logger.LogInformation("Resolved tree");
 
+		await ProcessDocumentationFiles(offendingFiles, outputSeenChanges, ctx);
+
+		await ExtractEmbeddedStaticResources(ctx);
+
+
+		_logger.LogInformation($"Completing diagnostics channel");
+		Context.Collector.Channel.TryComplete();
 
+		_logger.LogInformation($"Generating documentation compilation state");
+		await GenerateDocumentationState(ctx);
+		_logger.LogInformation($"Generating links.json");
+		await GenerateLinkReference(ctx);
+
+		_logger.LogInformation($"Completing diagnostics channel");
+
+		await Context.Collector.StopAsync(ctx);
+
+		_logger.LogInformation($"Completed diagnostics channel");
+	}
+
+	private async Task ProcessDocumentationFiles(HashSet<string> offendingFiles, DateTimeOffset outputSeenChanges, Cancel ctx)
+	{
 		var processedFileCount = 0;
 		var exceptionCount = 0;
 		_ = Context.Collector.StartAsync(ctx);
@@ -91,7 +114,10 @@ await Parallel.ForEachAsync(DocumentationSet.Files, ctx, async (file, token) =>
 			if (processedFiles % 100 == 0)
 				_logger.LogInformation($"-> Handled {processedFiles} files");
 		});
+	}
 
+	private async Task ExtractEmbeddedStaticResources(Cancel ctx)
+	{
 		_logger.LogInformation($"Copying static files to output directory");
 		var embeddedStaticFiles = Assembly.GetExecutingAssembly()
 			.GetManifestResourceNames()
@@ -111,21 +137,6 @@ await Parallel.ForEachAsync(DocumentationSet.Files, ctx, async (file, token) =>
 			await resourceStream.CopyToAsync(stream, ctx);
 			_logger.LogInformation($"Copied static embedded resource {path}");
 		}
-
-
-		_logger.LogInformation($"Completing diagnostics channel");
-		Context.Collector.Channel.TryComplete();
-
-		_logger.LogInformation($"Generating documentation compilation state");
-		await GenerateDocumentationState(ctx);
-		_logger.LogInformation($"Generating links.json");
-		await GenerateLinkReference(ctx);
-
-		_logger.LogInformation($"Completing diagnostics channel");
-
-		await Context.Collector.StopAsync(ctx);
-
-		_logger.LogInformation($"Completed diagnostics channel");
 	}
 
 	private async Task ProcessFile(HashSet<string> offendingFiles, DocumentationFile file, DateTimeOffset outputSeenChanges, CancellationToken token)

src/Elastic.Markdown/IO/Discovery/GitCheckoutInformation.cs

@@ -39,19 +39,18 @@ public string? RepositoryName
 	// manual read because libgit2sharp is not yet AOT ready
 	public static GitCheckoutInformation Create(IFileSystem fileSystem)
 	{
-		// filesystem is not real so return a dummy
-		var fakeRef = Guid.NewGuid().ToString().Substring(0, 16);
 		if (fileSystem is not FileSystem)
 		{
 			return new GitCheckoutInformation
 			{
-				Branch = $"test-{fakeRef}",
+				Branch = $"test-e35fcb27-5f60-4e",
 				Remote = "elastic/docs-builder",
-				Ref = fakeRef,
+				Ref = "e35fcb27-5f60-4e",
 				RepositoryName = "docs-builder"
 			};
 		}
 
+		var fakeRef = Guid.NewGuid().ToString()[..16];
 		var gitConfig = Git(".git/config");
 		if (!gitConfig.Exists)
 			return Unavailable;

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -63,8 +63,8 @@ public string? NavigationTitle
 	private readonly Dictionary<string, PageTocItem> _tableOfContent = new(StringComparer.OrdinalIgnoreCase);
 	public IReadOnlyDictionary<string, PageTocItem> TableOfContents => _tableOfContent;
 
-	private readonly HashSet<string> _additionalLabels = new(StringComparer.OrdinalIgnoreCase);
-	public IReadOnlySet<string> AdditionalLabels => _additionalLabels;
+	private readonly HashSet<string> _anchors = new(StringComparer.OrdinalIgnoreCase);
+	public IReadOnlySet<string> Anchors => _anchors;
 
 	public string FilePath { get; }
 	public string FileName { get; }
@@ -89,7 +89,7 @@ public MarkdownFile[] YieldParents()
 		return parents.ToArray();
 	}
 
-	public async Task<MarkdownDocument> MinimalParse(Cancel ctx)
+	public async Task<MarkdownDocument> MinimalParseAsync(Cancel ctx)
 	{
 		var document = await MarkdownParser.MinimalParseAsync(SourceFile, ctx);
 		ReadDocumentInstructions(document);
@@ -99,7 +99,7 @@ public async Task<MarkdownDocument> MinimalParse(Cancel ctx)
 	public async Task<MarkdownDocument> ParseFullAsync(Cancel ctx)
 	{
 		if (!_instructionsParsed)
-			await MinimalParse(ctx);
+			await MinimalParseAsync(ctx);
 
 		var document = await MarkdownParser.ParseAsync(SourceFile, YamlFrontMatter, ctx);
 		return document;
@@ -171,22 +171,22 @@ private void ReadDocumentInstructions(MarkdownDocument document)
 				Slug = (h.Item2 ?? h.Item1).Slugify()
 			})
 			.ToList();
+
 		_tableOfContent.Clear();
 		foreach (var t in contents)
 			_tableOfContent[t.Slug] = t;
 
-		var labels = document.Descendants<DirectiveBlock>()
+		var anchors = document.Descendants<DirectiveBlock>()
 			.Select(b => b.CrossReferenceName)
 			.Where(l => !string.IsNullOrWhiteSpace(l))
 			.Select(s => s.Slugify())
 			.Concat(document.Descendants<InlineAnchor>().Select(a => a.Anchor))
+			.Concat(_tableOfContent.Values.Select(t => t.Slug))
+			.Where(anchor => !string.IsNullOrEmpty(anchor))
 			.ToArray();
 
-		foreach (var label in labels)
-		{
-			if (!string.IsNullOrEmpty(label))
-				_additionalLabels.Add(label);
-		}
+		foreach (var label in anchors)
+			_anchors.Add(label);
 
 		_instructionsParsed = true;
 	}

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

@@ -146,10 +146,10 @@ public async Task Resolve(Cancel ctx = default)
 		if (_resolved)
 			return;
 
-		await Parallel.ForEachAsync(FilesInOrder, ctx, async (file, token) => await file.MinimalParse(token));
+		await Parallel.ForEachAsync(FilesInOrder, ctx, async (file, token) => await file.MinimalParseAsync(token));
 		await Parallel.ForEachAsync(GroupsInOrder, ctx, async (group, token) => await group.Resolve(token));
 
-		await (Index?.MinimalParse(ctx) ?? Task.CompletedTask);
+		await (Index?.MinimalParseAsync(ctx) ?? Task.CompletedTask);
 
 		_resolved = true;
 	}

src/Elastic.Markdown/IO/State/LinkReference.cs

@@ -7,6 +7,13 @@
 
 namespace Elastic.Markdown.IO.State;
 
+public record LinkMetadata
+{
+	[JsonPropertyName("anchors")]
+	[JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+	public required string[]? Anchors { get; init; } = [];
+}
+
 public record LinkReference
 {
 	[JsonPropertyName("origin")]
@@ -15,8 +22,9 @@ public record LinkReference
 	[JsonPropertyName("url_path_prefix")]
 	public required string? UrlPathPrefix { get; init; }
 
+	/// Mapping of relative filepath and all the page's anchors for deeplinks
 	[JsonPropertyName("links")]
-	public required string[] Links { get; init; } = [];
+	public required Dictionary<string, LinkMetadata> Links { get; init; } = [];
 
 	[JsonPropertyName("cross_links")]
 	public required string[] CrossLinks { get; init; } = [];
@@ -25,7 +33,12 @@ public static LinkReference Create(DocumentationSet set)
 	{
 		var crossLinks = set.Context.Collector.CrossLinks.ToHashSet().ToArray();
 		var links = set.MarkdownFiles.Values
-			.Select(m => m.RelativePath).ToArray();
+			.Select(m => (m.RelativePath, m.Anchors))
+			.ToDictionary(k => k.RelativePath, v =>
+			{
+				var anchors = v.Anchors.Count == 0 ? null : v.Anchors.ToArray();
+				return new LinkMetadata { Anchors = anchors };
+			});
 		return new LinkReference
 		{
 			UrlPathPrefix = set.Context.UrlPathPrefix,

src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlock.cs

@@ -20,7 +20,7 @@ public class EnhancedCodeBlock(BlockParser parser, ParserContext context)
 
 	public int OpeningLength => Info?.Length ?? 0 + 3;
 
-	public List<CallOut>? CallOuts { get; set; }
+	public List<CallOut> CallOuts { get; set; } = [];
 
 	public IReadOnlyCollection<CallOut> UniqueCallOuts => CallOuts?.DistinctBy(c => c.Index).ToList() ?? [];
 

src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockHtmlRenderer.cs

@@ -55,7 +55,7 @@ private static void RenderCallouts(HtmlRenderer renderer, EnhancedCodeBlock bloc
 	{
 		var callOuts = FindCallouts(block.CallOuts ?? [], lineNumber + 1);
 		foreach (var callOut in callOuts)
-			renderer.Write($"<span class=\"code-callout\">{callOut.Index}</span>");
+			renderer.Write($"<span class=\"code-callout\" data-index=\"{callOut.Index}\">{callOut.Index}</span>");
 	}
 
 	private static IEnumerable<CallOut> FindCallouts(