stage

Author: Mpdreamz

src/Elastic.Documentation.Navigation/Isolated/DocumentationSetNavigation.cs

@@ -393,10 +393,7 @@ int depth
 	)
 	{
 		// tocRef.Path is now the FULL path (e.g., "guides/api" or "setup/advanced") after LoadAndResolve
-		// Extract just the last segment (relative part) for the URL path prefix
 		var fullTocPath = tocRef.Path;
-		var lastSlashIndex = fullTocPath.LastIndexOf('/');
-		var relativeTocPath = lastSlashIndex >= 0 ? fullTocPath[(lastSlashIndex + 1)..] : fullTocPath;
 
 		var tocDirectory = context.ReadFileSystem.DirectoryInfo.New(
 			context.ReadFileSystem.Path.Combine(context.DocumentationSourceDirectory.FullName, fullTocPath)
@@ -405,9 +402,10 @@ int depth
 		// TODO: Add validation for TOCs with children in parent YAML
 		// This is a known limitation - TOCs should not have children defined in parent YAML
 
-		// Create a scoped path prefix for this TOC
-		var parentPrefix = homeProvider.PathPrefix.TrimEnd('/');
-		var scopedPathPrefix = string.IsNullOrEmpty(parentPrefix) ? $"/{relativeTocPath}" : $"{parentPrefix}/{relativeTocPath}";
+		// According to url-building.md line 19-21: "We are not actually changing the PathPrefix,
+		// we create the scope to be able to rehome during Assembler builds."
+		// So TOC uses the SAME PathPrefix as its parent - it only creates a scope for rehoming
+		var scopedPathPrefix = homeProvider.PathPrefix;
 
 		// Create the TOC navigation with empty children initially
 		// We use null parent temporarily - we'll set it properly at the end using the public setter
@@ -425,20 +423,25 @@ int depth
 			NavigationIndex = index
 		};
 
-		// Convert children - pass tocNavigation as parent and as HomeProvider (TOC creates new scope)
+		// Create a scoped HomeProvider for TOC children
+		// According to url-building.md: "In isolated builds the NavigationRoot is always the DocumentationSetNavigation"
+		// So we use the parent's NavigationRoot, not the TOC itself
+		var tocHomeProvider = new NavigationHomeProvider(scopedPathPrefix, homeProvider.NavigationRoot);
+
+		// Convert children - pass tocNavigation as parent and tocHomeProvider as HomeProvider (TOC creates new scope)
 		var children = new List<INavigationItem>();
 		var childIndex = 0;
 
 		// LoadAndResolve has already resolved children from the toc.yml file and prepended full paths.
-		// Children have full paths (e.g., "guides/api/reference.md"), so they should use tocNavigation as their HomeProvider
+		// Children have full paths (e.g., "guides/api/reference.md"), so they should use the TOC's scoped HomeProvider
 		foreach (var child in tocRef.Children)
 		{
 			var childNav = ConvertToNavigationItem(
 				child,
 				childIndex++,
 				context,
 				tocNavigation,
-				tocNavigation, // TOC implements INavigationHomeProvider
+				tocHomeProvider, // Use the scoped HomeProvider with correct NavigationRoot
 				depth + 1
 			);
 
@@ -476,14 +479,11 @@ int depth
 			NavigationIndex = index
 		};
 
-		// Update children to point to the final TOC navigation
-		// This includes both Parent and HomeProvider (via INavigationHomeAccessor)
+		// Update children's Parent to point to the final TOC navigation
+		// Note: We don't update HomeProvider here because children already have the correct tocHomeProvider
+		// which provides the scoped PathPrefix and correct NavigationRoot
 		foreach (var child in children)
-		{
 			child.Parent = finalTocNavigation;
-			if (child is INavigationHomeAccessor accessor)
-				accessor.HomeProvider = finalTocNavigation; // TOC implements INavigationHomeProvider
-		}
 
 		return finalTocNavigation;
 	}

src/Elastic.Documentation.Navigation/Isolated/TableOfContentsNavigation.cs

