fix(nav-v2): resolve section roots and island back links

Register section root URLs as authoritative owners and normalize site-prefixed lookups so section landing pages keep their own sidebar. Make island back links preserve the active site prefix, including nested reference islands such as Logstash plugins.

Co-Authored-By: GPT-5.5 <noreply@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

src/Elastic.Documentation.Navigation/V2/SiteNavigationV2.cs

@@ -82,17 +82,32 @@ public SiteNavigationV2(
 	/// </summary>
 	public NavigationSection? GetSectionForUrl(string? pageUrl)
 	{
-		if (pageUrl is not null)
-		{
-			var normalized = pageUrl.TrimEnd('/');
-			if (_urlToSection.TryGetValue(normalized, out var section))
-				return section;
-			if (_urlToSection.TryGetValue(normalized + "/", out section))
-				return section;
-		}
+		if (pageUrl is not null && TryGetSectionForUrl(pageUrl, out var section))
+			return section;
 		return Sections.FirstOrDefault(s => !s.Isolated);
 	}
 
+	private bool TryGetSectionForUrl(string url, out NavigationSection section)
+	{
+		var normalized = url.TrimEnd('/');
+		if (_urlToSection.TryGetValue(normalized, out section!))
+			return true;
+		if (_urlToSection.TryGetValue(normalized + "/", out section!))
+			return true;
+
+		var prefix = Url.TrimEnd('/');
+		if (!string.IsNullOrEmpty(prefix) && normalized.StartsWith($"{prefix}/", StringComparison.OrdinalIgnoreCase))
+		{
+			var withoutPrefix = normalized[prefix.Length..];
+			if (_urlToSection.TryGetValue(withoutPrefix, out section!))
+				return true;
+			if (_urlToSection.TryGetValue(withoutPrefix + "/", out section!))
+				return true;
+		}
+
+		section = null!;
+		return false;
+	}
 	private static IReadOnlyList<NavigationSection> BuildSections(IReadOnlyList<INavigationItem> items) =>
 		items
 			.OfType<SectionNavigationNode>()
@@ -137,7 +152,10 @@ [.. islandNode.NavigationItems]
 	private void BuildUrlToSectionLookup()
 	{
 		foreach (var section in Sections)
+		{
 			CollectUrlsForSection(section.NavigationItems, section);
+			AddUrlToSection(section.Url, section, replaceExisting: true);
+		}
 	}
 
 	private void CollectUrlsForSection(IEnumerable<INavigationItem> items, NavigationSection section)
@@ -148,17 +166,40 @@ private void CollectUrlsForSection(IEnumerable<INavigationItem> items, Navigatio
 			if (item is IslandNavigationNode)
 				continue;
 
-			if (!string.IsNullOrEmpty(item.Url))
-			{
-				var normalized = item.Url.TrimEnd('/');
-				_ = _urlToSection.TryAdd(normalized, section);
-			}
+			AddUrlToSection(item.Url, section);
 
 			if (item is INodeNavigationItem<INavigationModel, INavigationItem> node)
 				CollectUrlsForSection(node.NavigationItems, section);
 		}
 	}
 
+	private void AddUrlToSection(string url, NavigationSection section, bool replaceExisting = false)
+	{
+		if (string.IsNullOrEmpty(url))
+			return;
+		AddNormalizedUrlToSection(url, section, replaceExisting);
+		if (IsExternalUrl(url))
+			return;
+		var prefix = Url.TrimEnd('/');
+		var path = url.TrimStart('/');
+		var prefixed = string.IsNullOrEmpty(path) ? prefix : $"{prefix}/{path}";
+		if (!url.Equals(prefixed, StringComparison.OrdinalIgnoreCase))
+			AddNormalizedUrlToSection(prefixed, section, replaceExisting);
+	}
+
+	private void AddNormalizedUrlToSection(string url, NavigationSection section, bool replaceExisting)
+	{
+		var normalized = url.TrimEnd('/');
+		if (replaceExisting)
+			_urlToSection[normalized] = section;
+		else
+			_ = _urlToSection.TryAdd(normalized, section);
+	}
+
+	private static bool IsExternalUrl(string url) =>
+		url.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
+		url.StartsWith("https://", StringComparison.OrdinalIgnoreCase);
+
 	private void BuildTocRootToIslandLookup()
 	{
 		foreach (var island in Islands)

src/services/Elastic.Documentation.Assembler/Navigation/GlobalNavigationHtmlWriter.cs

@@ -138,6 +138,8 @@ Cancel ctx
 				return CreateIslandResult(cachedHtml, island, navV2);
 
 			_logger.LogInformation("Rendering V2 island navigation: {IslandLabel} ({IslandId})", island.Label, island.Id);
+			var islandUrlForPrefix = island.NavigationItems.FirstOrDefault(i => !string.IsNullOrEmpty(i.Url))?.Url ?? island.Url;
+			var backArrowUrl = CombineWithSitePrefix(navV2, island.BackUrl, islandUrlForPrefix);
 
 			var wrapper = new SectionNavigationV2Wrapper(
 				new NavigationSection(island.Id, island.Label, "", false, island.NavigationItems),
@@ -157,7 +159,7 @@ Cancel ctx
 				IsNavV2 = true,
 				IsIsolatedSection = true,
 				SectionUrl = null,
-				BackArrowUrl = CombineWithSitePrefix(navV2, island.BackUrl)
+				BackArrowUrl = backArrowUrl
 			};
 
 			var html = await ((INavigationHtmlWriter)this).Render(model, ctx);
@@ -179,13 +181,31 @@ private static NavigationRenderResult CreateIslandResult(string html, Navigation
 			ActiveSectionId = island.ParentSection.Id
 		};
 
-	private static string CombineWithSitePrefix(SiteNavigation nav, string sectionUrl)
+	private static string CombineWithSitePrefix(SiteNavigation nav, string sectionUrl, string? currentUrl = null)
 	{
 		var prefix = nav.Url.TrimEnd('/');
 		var path = sectionUrl.TrimStart('/');
-		return string.IsNullOrEmpty(path) ? $"{prefix}/" : $"{prefix}/{path}";
+		if (string.IsNullOrEmpty(path))
+			return $"{prefix}/";
+		if (IsExternalUrl(sectionUrl))
+			return sectionUrl;
+		if (sectionUrl.Equals(prefix, StringComparison.OrdinalIgnoreCase) || sectionUrl.StartsWith($"{prefix}/", StringComparison.OrdinalIgnoreCase))
+			return sectionUrl;
+		if (!string.IsNullOrEmpty(currentUrl) && sectionUrl.Length > 0 && sectionUrl[0] == '/')
+		{
+			var normalizedCurrentUrl = currentUrl.TrimEnd('/');
+			var normalizedSectionPath = "/" + path.TrimEnd('/');
+			var sectionIndex = normalizedCurrentUrl.IndexOf(normalizedSectionPath, StringComparison.OrdinalIgnoreCase);
+			if (sectionIndex > 0)
+				return normalizedCurrentUrl[..sectionIndex] + "/" + path;
+		}
+		return $"{prefix}/{path}";
 	}
 
+	private static bool IsExternalUrl(string url) =>
+		url.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
+		url.StartsWith("https://", StringComparison.OrdinalIgnoreCase);
+
 	private static NavigationRenderResult CreateSectionResult(string html, NavigationSection activeSection, SiteNavigationV2 navV2) =>
 		new()
 		{