Refactor markdown and layout rendering by decoupling from GlobalLayoutViewModel. Streamline layout handling, enhance navigation item visibility logic, and rework documentation file structures for improved maintainability. (#1353)

* Refactor markdown and layout rendering by decoupling from `GlobalLayoutViewModel`. Streamline layout handling, enhance navigation item visibility logic, and rework documentation file structures for improved maintainability.

`Hidden` is a pure navigation property now as its removed from `MarkdownFile`.

`GetCurrentNavigation()` is now non nullable

* Ensure NavigationIndex is a navigation property.

* Update advertising of landing-page-path

* update landing page path output

* Add xmldocs for IsPhantom

Author: Mpdreamz

src/Elastic.ApiExplorer/Endpoints/ApiEndpoint.cs

@@ -58,10 +58,13 @@ public EndpointNavigationItem(int depth, string url, ApiEndpoint apiEndpoint, La
 	public ApiEndpoint Index { get; }
 	public string Url { get; }
 	public string NavigationTitle { get; }
+	public bool Hidden => false;
 
 	public IReadOnlyCollection<OperationNavigationItem> NavigationItems { get; set; } = [];
 
 	public INodeNavigationItem<INavigationModel, INavigationItem> NavigationRoot { get; }
 
 	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
+
+	public int NavigationIndex { get; set; }
 }

src/Elastic.ApiExplorer/Endpoints/EndpointView.cshtml

@@ -7,24 +7,15 @@
 	{
 		DocSetName = "Api Explorer",
 		Description = "",
-		Layout = null,
-		PageTocItems = [],
 		CurrentNavigationItem = Model.CurrentNavigationItem,
 		Previous = null,
 		Next = null,
 		NavigationHtml = Model.NavigationHtml,
-		LegacyPage = null,
 		UrlPathPrefix = null,
-		GithubEditUrl = null,
-		ReportIssueUrl = null,
 		AllowIndexing = false,
 		CanonicalBaseUrl = null,
 		GoogleTagManager = new GoogleTagManagerConfiguration(),
 		Features = new FeatureFlags([]),
-		Parents =
-		[
-		],
-		Products = null,
 		StaticFileContentHashProvider = Model.StaticFileContentHashProvider
 	};
 }

src/Elastic.ApiExplorer/Landing/LandingNavigationItem.cs

@@ -34,8 +34,10 @@ public class LandingNavigationItem : INodeNavigationItem<ApiLanding, EndpointNav
 	public int Depth { get; }
 	public ApiLanding Index { get; }
 	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
+	public int NavigationIndex { get; set; }
 	public IReadOnlyCollection<EndpointNavigationItem> NavigationItems { get; set; } = [];
 	public string Url { get; }
+	public bool Hidden => false;
 
 	//TODO
 	public string NavigationTitle { get; } = "API Documentation";

src/Elastic.ApiExplorer/Landing/LandingView.cshtml

@@ -7,24 +7,15 @@
 	{
 		DocSetName = "Api Explorer",
 		Description = "",
-		Layout = null,
-		PageTocItems = [],
 		CurrentNavigationItem = Model.CurrentNavigationItem,
 		Previous = null,
 		Next = null,
 		NavigationHtml = Model.NavigationHtml,
-		LegacyPage = null,
 		UrlPathPrefix = null,
-		GithubEditUrl = null,
-		ReportIssueUrl = null,
 		AllowIndexing = false,
 		CanonicalBaseUrl = null,
 		GoogleTagManager = new GoogleTagManagerConfiguration(),
 		Features = new FeatureFlags([]),
-		Parents =
-		[
-		],
-		Products = null,
 		StaticFileContentHashProvider = Model.StaticFileContentHashProvider
 	};
 }

src/Elastic.ApiExplorer/Operations/OperationNavigationItem.cs

@@ -47,8 +47,12 @@ public OperationNavigationItem(int depth, string url, ApiOperation apiOperation,
 	public int Depth { get; }
 	public ApiOperation Model { get; }
 	public string Url { get; }
+	public bool Hidden => false;
 
 	public string NavigationTitle { get; }
 
 	public INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
+
+	public int NavigationIndex { get; set; }
+
 }

src/Elastic.ApiExplorer/Operations/OperationView.cshtml

@@ -7,24 +7,15 @@
 	{
 		DocSetName = "Api Explorer",
 		Description = "",
-		Layout = null,
-		PageTocItems = [],
 		CurrentNavigationItem = Model.CurrentNavigationItem,
 		Previous = null,
 		Next = null,
 		NavigationHtml = Model.NavigationHtml,
-		LegacyPage = null,
 		UrlPathPrefix = null,
-		GithubEditUrl = null,
-		ReportIssueUrl = null,
 		AllowIndexing = false,
 		CanonicalBaseUrl = null,
 		GoogleTagManager = new GoogleTagManagerConfiguration(),
 		Features = new FeatureFlags([]),
-		Parents =
-		[
-		],
-		Products = null,
 		StaticFileContentHashProvider = Model.StaticFileContentHashProvider
 	};
 }

