Codex URL structure and category navigation (#2624)

* Codex URL structure and category navigation

* Potential fix for pull request finding 'Dereferenced variable may be null'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Author: reakaleek

config/codex.example.yml

@@ -11,7 +11,8 @@
 # Site prefix for all codex URLs
 # All documentation sets will be served under this prefix
 # e.g., /internal-docs, /dev-docs, /docs
-site_prefix: /internal-docs
+# Set to "/" or omit for no prefix (site hosted at root, e.g., codex.elastic.dev)
+site_prefix: /
 
 # Title displayed on the codex index page
 title: "Elastic's Internal Dev Docs"
@@ -40,13 +41,27 @@ documentation_sets:
     display_name: "Content Architecture"
     icon: architecture
 
-  # Benchmarking documentation in observability category
+  # Observability group (multiple members)
+  - name: docs-eng-team
+    branch: feature/test
+    category: docs
+    repo_name: docs-eng-team
+    display_name: "Docs Engineering"
+    icon: documentation
+
   - name: docs-eng-team
     branch: main
     category: observability
-    repo_name: benchmarking
-    display_name: "Benchmarking Elasticsearch"
-    icon: benchmark
+    repo_name: uptime-docs
+    display_name: "Uptime Monitoring"
+    icon: observability
+
+  - name: docs-eng-team
+    branch: main
+    category: observability
+    repo_name: apm-agent-docs
+    display_name: "APM Agent"
+    icon: apm
 
   # Migration Guide in tooling category
   - name: docs-eng-team
@@ -96,9 +111,10 @@ documentation_sets:
 #   Defaults to "docs".
 #
 # category (optional):
-#   Group documentation sets under a category.
-#   Creates URL structure: /{site_prefix}/{category}/{repo_name}/
-#   If not specified, URL is: /{site_prefix}/{repo_name}/
+#   Group documentation sets under a category (group).
+#   Repos use stable URLs: /r/{repo_name}/ (or /{site_prefix}/r/{repo_name}/ with prefix)
+#   Group landing: /g/{category}/ (or /{site_prefix}/g/{category}/ with prefix)
+#   Group membership only affects which sidebar navigation is shown, not the URL.
 #
 # repo_name (optional):
 #   Override the name used for checkout directories and URL paths.

src/Elastic.Codex/Building/CodexBuildService.cs

@@ -69,7 +69,7 @@ public async Task<CodexBuildResult> BuildAll(
 		foreach (var buildContext in buildContexts)
 			await BuildDocumentationSet(context, buildContext, ctx);
 
-		// Phase 4: Generate codex index and category pages using CodexGenerator
+		// Phase 4: Generate codex landing and category pages
 		if (buildContexts.Count > 0)
 			await GenerateCodexPages(context, buildContexts[0].BuildContext, codexNavigation, ctx);
 
@@ -86,18 +86,19 @@ public async Task<CodexBuildResult> BuildAll(
 
 		try
 		{
-			// Calculate output path based on category (using ResolvedRepoName for directory/URL paths)
-			// Include site prefix in output path so file structure matches URL structure
+			// All repos use stable /r/repoName paths (group-independent)
 			var repoName = checkout.Reference.ResolvedRepoName;
-			var sitePrefix = context.Configuration.SitePrefix.Trim('/');
-			var outputPath = string.IsNullOrEmpty(checkout.Reference.Category)
-				? fileSystem.Path.Combine(context.OutputDirectory.FullName, sitePrefix, repoName)
-				: fileSystem.Path.Combine(context.OutputDirectory.FullName, sitePrefix, checkout.Reference.Category, repoName);
+			var sitePrefix = context.Configuration.SitePrefix?.Trim('/') ?? "";
 
-			// Calculate URL path prefix
-			var pathPrefix = string.IsNullOrEmpty(checkout.Reference.Category)
-				? $"{context.Configuration.SitePrefix}/{repoName}"
-				: $"{context.Configuration.SitePrefix}/{checkout.Reference.Category}/{repoName}";
+			// Build output path: {outputDir}/{sitePrefix}/r/{repoName} or {outputDir}/r/{repoName} if no prefix
+			var outputPath = string.IsNullOrEmpty(sitePrefix)
+				? fileSystem.Path.Combine(context.OutputDirectory.FullName, "r", repoName)
+				: fileSystem.Path.Combine(context.OutputDirectory.FullName, sitePrefix, "r", repoName);
+
+			// Build URL path prefix: /r/{repoName} or /{sitePrefix}/r/{repoName}
+			var pathPrefix = string.IsNullOrEmpty(sitePrefix)
+				? $"/r/{repoName}"
+				: $"/{sitePrefix}/r/{repoName}";
 
 			// Create git checkout information
 			var git = new GitCheckoutInformation
@@ -151,8 +152,6 @@ private async Task BuildDocumentationSet(
 
 		try
 		{
-			// Use the documentation set's own navigation for traversal (file lookups, prev/next)
-			// TODO: Create a CodexNavigationHtmlWriter to render codex-wide navigation
 			_ = await isolatedBuildService.BuildDocumentationSet(
 				buildContext.DocumentationSet,
 				null, // Use doc set's navigation for traversal

src/Elastic.Codex/CodexGenerator.cs

@@ -4,7 +4,7 @@
 
 using System.IO.Abstractions;
 using System.Text.RegularExpressions;
-using Elastic.Codex.Category;
+using Elastic.Codex.Group;
 using Elastic.Codex.Landing;
 using Elastic.Codex.Navigation;
 using Elastic.Documentation.Configuration;
@@ -63,14 +63,9 @@ public async Task Generate(CodexNavigation codexNavigation, Cancel ctx = default
 		// Render the codex landing page
 		await RenderLandingPage(codexNavigation, renderContext, navigationRenderer, ctx);
 
-		// Render category pages
-		foreach (var item in codexNavigation.NavigationItems)
-		{
-			if (item is CategoryNavigation category)
-			{
-				await RenderCategoryPage(category, renderContext, navigationRenderer, ctx);
-			}
-		}
+		// Render group landing pages (/g/slug)
+		foreach (var groupNav in codexNavigation.GroupNavigations)
+			await RenderGroupLandingPage(groupNav, renderContext, navigationRenderer, ctx);
 	}
 
 	private async Task ExtractEmbeddedStaticResources(Cancel ctx)
@@ -138,42 +133,40 @@ private async Task RenderLandingPage(
 
 		await using var stream = _writeFileSystem.FileStream.New(outputFile.FullName, FileMode.Create);
 		await slice.RenderAsync(stream, cancellationToken: ctx);
-
-
 		_logger.LogDebug("Generated codex landing page: {Path}", outputFile.FullName);
 	}
 
-	private async Task RenderCategoryPage(
-		CategoryNavigation category,
+	private async Task RenderGroupLandingPage(
+		GroupNavigation groupNav,
 		CodexRenderContext renderContext,
 		CodexNavigationHtmlWriter navigationRenderer,
 		CancellationToken ctx)
 	{
 		var navigationRenderResult = await navigationRenderer.RenderNavigation(
-			category.NavigationRoot,
-			category.Index,
+			groupNav,
+			groupNav.Index,
 			ctx);
 
 		renderContext = renderContext with
 		{
-			CurrentNavigation = category.Index,
+			CurrentNavigation = groupNav.Index,
 			NavigationHtml = navigationRenderResult.Html
 		};
 
-		var viewModel = new CategoryViewModel(renderContext)
+		var viewModel = new GroupLandingViewModel(renderContext)
 		{
-			Category = category
+			Group = groupNav
 		};
 
-		var outputFile = GetOutputFile(category.Url);
+		var outputFile = GetOutputFile(groupNav.Url);
 		if (!outputFile.Directory!.Exists)
 			outputFile.Directory.Create();
 
 		await using var stream = _writeFileSystem.FileStream.New(outputFile.FullName, FileMode.Create);
-		var slice = CategoryView.Create(viewModel);
+		var slice = GroupLandingView.Create(viewModel);
 		await slice.RenderAsync(stream, cancellationToken: ctx);
 
-		_logger.LogDebug("Generated category page: {Path}", outputFile.FullName);
+		_logger.LogDebug("Generated group landing page: {Path}", outputFile.FullName);
 	}
 
 	private IFileInfo GetOutputFile(string url)

src/Elastic.Codex/Group/GroupLandingView.cshtml

@@ -0,0 +1,30 @@
+@inherits RazorSliceHttpResult<Elastic.Codex.Group.GroupLandingViewModel>
+@using Elastic.Codex.Group
+@using Elastic.Codex.Navigation
+@implements IUsesLayout<Elastic.Codex._Layout, GlobalLayoutViewModel>
+@functions {
+	public GlobalLayoutViewModel LayoutModel => Model.CreateGlobalLayoutModel();
+}
+<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>
+	</div>
+
+	<div class="codex-grid grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 mt-8">
+		@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>
+		}
+	</div>
+</section>

src/Elastic.Codex/Group/GroupLandingViewModel.cs

@@ -0,0 +1,23 @@
+// 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
+
+using Elastic.Codex.Navigation;
+
+namespace Elastic.Codex.Group;
+
+/// <summary>
+/// View model for a group landing page (/g/slug) that lists only documentation sets in that group.
+/// </summary>
+public class GroupLandingViewModel(CodexRenderContext context) : CodexViewModel(context)
+{
+	/// <summary>
+	/// The group navigation (landing + repos in this group).
+	/// </summary>
+	public required GroupNavigation Group { get; init; }
+
+	/// <summary>
+	/// Documentation sets in this group (for the group landing cards).
+	/// </summary>
+	public IEnumerable<CodexDocumentationSetInfo> DocumentationSets => Group.DocumentationSetInfos;
+}