@@ -18,8 +18,6 @@ public class TableOfContentsNavigation : IRootNavigationItem<IDocumentationFile,
 	, INavigationHomeAccessor
 	, INavigationHomeProvider
 {
-	private INavigationHomeProvider? _homeProvider;
-
 	public TableOfContentsNavigation(
 		IDirectoryInfo tableOfContentsDirectory,
 		int depth,
@@ -33,7 +31,6 @@ Dictionary<Uri, INodeNavigationItem<IDocumentationFile, INavigationItem>> tocNod
 	{
 		TableOfContentsDirectory = tableOfContentsDirectory;
 		NavigationItems = navigationItems;
-		Index = this.FindIndex<IDocumentationFile>(new NotFoundModel($"{parentPath}/index.md"));
 		Parent = parent;
 		Hidden = false;
 		IsUsingNavigationDropdown = false;
@@ -43,20 +40,31 @@ Dictionary<Uri, INodeNavigationItem<IDocumentationFile, INavigationItem>> tocNod
 		ParentPath = parentPath;
 		_pathPrefix = pathPrefix;
 
+		// Initialize _homeProvider to this - it will be updated in assembler builds if needed
+		_homeProvider = this;
+
 		// Create an identifier for this TOC
 		Identifier = new Uri($"{git.RepositoryName}://{parentPath}");
 		_ = tocNodes.TryAdd(Identifier, this);
+
+		// FindIndex must be called after _homeProvider is set
+		Index = this.FindIndex<IDocumentationFile>(new NotFoundModel($"{parentPath}/index.md"));
 	}
 
 	private readonly string _pathPrefix;
 
+	/// <summary>
+	/// Internal HomeProvider - defaults to this, but can be updated in assembler builds.
+	/// </summary>
+	private INavigationHomeProvider _homeProvider { get; set; }
+
 	/// <summary>
 	/// The composed path prefix for this TOC, which is the parent's prefix + this TOC's parent path.
 	/// This is used by children to build their URLs.
 	/// Implements INavigationHomeProvider.PathPrefix
 	/// When HomeProvider is set (during assembler), this returns the external provider's PathPrefix.
 	/// </summary>
-	public string PathPrefix => _homeProvider?.PathPrefix ?? _pathPrefix;
+	public string PathPrefix => _homeProvider == this ? _pathPrefix : _homeProvider.PathPrefix;
 
 	/// <inheritdoc />
 	public string Url => Index.Url;
@@ -69,7 +77,7 @@ Dictionary<Uri, INodeNavigationItem<IDocumentationFile, INavigationItem>> tocNod
 	/// In assembler builds, this can be overridden via HomeProvider.
 	/// This satisfies both INavigationItem.NavigationRoot and INavigationHomeProvider.NavigationRoot.
 	/// </summary>
-	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot => _homeProvider?.NavigationRoot ?? this;
+	public IRootNavigationItem<INavigationModel, INavigationItem> NavigationRoot => _homeProvider == this ? this : _homeProvider.NavigationRoot;
 
 	/// <inheritdoc />
 	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
@@ -81,7 +89,7 @@ Dictionary<Uri, INodeNavigationItem<IDocumentationFile, INavigationItem>> tocNod
 	/// </summary>
 	public INavigationHomeProvider HomeProvider
 	{
-		get => _homeProvider ?? this;
+		get => _homeProvider;
 		set => _homeProvider = value;
 	}
 

tests/Navigation.Tests/Isolation/ConstructorTests.cs

@@ -85,7 +85,7 @@ public void ConstructorCreatesFileNavigationLeafFromFileRef()
 		fileNav.Url.Should().Be("/getting-started");
 		fileNav.Hidden.Should().BeFalse();
 		fileNav.NavigationRoot.Should().BeSameAs(navigation);
-		fileNav.Parent.Should().BeNull();
+		fileNav.Parent.Should().BeSameAs(navigation); // Top-level files have DocumentationSetNavigation as parent
 	}
 
 	[Fact]

tests/Navigation.Tests/Isolation/NavigationStructureTests.cs

@@ -339,12 +339,13 @@ void VisitNavigationItems(INavigationItem item)
 		var gettingStarted = setupFolder.NavigationItems.First();
 		gettingStarted.NavigationRoot.Should().BeSameAs(navigation);
 
-		// Items in advanced TOC should point to the TableOfContentsNavigation
+		// According to url-building.md: "In isolated builds the NavigationRoot is always the DocumentationSetNavigation"
+		// Items in advanced TOC should point to DocumentationSetNavigation, not the TOC
 		var advancedToc = setupFolder.NavigationItems.ElementAt(1).Should().BeOfType<TableOfContentsNavigation>().Subject;
-		advancedToc.NavigationRoot.Should().BeSameAs(advancedToc, "TableOfContentsNavigation should be its own root");
+		advancedToc.NavigationRoot.Should().BeSameAs(advancedToc, "TableOfContentsNavigation is its own root when not rehomed");
 
 		var advancedIndex = advancedToc.NavigationItems.First();
-		advancedIndex.NavigationRoot.Should().BeSameAs(advancedToc, "Items within TOC should point to the TOC as their root");
+		advancedIndex.NavigationRoot.Should().BeSameAs(navigation, "Items within TOC should point to DocumentationSetNavigation in isolated builds");
 
 		// Items in file with children should point to DocumentationSetNavigation
 		var guideFile = navigation.NavigationItems.ElementAt(2).Should().BeOfType<VirtualFileNavigation<TestDocumentationFile>>().Subject;