src/Elastic.Documentation.Configuration/TableOfContents/ITocItem.cs

@@ -22,4 +22,20 @@ public record TocReference(Uri Source, ITableOfContentsScope TableOfContentsScop
 {
 	public IReadOnlyDictionary<Uri, TocReference> TocReferences { get; } =
 		Children.OfType<TocReference>().ToDictionary(kv => kv.Source, kv => kv);
+
+	/// <summary>
+	/// A phantom table of contents is a table of contents that is not rendered in the UI but is used to generate the TOC.
+	/// This should be used sparingly and needs explicit configuration in navigation.yml.
+	/// It's typically used for container TOC that holds various other TOC's where its children are rehomed throughout the navigation.
+	/// <para>Examples of phantom toc's:</para>
+	/// <list type="">
+	///		<item> - toc: elasticsearch://reference</item>
+	///		<item> - toc: docs-content://</item>
+	/// </list>
+	/// <para>Because navigation.yml does exhaustive checks to ensure all toc.yml files are referenced, marking these containers as phantoms
+	/// ensures that these skip validation checks
+	/// </para>
+	/// </summary>
+	public bool IsPhantom { get; init; }
 }
+

src/Elastic.Documentation.Site/Layout/_Head.cshtml

@@ -1,6 +1,5 @@
 @inherits RazorSlice<Elastic.Documentation.Site.GlobalLayoutViewModel>
 @using FontPreloader = Elastic.Documentation.Site.FileProviders.FontPreloader
-<head hx-head="merge">
 	<meta charset="utf-8">
 	<title>@Model.Title</title>
 	<meta name="description" content="@Model.Description">
@@ -35,9 +34,3 @@
 	{
 		<meta property="og:url" content="@Model.CanonicalUrl" />
 	}
-	@if (!string.IsNullOrEmpty(Model.Products))
-	{	
-		<meta class="elastic" name="product_name" content="@(Model.Products)"/>
-		<meta name="DC.subject" content="@(Model.Products)"/>
-	}
-</head>

src/Elastic.Documentation.Site/Layout/_SecondaryNav.cshtml

@@ -2,7 +2,7 @@
 <nav id="secondary-nav" class="bg-grey-10 border-t-1 border-grey-20 font-sans font-semibold text-sm text-ink-light md:text-base">
 	<div class="max-w-(--max-layout-width) flex mx-auto justify-between items-center p-6">
 		<div class="flex gap-2 flex-nowrap items-center">
-			@if (Model.Layout != LayoutName.LandingPage)
+			@if (Model.RenderHamburgerIcon)
 			{
 				@* ReSharper disable once Html.IdNotResolved *@
 				<label role="button" class="md:hidden cursor-pointer" for="pages-nav-hamburger">

src/Elastic.Documentation.Site/Navigation/INavigationItem.cs

@@ -30,6 +30,10 @@ public interface INavigationItem
 	/// TODO: This should be read-only however currently needs the setter in assembler.
 	/// </remarks>
 	INodeNavigationItem<INavigationModel, INavigationItem>? Parent { get; set; }
+
+	bool Hidden { get; }
+
+	int NavigationIndex { get; set; }
 }
 
 /// Represents a leaf node in the navigation tree with associated model data.

src/Elastic.Documentation.Site/Navigation/_TocTreeNav.cshtml

@@ -5,6 +5,10 @@
 }
 @foreach (var item in Model.SubTree.NavigationItems)
 {
+	if (item.Hidden)
+	{
+		continue;
+	}
 	if (item is INodeNavigationItem<INavigationModel, INavigationItem> { NavigationItems.Count: 0, Index: not null } group)
 	{
 		<li class="flex group/li pr-8 @(isTopLevel ? "font-semibold mt-6" : "mt-4")">

src/Elastic.Documentation.Site/_GlobalLayout.cshtml

@@ -1,11 +1,10 @@
 @inherits RazorLayoutSlice<GlobalLayoutViewModel>
 <!DOCTYPE html>
 <html lang="en" class="h-screen" xmlns="http://www.w3.org/1999/html">
-@await RenderPartialAsync(_Head.Create(Model))
-
-@{
-	var layout = Model.Layout;
-}
+<head hx-head="merge">
+	@await RenderPartialAsync(_Head.Create(Model))
+	@await RenderSectionAsync(GlobalSections.Head)
+</head>
 
 <body
 	class="group/body text-ink has-[#primary-nav-hamburger:checked]:overflow-hidden"
@@ -18,38 +17,9 @@
 }
 @(await RenderPartialAsync(_Header.Create(Model)))
 <div id="main-container" class="flex flex-col items-center border-t-1 border-grey-20">
-	@switch (layout)
-	{
-		case LayoutName.NotFound:
-			await RenderPartialAsync(_NotFound.Create(Model));
-			break;
-		case LayoutName.LandingPage:
-			await RenderPartialAsync(_LandingPage.Create(Model));
-			break;
-		case LayoutName.Archive:
-			await RenderPartialAsync(_Archive.Create(Model));
-			break;
-		default:
-			await RenderBodyAsync();
-			break;
-	}
+	@(await RenderBodyAsync())
 </div>
 @await RenderPartialAsync(_Footer.Create(Model))
-@if (layout is not LayoutName.Archive)
-{
-	<aside id="dismissible-banner" class="admonition tip">
-		<div class="container flex justify-between items-center mx-auto">
-			<p>
-				Welcome to the docs for the <a class="link text-base" href="/docs/get-started/versioning-availability#find-docs-for-your-product-version">latest Elastic product versions</a>, including Elastic Stack 9.0 and Elastic Cloud Serverless.
-				To view previous versions, go to <a class="link text-base" target="_blank" href="https://elastic.co/guide">elastic.co/guide</a>.
-			</p>
-			<button id="dismissible-button">
-				<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="size-6">
-					<path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12"/>
-				</svg>
-			</button>
-		</div>
-	</aside>
-}
+@await RenderSectionAsync(GlobalSections.Footer)
 </body>
 </html>

src/Elastic.Documentation.Site/_ViewModels.cs

@@ -4,38 +4,41 @@
 
 using Elastic.Documentation.Configuration.Assembler;
 using Elastic.Documentation.Configuration.Builder;
-using Elastic.Documentation.Legacy;
 using Elastic.Documentation.Site.FileProviders;
 using Elastic.Documentation.Site.Navigation;
 
 namespace Elastic.Documentation.Site;
 
+public static class GlobalSections
+{
+	public const string Head = "head";
+	public const string Footer = "footer";
+}
+
 public class GlobalLayoutViewModel
 {
 	public required string DocSetName { get; init; }
 	public string Title { get; set; } = "Elastic Documentation";
 	public required string Description { get; init; }
-	public required LayoutName? Layout { get; init; }
 
-	public required IReadOnlyCollection<PageTocItem> PageTocItems { get; init; }
-	public required INavigationItem? CurrentNavigationItem { get; init; }
+	public required INavigationItem CurrentNavigationItem { get; init; }
 	public required INavigationItem? Previous { get; init; }
 	public required INavigationItem? Next { get; init; }
+
 	public required string NavigationHtml { get; init; }
-	public required LegacyPageMapping? LegacyPage { get; init; }
 	public required string? UrlPathPrefix { get; init; }
-	public required string? GithubEditUrl { get; init; }
-	public required string? ReportIssueUrl { get; init; }
-	public required bool AllowIndexing { get; init; }
 	public required Uri? CanonicalBaseUrl { get; init; }
-	public required GoogleTagManagerConfiguration GoogleTagManager { get; init; }
 	public string? CanonicalUrl => CanonicalBaseUrl is not null ?
 		new Uri(CanonicalBaseUrl, CurrentNavigationItem?.Url).ToString().TrimEnd('/') : null;
+
 	public required FeatureFlags Features { get; init; }
 
-	public required INavigationItem[] Parents { get; init; }
+	// TODO move to @inject
+	public required GoogleTagManagerConfiguration GoogleTagManager { get; init; }
+	public required bool AllowIndexing { get; init; }
+	public required StaticFileContentHashProvider StaticFileContentHashProvider { get; init; }
 
-	public required string? Products { get; init; }
+	public bool RenderHamburgerIcon { get; init; } = true;
 
 	public string Static(string path)
 	{
@@ -46,19 +49,10 @@ public string Static(string path)
 			: $"{UrlPathPrefix}/{staticPath}?v={contentHash}";
 	}
 
-	// TODO move to @inject
-	public required StaticFileContentHashProvider StaticFileContentHashProvider { get; init; }
-
 	public string Link(string path)
 	{
 		path = path.AsSpan().TrimStart('/').ToString();
 		return $"{UrlPathPrefix}/{path}";
 	}
 }
 
-public record PageTocItem
-{
-	public required string Heading { get; init; }
-	public required string Slug { get; init; }
-	public required int Level { get; init; }
-}

src/Elastic.Markdown/IO/DocumentationFile.cs

@@ -5,6 +5,7 @@
 using Elastic.Documentation.Site;
 using Elastic.Markdown.Myst;
 using Elastic.Markdown.Myst.FrontMatter;
+using Elastic.Markdown.Slices;
 
 namespace Elastic.Markdown.IO;