Add primary-nav feature (#636)

* Add latest header design and adjust pages navigation

* Fix unintended merge changes

* fix

* Pass markdownparser to directive html renderer

* Change feature flag from UpperCamelCase to kebab-case

* Update docs/_docset.yml

* Refactor feature flags

* Fix case where targetUrl is null or empty

* Revert Commands.cs

* Don't fail-fast on matrix

* Handle the case where there is no root index.md file

* Fix

* test

* ok

* fix

* Fix

---------

Co-authored-by: Martijn Laarman <[email protected]>

Author: reakaleek

.github/workflows/smoke-test.yml

@@ -7,6 +7,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix: 
         include:
           - repository: elastic/docs-content

docs/_docset.yml

@@ -9,6 +9,10 @@ subs:
   serverless-short: Serverless
   ece:   "Elastic Cloud Enterprise"
   eck:   "Elastic Cloud on Kubernetes"
+  
+features:
+  primary-nav: false
+
 toc:
   - file: index.md
   - hidden: developer-notes.md

src/Elastic.Markdown/Assets/pages-nav.ts

@@ -15,9 +15,9 @@ function scrollCurrentNaviItemIntoView(nav: HTMLElement, delay: number) {
 	const currentNavItem = $('.current', nav);
 	expandAllParents(currentNavItem);
 	setTimeout(() => {
-
 		if (currentNavItem && !isElementInViewport(currentNavItem)) {
 			currentNavItem.scrollIntoView({ behavior: 'smooth', block: 'center' });
+			window.scrollTo(0, 0);
 		}
 	}, delay);
 }
@@ -36,7 +36,7 @@ export function initNav() {
 	if (!pagesNav) {
 		return;
 	}
-	const navItems = $$('a[href="' + window.location.pathname + '"]', pagesNav);
+	const navItems = $$('a[href="' + window.location.pathname + '"], a[href="' + window.location.pathname + '/"]', pagesNav);
 	navItems.forEach(el => {
 		el.classList.add('current');
 	});

src/Elastic.Markdown/Assets/styles.css

@@ -72,16 +72,19 @@
 
 	.sidebar {
 		.sidebar-nav {
-			@apply sticky top-22 z-30 overflow-y-auto;
+			@apply sticky top-21 z-30 overflow-y-auto;
 			max-height: calc(100vh - var(--spacing) * 22);
+			scrollbar-gutter: stable;
 		}
 
 		.sidebar-link {
 			@apply
 				text-ink-light
 				hover:text-black
 				text-sm
-			    leading-[1.2em]
+				text-wrap
+				inline-block
+			    leading-[1.3em]
 			    tracking-[-0.02em];
 		}
 	}
@@ -169,7 +172,7 @@
 }
 
 #pages-nav .current {
-	@apply text-blue-elastic!;
+	@apply font-semibold text-blue-elastic!;
 }
 
 .markdown-content {

src/Elastic.Markdown/Helpers/Htmx.cs

@@ -2,9 +2,70 @@
 // 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 System.Text;
+using Elastic.Markdown.IO.Configuration;
+
 namespace Elastic.Markdown.Helpers;
 
-public class Htmx
+public static class Htmx
+{
+	public static string GetHxSelectOob(FeatureFlags features, string? pathPrefix, string currentUrl, string targetUrl)
+	{
+		HashSet<string> selectTargets =
+		[
+			"#primary-nav", "#secondary-nav", "#markdown-content", "#toc-nav", "#prev-next-nav", "#breadcrumbs"
+		];
+		if (!HasSameTopLevelGroup(pathPrefix, currentUrl, targetUrl) && features.IsPrimaryNavEnabled)
+			_ = selectTargets.Add("#pages-nav");
+		return string.Join(',', selectTargets);
+	}
+
+	public static bool HasSameTopLevelGroup(string? pathPrefix, string currentUrl, string targetUrl)
+	{
+		if (string.IsNullOrEmpty(targetUrl) || string.IsNullOrEmpty(currentUrl))
+			return false;
+		var startIndex = pathPrefix?.Length ?? 0;
+
+		if (currentUrl.Length < startIndex)
+			throw new InvalidUrlException("Current URL is not a valid URL", currentUrl, startIndex);
+
+		if (targetUrl.Length < startIndex)
+			throw new InvalidUrlException("Target URL is not a valid URL", targetUrl, startIndex);
+
+		var currentSegments = GetSegments(currentUrl[startIndex..].Trim('/'));
+		var targetSegments = GetSegments(targetUrl[startIndex..].Trim('/'));
+		return currentSegments.Length >= 1 && targetSegments.Length >= 1 && currentSegments[0] == targetSegments[0];
+	}
+
+	public static string GetPreload() => "true";
+
+	public static string GetHxSwap() => "none";
+	public static string GetHxPushUrl() => "true";
+	public static string GetHxIndicator() => "#htmx-indicator";
+
+	private static string[] GetSegments(string url) => url.Split('/');
+
+	public static string GetHxAttributes(FeatureFlags features, string? pathPrefix, string currentUrl, string targetUrl)
+	{
+
+		var attributes = new StringBuilder();
+		_ = attributes.Append($" hx-get={targetUrl}");
+		_ = attributes.Append($" hx-select-oob={GetHxSelectOob(features, pathPrefix, currentUrl, targetUrl)}");
+		_ = attributes.Append($" hx-swap={GetHxSwap()}");
+		_ = attributes.Append($" hx-push-url={GetHxPushUrl()}");
+		_ = attributes.Append($" hx-indicator={GetHxIndicator()}");
+		_ = attributes.Append($" preload={GetPreload()}");
+		return attributes.ToString();
+	}
+}
+
+
+internal sealed class InvalidUrlException : ArgumentException
 {
-	public static string GetHxSelectOob() => "#markdown-content,#toc-nav,#prev-next-nav,#breadcrumbs";
+	public InvalidUrlException(string message, string url, int startIndex)
+		: base($"{message} (Url: {url}, StartIndex: {startIndex})")
+	{
+		Data["Url"] = url;
+		Data["StartIndex"] = startIndex;
+	}
 }

src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs

@@ -31,6 +31,10 @@ public record ConfigurationFile : DocumentationFile
 	private readonly Dictionary<string, string> _substitutions = new(StringComparer.OrdinalIgnoreCase);
 	public IReadOnlyDictionary<string, string> Substitutions => _substitutions;
 
+	private readonly Dictionary<string, bool> _features = new(StringComparer.OrdinalIgnoreCase);
+	private FeatureFlags? _featureFlags;
+	public FeatureFlags Features => _featureFlags ??= new FeatureFlags(_features);
+
 	public ConfigurationFile(IFileInfo sourceFile, IDirectoryInfo rootPath, BuildContext context, int depth = 0, string parentPath = "")
 		: base(sourceFile, rootPath)
 	{
@@ -79,6 +83,9 @@ public ConfigurationFile(IFileInfo sourceFile, IDirectoryInfo rootPath, BuildCon
 
 						TableOfContents = entries;
 						break;
+					case "features":
+						_features = reader.ReadDictionary(entry.Entry).ToDictionary(k => k.Key, v => bool.Parse(v.Value), StringComparer.OrdinalIgnoreCase);
+						break;
 					case "external_hosts":
 						reader.EmitWarning($"{entry.Key} has been deprecated and will be removed", entry.Key);
 						break;
@@ -97,6 +104,8 @@ public ConfigurationFile(IFileInfo sourceFile, IDirectoryInfo rootPath, BuildCon
 		Globs = [.. ImplicitFolders.Select(f => Glob.Parse($"{f}/*.md"))];
 	}
 
+	public bool IsFeatureEnabled(string feature) => _features.TryGetValue(feature, out var enabled) && enabled;
+
 	private List<ITocItem> ReadChildren(YamlStreamReader reader, KeyValuePair<YamlNode, YamlNode> entry, string parentPath)
 	{
 		var entries = new List<ITocItem>();

src/Elastic.Markdown/IO/Configuration/FeatureFlags.cs

@@ -0,0 +1,11 @@
+// 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.Markdown.IO.Configuration;
+
+public class FeatureFlags(Dictionary<string, bool> featureFlags)
+{
+	public bool IsPrimaryNavEnabled => IsEnabled("primary-nav");
+	private bool IsEnabled(string key) => featureFlags.TryGetValue(key, out var value) && value;
+}

src/Elastic.Markdown/IO/MarkdownFile.cs

@@ -316,12 +316,21 @@ private YamlFrontMatter ReadYamlFrontMatter(string raw)
 	}
 
 
-	public static string CreateHtml(MarkdownDocument document)
+	public string CreateHtml(MarkdownDocument document)
 	{
 		//we manually render title and optionally append an applies block embedded in yaml front matter.
 		var h1 = document.Descendants<HeadingBlock>().FirstOrDefault(h => h.Level == 1);
 		if (h1 is not null)
 			_ = document.Remove(h1);
 		return document.ToHtml(MarkdownParser.Pipeline);
 	}
+
+	public static string CreateHtml(MarkdownDocument document, MarkdownParser parser)
+	{
+		//we manually render title and optionally append an applies block embedded in yaml front matter.
+		var h1 = document.Descendants<HeadingBlock>().FirstOrDefault(h => h.Level == 1);
+		if (h1 is not null)
+			_ = document.Remove(h1);
+		return document.ToHtml(parser.Pipeline);
+	}
 }

src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs

@@ -21,7 +21,7 @@ namespace Elastic.Markdown.Myst.Directives;
 /// An HTML renderer for a <see cref="DirectiveBlock"/>.
 /// </summary>
 /// <seealso cref="HtmlObjectRenderer{CustomContainer}" />
-public class DirectiveHtmlRenderer : HtmlObjectRenderer<DirectiveBlock>
+public class DirectiveHtmlRenderer(MarkdownParser markdownParser) : HtmlObjectRenderer<DirectiveBlock>
 {
 	protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlock)
 	{
@@ -62,10 +62,10 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo
 				if (includeBlock.Literal)
 					WriteLiteralIncludeBlock(renderer, includeBlock);
 				else
-					WriteIncludeBlock(renderer, includeBlock);
+					WriteIncludeBlock(renderer, includeBlock, markdownParser);
 				return;
 			case SettingsBlock settingsBlock:
-				WriteSettingsBlock(renderer, settingsBlock);
+				WriteSettingsBlock(renderer, settingsBlock, markdownParser);
 				return;
 			default:
 				// if (!string.IsNullOrEmpty(directiveBlock.Info) && !directiveBlock.Info.StartsWith('{'))
@@ -219,28 +219,24 @@ private static void WriteLiteralIncludeBlock(HtmlRenderer renderer, IncludeBlock
 		}
 	}
 
-	private static void WriteIncludeBlock(HtmlRenderer renderer, IncludeBlock block)
+	private static void WriteIncludeBlock(HtmlRenderer renderer, IncludeBlock block, MarkdownParser parser)
 	{
 		if (!block.Found || block.IncludePath is null)
 			return;
 
-		var parser = new MarkdownParser(block.Build, block.Context);
 		var snippet = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);
 		var parentPath = block.Context.MarkdownSourcePath;
 		var document = parser.ParseSnippetAsync(snippet, parentPath, block.Context.YamlFrontMatter, default).GetAwaiter().GetResult();
-		var html = document.ToHtml(MarkdownParser.Pipeline);
+		var html = document.ToHtml(parser.Pipeline);
 		_ = renderer.Write(html);
 	}
 
-	private static void WriteSettingsBlock(HtmlRenderer renderer, SettingsBlock block)
+	private static void WriteSettingsBlock(HtmlRenderer renderer, SettingsBlock block, MarkdownParser parser)
 	{
 		if (!block.Found || block.IncludePath is null)
 			return;
 
-		var parser = new MarkdownParser(block.Build, block.Context);
-
 		var file = block.Build.ReadFileSystem.FileInfo.New(block.IncludePath);
-
 		YamlSettings? settings;
 		try
 		{
@@ -264,7 +260,7 @@ private static void WriteSettingsBlock(HtmlRenderer renderer, SettingsBlock bloc
 			RenderMarkdown = s =>
 			{
 				var document = parser.ParseEmbeddedMarkdown(s, block.IncludeFrom, block.Context.YamlFrontMatter);
-				var html = document.ToHtml(MarkdownParser.Pipeline);
+				var html = document.ToHtml(parser.Pipeline);
 				return html;
 			}
 		});

src/Elastic.Markdown/Myst/Directives/DirectiveMarkdownExtension.cs

@@ -13,9 +13,9 @@ namespace Elastic.Markdown.Myst.Directives;
 
 public static class DirectiveMarkdownBuilderExtensions
 {
-	public static MarkdownPipelineBuilder UseDirectives(this MarkdownPipelineBuilder pipeline)
+	public static MarkdownPipelineBuilder UseDirectives(this MarkdownPipelineBuilder pipeline, MarkdownParser markdownParser)
 	{
-		pipeline.Extensions.AddIfNotAlready<DirectiveMarkdownExtension>();
+		pipeline.Extensions.AddIfNotAlready(new DirectiveMarkdownExtension(markdownParser));
 		return pipeline;
 	}
 }
@@ -24,7 +24,7 @@ public static MarkdownPipelineBuilder UseDirectives(this MarkdownPipelineBuilder
 /// Extension to allow custom containers.
 /// </summary>
 /// <seealso cref="IMarkdownExtension" />
-public class DirectiveMarkdownExtension : IMarkdownExtension
+public class DirectiveMarkdownExtension(MarkdownParser markdownParser) : IMarkdownExtension
 {
 	public void Setup(MarkdownPipelineBuilder pipeline)
 	{
@@ -53,7 +53,7 @@ public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)
 		if (!renderer.ObjectRenderers.Contains<DirectiveHtmlRenderer>())
 		{
 			// Must be inserted before CodeBlockRenderer
-			_ = renderer.ObjectRenderers.InsertBefore<CodeBlockRenderer>(new DirectiveHtmlRenderer());
+			_ = renderer.ObjectRenderers.InsertBefore<CodeBlockRenderer>(new DirectiveHtmlRenderer(markdownParser));
 		}
 
 		_ = renderer.ObjectRenderers.Replace<HeadingRenderer>(new SectionedHeadingRenderer());

src/Elastic.Markdown/Myst/MarkdownParser.cs

@@ -4,6 +4,7 @@
 
 using System.IO.Abstractions;
 using Cysharp.IO;
+using Elastic.Markdown.IO.Configuration;
 using Elastic.Markdown.Myst.CodeBlocks;
 using Elastic.Markdown.Myst.Comments;
 using Elastic.Markdown.Myst.Directives;
@@ -101,33 +102,33 @@ private static async Task<MarkdownDocument> ParseAsync(
 	}
 
 	// ReSharper disable once InconsistentNaming
-	private static MarkdownPipeline? MinimalPipelineCached;
-	private static MarkdownPipeline MinimalPipeline
+	private MarkdownPipeline? _minimalPipelineCached;
+	private MarkdownPipeline MinimalPipeline
 	{
 		get
 		{
-			if (MinimalPipelineCached is not null)
-				return MinimalPipelineCached;
+			if (_minimalPipelineCached is not null)
+				return _minimalPipelineCached;
 			var builder = new MarkdownPipelineBuilder()
 				.UseYamlFrontMatter()
 				.UseInlineAnchors()
 				.UseHeadingsWithSlugs()
-				.UseDirectives();
+				.UseDirectives(this);
 
 			_ = builder.BlockParsers.TryRemove<IndentedCodeBlockParser>();
-			MinimalPipelineCached = builder.Build();
-			return MinimalPipelineCached;
+			_minimalPipelineCached = builder.Build();
+			return _minimalPipelineCached;
 		}
 	}
 
 	// ReSharper disable once InconsistentNaming
-	private static MarkdownPipeline? PipelineCached;
-	public static MarkdownPipeline Pipeline
+	private MarkdownPipeline? _pipelineCached;
+	public MarkdownPipeline Pipeline
 	{
 		get
 		{
-			if (PipelineCached is not null)
-				return PipelineCached;
+			if (_pipelineCached is not null)
+				return _pipelineCached;
 
 			var builder = new MarkdownPipelineBuilder()
 				.UseInlineAnchors()
@@ -141,15 +142,15 @@ public static MarkdownPipeline Pipeline
 				.UseYamlFrontMatter()
 				.UseGridTables()
 				.UsePipeTables()
-				.UseDirectives()
+				.UseDirectives(this)
 				.UseDefinitionLists()
 				.UseEnhancedCodeBlocks()
-				.UseHtmxLinkInlineRenderer()
+				.UseHtmxLinkInlineRenderer(Build)
 				.DisableHtml()
 				.UseHardBreaks();
 			_ = builder.BlockParsers.TryRemove<IndentedCodeBlockParser>();
-			PipelineCached = builder.Build();
-			return PipelineCached;
+			_pipelineCached = builder.Build();
+			return _pipelineCached;
 		}
 	}