Codex (#2730)

* Codex upgrade

* dotnet format

* Fix

Author: reakaleek

src/Elastic.Codex/Building/CodexBuildService.cs

@@ -8,12 +8,14 @@
 using Elastic.Codex.Sourcing;
 using Elastic.Documentation;
 using Elastic.Documentation.Configuration;
+using Elastic.Documentation.Configuration.Codex;
 using Elastic.Documentation.Diagnostics;
 using Elastic.Documentation.Isolated;
 using Elastic.Documentation.Links.CrossLinks;
 using Elastic.Documentation.Navigation;
 using Elastic.Documentation.Navigation.Isolated.Node;
 using Elastic.Documentation.Services;
+using Elastic.Documentation.Site;
 using Elastic.Documentation.Site.Navigation;
 using Elastic.Markdown.Exporters;
 using Elastic.Markdown.IO;
@@ -44,8 +46,13 @@ public async Task<CodexBuildResult> BuildAll(
 		IReadOnlySet<Exporter>? exporters = null)
 	{
 		var outputDir = context.OutputDirectory;
-		if (!outputDir.Exists)
-			outputDir.Create();
+		if (outputDir.Exists)
+		{
+			_logger.LogInformation("Cleaning target output directory: {Directory}", outputDir.FullName);
+			outputDir.Delete(true);
+		}
+
+		outputDir.Create();
 
 		_logger.LogInformation("Building {Count} documentation sets to {Directory}",
 			cloneResult.Checkouts.Count, outputDir.FullName);
@@ -97,11 +104,14 @@ public async Task<CodexBuildResult> BuildAll(
 			await Task.WhenAll(stopTasks);
 		}
 
-		// Phase 4: Generate codex landing and category pages
+		// Phase 4: Generate codex landing and group pages
+		CodexGenerator? codexGenerator = null;
 		if (buildContexts.Count > 0)
-			await GenerateCodexPages(context, buildContexts[0].BuildContext, codexNavigation, ctx);
+		{
+			codexGenerator = await GenerateCodexPages(context, buildContexts[0].BuildContext, codexNavigation, ctx);
+		}
 
-		return new CodexBuildResult(codexNavigation, buildContexts.Select(b => b.DocumentationSet).ToList());
+		return new CodexBuildResult(codexNavigation, buildContexts.Select(b => b.DocumentationSet).ToList(), codexGenerator);
 	}
 
 	private async Task<CodexDocumentationSetBuildContext?> LoadDocumentationSet(
@@ -187,13 +197,16 @@ private async Task BuildDocumentationSet(
 
 		try
 		{
+			var reference = buildContext.Checkout.Reference;
+			var codexBreadcrumbs = ResolveCodexBreadcrumbs(context, reference);
+
 			_ = await isolatedBuildService.BuildDocumentationSet(
 				buildContext.DocumentationSet,
 				null, // Use doc set's navigation for traversal
 				null, // Use default navigation HTML writer (doc set's navigation)
 				ExportOptions.Default,
 				sharedExporters,
-				pageViewFactory: new CodexPageViewFactory(context.Configuration.Title),
+				pageViewFactory: new CodexPageViewFactory(context.Configuration.Title, codexBreadcrumbs),
 				ctx);
 		}
 		catch (Exception ex)
@@ -204,7 +217,27 @@ private async Task BuildDocumentationSet(
 		}
 	}
 
-	private async Task GenerateCodexPages(
+	private static IReadOnlyList<CodexBreadcrumb> ResolveCodexBreadcrumbs(
+		CodexContext context,
+		CodexDocumentationSetReference reference)
+	{
+		var sitePrefix = context.Configuration.SitePrefix?.Trim('/') ?? "";
+		var repoName = reference.ResolvedRepoName;
+		var groupId = reference.Group;
+		var homeUrl = string.IsNullOrEmpty(sitePrefix) ? "/" : $"/{sitePrefix}/";
+		var docSetUrl = string.IsNullOrEmpty(sitePrefix) ? $"/r/{repoName}" : $"/{sitePrefix}/r/{repoName}";
+		var docSetTitle = reference.DisplayName ?? repoName;
+
+		if (string.IsNullOrEmpty(groupId))
+			return [new CodexBreadcrumb("Home", homeUrl), new CodexBreadcrumb(docSetTitle, docSetUrl)];
+
+		var groupUrl = string.IsNullOrEmpty(sitePrefix) ? $"/g/{groupId}" : $"/{sitePrefix}/g/{groupId}";
+		var groupDef = context.Configuration.Groups.FirstOrDefault(g => g.Id == groupId);
+		var groupTitle = groupDef?.Name ?? groupId;
+		return [new CodexBreadcrumb("Home", homeUrl), new CodexBreadcrumb(groupTitle, groupUrl), new CodexBreadcrumb(docSetTitle, docSetUrl)];
+	}
+
+	private async Task<CodexGenerator> GenerateCodexPages(
 		CodexContext context,
 		BuildContext docSetBuildContext,
 		CodexNavigation codexNavigation,
@@ -230,6 +263,7 @@ private async Task GenerateCodexPages(
 		// Use CodexGenerator to render the codex pages to the codex's output directory
 		var codexGenerator = new CodexGenerator(logFactory, codexBuildContext, context.OutputDirectory);
 		await codexGenerator.Generate(codexNavigation, ctx);
+		return codexGenerator;
 	}
 }
 
@@ -238,9 +272,11 @@ private async Task GenerateCodexPages(
 /// </summary>
 /// <param name="Navigation">The codex navigation structure.</param>
 /// <param name="DocumentationSets">The built documentation sets.</param>
+/// <param name="CodexGenerator">Generator for re-rendering codex pages (e.g. for dev server).</param>
 public record CodexBuildResult(
 	CodexNavigation Navigation,
-	IReadOnlyList<DocumentationSet> DocumentationSets);
+	IReadOnlyList<DocumentationSet> DocumentationSets,
+	CodexGenerator? CodexGenerator = null);
 
 /// <summary>
 /// Build context for a single documentation set within the codex.

src/Elastic.Codex/Category/CategoryView.cshtml

@@ -46,7 +46,7 @@ public abstract class CodexViewModel(CodexRenderContext context)
 	/// <summary>
 	/// Creates the global layout model for the page.
 	/// </summary>
-	public GlobalLayoutViewModel CreateGlobalLayoutModel()
+	public GlobalLayoutViewModel CreateGlobalLayoutModel(IReadOnlyList<CodexBreadcrumb>? codexBreadcrumbs = null)
 	{
 		var rootPath = BuildContext.SiteRootPath ?? GetDefaultRootPath(BuildContext.UrlPathPrefix);
 		return new()
@@ -66,7 +66,8 @@ public GlobalLayoutViewModel CreateGlobalLayoutModel()
 			Optimizely = new OptimizelyConfiguration(),
 			Features = new FeatureFlags([]),
 			StaticFileContentHashProvider = StaticFileContentHashProvider,
-			BuildType = BuildContext.BuildType
+			BuildType = BuildContext.BuildType,
+			CodexBreadcrumbs = codexBreadcrumbs
 		};
 	}
 

src/Elastic.Codex/Category/CategoryViewModel.cs

@@ -1,30 +1,32 @@
 @inherits RazorSliceHttpResult<Elastic.Codex.Group.GroupLandingViewModel>
+@using System.Linq
 @using Elastic.Codex.Group
+@using Elastic.Codex.Landing
 @using Elastic.Codex.Navigation
-@implements IUsesLayout<Elastic.Codex._Layout, GlobalLayoutViewModel>
+@implements IUsesLayout<Elastic.Codex._GroupLayout, GlobalLayoutViewModel>
 @functions {
-	public GlobalLayoutViewModel LayoutModel => Model.CreateGlobalLayoutModel();
+	public GlobalLayoutViewModel LayoutModel => Model.CreateGlobalLayoutModel(
+		codexBreadcrumbs: [new CodexBreadcrumb("Home", Model.BuildContext.SiteRootPath ?? "/"), new CodexBreadcrumb(Model.Group.DisplayTitle, Model.Group.Url)]);
 }
-<section id="elastic-docs-v3" class="codex-group-page">
-	<div class="codex-header py-8">
-		<h1 class="text-3xl font-bold mb-4">@Model.Group.DisplayTitle</h1>
-		<p class="text-gray-60">Documentation sets in this group</p>
+<section id="elastic-docs-v3" class="codex-landing min-h-screen">
+	<div class="pt-8 max-w-7xl mx-auto">
+		<h1 class="text-5xl font-medium text-black">@Model.Group.DisplayTitle</h1>
+		@if (!string.IsNullOrEmpty(Model.Group.Description))
+		{
+			<p class="mt-2 text-lg text-subdued">@Model.Group.Description</p>
+		}
 	</div>
-
-	<div class="codex-grid grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 mt-8">
+	<div id="codex-grid" class="pt-8 max-w-7xl mx-auto grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
 		@foreach (var docSet in Model.DocumentationSets.OrderBy(ds => ds.Title))
 		{
-			<a href="@docSet.Url"
-			   hx-select-oob="#main-container"
-			   preload="mousedown"
-			   class="codex-card block p-6 rounded-lg border border-gray-20 hover:border-blue-40 hover:shadow-md transition-all">
-				<div class="codex-card-content">
-					<h3 class="text-xl font-medium mb-2 text-gray-80">@docSet.Title</h3>
-					<div class="codex-card-meta text-sm text-gray-50">
-						<span>@docSet.PageCount pages</span>
-					</div>
-				</div>
-			</a>
+			@(await RenderPartialAsync(_CodexCard.Create(new CodexCardModel
+			{
+				Url = docSet.Url,
+				Title = docSet.Title ?? docSet.Name,
+				Description = docSet.Description,
+				Icon = docSet.Icon,
+				PageCount = docSet.PageCount
+			})))
 		}
 	</div>
 </section>

src/Elastic.Codex/CodexViewModel.cs

@@ -0,0 +1,17 @@
+// 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
+
+namespace Elastic.Codex.Landing;
+
+/// <summary>
+/// Model for a codex landing page card (used for both group cards and docset cards).
+/// </summary>
+public record CodexCardModel
+{
+	public required string Url { get; init; }
+	public required string Title { get; init; }
+	public string? Description { get; init; }
+	public string? Icon { get; init; }
+	public int PageCount { get; init; }
+}