From a746fb29cad51d4cac866f3b465ba8064c56c40e Mon Sep 17 00:00:00 2001 From: Vlada Chirmicci Date: Fri, 31 Jul 2026 14:17:24 +0100 Subject: [PATCH 01/11] Adding another card to the Solutions and use cases grid Adding the Vector Database card for the new Serverless project type. --- .../vector-database-logo-color-64px.svg | 5 +++ .../Layout/_LandingPage.cshtml | 32 ++++++++++++------- 2 files changed, 26 insertions(+), 11 deletions(-) create mode 100644 src/Elastic.Documentation.Site/_static/vector-database-logo-color-64px.svg diff --git a/src/Elastic.Documentation.Site/_static/vector-database-logo-color-64px.svg b/src/Elastic.Documentation.Site/_static/vector-database-logo-color-64px.svg new file mode 100644 index 0000000000..4ff2638944 --- /dev/null +++ b/src/Elastic.Documentation.Site/_static/vector-database-logo-color-64px.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/src/Elastic.Markdown/Layout/_LandingPage.cshtml b/src/Elastic.Markdown/Layout/_LandingPage.cshtml index 40c333834f..7181332fd1 100644 --- a/src/Elastic.Markdown/Layout/_LandingPage.cshtml +++ b/src/Elastic.Markdown/Layout/_LandingPage.cshtml @@ -63,21 +63,31 @@ Solutions and use cases -
-
- Search logo -
+
+
+ Search logo +

Elasticsearch

-

Build powerful search and RAG applications using Elasticsearch's vector database, AI toolkit, and advanced retrieval capabilities.

+

Build search and analytics across structured data, logs, metrics, documents, and vectors as part of the broader stack.

9.0+ (latest @Model.CurrentVersion) docs Previous versions
-
- Observability logo -
+
+ Vector Database logo +
+

Vector Database

+

Build your primary workload around embeddings: semantic search, RAG, or AI retrieval, with built-in models and vector-optimized defaults.

+
+ View latest docs +
+
+
+
+ Observability logo +

Observability

Resolve problems with open, flexible, and unified observability powered by advanced machine learning and analytics.

@@ -86,9 +96,9 @@
-
- Security logo -
+
+ Security logo +

Security

Detect, investigate, and respond to threats with AI-driven security analytics to protect your organization at scale.

From 3854a16885156722b75379b1aa150a22d87e9f14 Mon Sep 17 00:00:00 2001 From: Vlada Chirmicci Date: Wed, 5 Aug 2026 10:48:29 +0100 Subject: [PATCH 02/11] Adjust link text to View (versionless) docs Discussed in https://elastic.slack.com/archives/C05PP2LEC1X/p1785503200382199?thread_ts=1785425265.209679&cid=C05PP2LEC1X --- src/Elastic.Markdown/Layout/_LandingPage.cshtml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Layout/_LandingPage.cshtml b/src/Elastic.Markdown/Layout/_LandingPage.cshtml index 7181332fd1..a3fb4844a3 100644 --- a/src/Elastic.Markdown/Layout/_LandingPage.cshtml +++ b/src/Elastic.Markdown/Layout/_LandingPage.cshtml @@ -81,7 +81,7 @@

Vector Database

Build your primary workload around embeddings: semantic search, RAG, or AI retrieval, with built-in models and vector-optimized defaults.

- View latest docs + View (versionless) docs
From a068ba3d81180c30c16b940d21a8e48ed4f18fb0 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Fri, 14 Aug 2026 11:46:20 +0200 Subject: [PATCH 03/11] Fix scoped-filesystem access-denied errors in codex builds (#3865) Co-authored-by: Claude Sonnet 4.6 (1M context) Co-authored-by: Cursor --- .../Building/CodexBuildService.cs | 71 ++++++++++++++---- src/Elastic.Codex/CodexGenerator.cs | 2 +- .../Indexing/CodexIndexService.cs | 6 +- .../FileSystems/CheckoutsFileSystem.cs | 20 ++--- .../FileSystems/DocumentationFileSystem.cs | 29 ++----- .../Extensions/IFileInfoExtensions.cs | 32 ++++++++ .../FileSystems/AssemblyWriteFileSystem.cs | 18 ++--- .../DocumentationWriteFileSystem.cs | 19 ++--- .../Exporters/LlmMarkdownExporter.cs | 12 ++- .../IsolatedBuildService.cs | 75 ------------------- .../Commands/Codex/CodexCommands.cs | 12 +-- .../Commands/Codex/CodexIndexCommand.cs | 9 +-- 12 files changed, 138 insertions(+), 167 deletions(-) diff --git a/src/Elastic.Codex/Building/CodexBuildService.cs b/src/Elastic.Codex/Building/CodexBuildService.cs index ad361ed781..534683e3a9 100644 --- a/src/Elastic.Codex/Building/CodexBuildService.cs +++ b/src/Elastic.Codex/Building/CodexBuildService.cs @@ -15,7 +15,6 @@ using Elastic.Documentation.Configuration.ReleaseNotes; using Elastic.Documentation.Diagnostics; using Elastic.Documentation.FileSystems; -using Elastic.Documentation.Isolated; using Elastic.Documentation.LinkIndex; using Elastic.Documentation.Links; using Elastic.Documentation.Links.CrossLinks; @@ -25,6 +24,7 @@ using Elastic.Documentation.Services; using Elastic.Documentation.Site; using Elastic.Documentation.Site.Navigation; +using Elastic.Markdown; using Elastic.Markdown.Exporters; using Elastic.Markdown.IO; using Microsoft.Extensions.Logging; @@ -37,8 +37,7 @@ namespace Elastic.Codex.Building; /// public class CodexBuildService( ILoggerFactory logFactory, - IConfigurationContext configurationContext, - IsolatedBuildService isolatedBuildService) : IService + IConfigurationContext configurationContext) : IService { private readonly ILogger _logger = logFactory.CreateLogger(); @@ -97,9 +96,8 @@ public async Task BuildAll( if (exporters is not null && buildContexts.Count > 0) { var firstContext = buildContexts[0].BuildContext; - firstContext.Endpoints.BuildType = "codex"; firstContext.Endpoints.Environment = environment; // from codex.yml; ensures the correct index (e.g. internal) - sharedExporters = exporters.CreateMarkdownExporters(logFactory, firstContext).ToArray(); + sharedExporters = CreateExporters(context, firstContext, exporters); var startTasks = sharedExporters.Select(async e => await e.StartAsync(ctx)); await Task.WhenAll(startTasks); } @@ -253,16 +251,37 @@ private async Task BuildDocumentationSet( try { + var docContext = buildContext.BuildContext; + var documentationSet = buildContext.DocumentationSet; var codexBreadcrumbs = ResolveCodexBreadcrumbs(context, buildContext); + var manageLifecycle = sharedExporters is null; + var allExporters = sharedExporters ?? CreateExporters(context, docContext, ExportOptions.Default); - return await isolatedBuildService.BuildDocumentationSet( - buildContext.DocumentationSet, - null, // Use doc set's navigation for traversal - null, // Use default navigation HTML writer (doc set's navigation) - ExportOptions.Default, - sharedExporters, - pageViewFactory: new CodexPageViewFactory(context.Configuration.Title, codexBreadcrumbs), - ctx); + if (manageLifecycle) + { + var startTasks = allExporters.Select(async e => await e.StartAsync(ctx)); + await Task.WhenAll(startTasks); + } + + var generator = new DocumentationGenerator( + documentationSet, + logFactory, + documentationSet, + markdownExporters: allExporters, + pageViewFactory: new CodexPageViewFactory(context.Configuration.Title, codexBreadcrumbs)); + + var result = await generator.GenerateAll(ctx); + + if (manageLifecycle) + { + var finishTasks = allExporters.Select(async e => await e.FinishExportAsync(docContext.OutputDirectory, ctx)); + _ = await Task.WhenAll(finishTasks); + + var stopTasks = allExporters.Select(async e => await e.StopAsync(ctx)); + await Task.WhenAll(stopTasks); + } + + return new BuildDocumentationSetResult(docContext.Collector.Errors == 0, result.Redirects); } catch (Exception ex) { @@ -273,6 +292,25 @@ private async Task BuildDocumentationSet( } } + /// + /// Composes markdown exporters for a codex documentation set build. The LLM exporter is special-cased + /// because it writes sibling {folder}.md files one level above a docset's own output directory — + /// out of scope for a per-docset write filesystem — so it needs the codex-wide write filesystem instead. + /// + private IMarkdownExporter[] CreateExporters(CodexContext context, BuildContext docContext, IReadOnlySet exporters) + { + docContext.Endpoints.BuildType = "codex"; + if (!exporters.Contains(Exporter.LLMText)) + return exporters.CreateMarkdownExporters(logFactory, docContext).ToArray(); + + // ExportOptions.Default is a shared static HashSet -- copy before mutating, never touch it in place. + var withoutLlm = new HashSet(exporters); + _ = withoutLlm.Remove(Exporter.LLMText); + return withoutLlm.CreateMarkdownExporters(logFactory, docContext) + .Append(new LlmMarkdownExporter(writeFileSystem: context.WriteFileSystem)) + .ToArray(); + } + private static void CollectRedirects( Dictionary allRedirects, IReadOnlyDictionary redirects, @@ -392,6 +430,13 @@ public record CodexBuildResult( IReadOnlyList DocumentationSets, CodexGenerator? CodexGenerator = null); +/// +/// Result of building a documentation set, including redirects for aggregation in the codex build. +/// +/// Whether the build completed without errors. +/// Redirect mappings from the documentation set, if available. +public record BuildDocumentationSetResult(bool Success, IReadOnlyDictionary Redirects); + /// /// Build context for a single documentation set within the codex. /// diff --git a/src/Elastic.Codex/CodexGenerator.cs b/src/Elastic.Codex/CodexGenerator.cs index a6b9948e2c..bb556deda5 100644 --- a/src/Elastic.Codex/CodexGenerator.cs +++ b/src/Elastic.Codex/CodexGenerator.cs @@ -38,7 +38,7 @@ public interface ICodexPageRenderer public class CodexGenerator(ILoggerFactory logFactory, BuildContext context, IDirectoryInfo outputDirectory) { private readonly ILogger _logger = logFactory.CreateLogger(); - private readonly IFileSystem _writeFileSystem = context.WriteFileSystem; + private readonly IFileSystem _writeFileSystem = outputDirectory.FileSystem; private readonly StaticFileContentHashProvider _contentHashProvider = new(new EmbeddedOrPhysicalFileProvider(context)); private readonly IDirectoryInfo _outputDirectory = outputDirectory; diff --git a/src/Elastic.Codex/Indexing/CodexIndexService.cs b/src/Elastic.Codex/Indexing/CodexIndexService.cs index c1235c58be..5f45c452cb 100644 --- a/src/Elastic.Codex/Indexing/CodexIndexService.cs +++ b/src/Elastic.Codex/Indexing/CodexIndexService.cs @@ -7,7 +7,6 @@ using Elastic.Codex.Sourcing; using Elastic.Documentation; using Elastic.Documentation.Configuration; -using Elastic.Documentation.Isolated; using Elastic.Documentation.Services; using Microsoft.Extensions.Logging; using Nullean.ScopedFileSystem; @@ -21,8 +20,7 @@ namespace Elastic.Codex.Indexing; /// public class CodexIndexService( ILoggerFactory logFactory, - IConfigurationContext configurationContext, - IsolatedBuildService isolatedBuildService + IConfigurationContext configurationContext ) : IService { /// @@ -39,7 +37,7 @@ public async Task Index( await ElasticsearchEndpointConfigurator.ApplyAsync(cfg, esOptions, codexContext.Collector, fileSystem, ctx); var exporters = new HashSet { Exporter.Elasticsearch }; - var buildService = new CodexBuildService(logFactory, configurationContext, isolatedBuildService); + var buildService = new CodexBuildService(logFactory, configurationContext); var result = await buildService.BuildAll(codexContext, cloneResult, fileSystem, ctx, exporters); return result.DocumentationSets.Count > 0; } diff --git a/src/Elastic.Documentation.Tooling/FileSystems/CheckoutsFileSystem.cs b/src/Elastic.Documentation.Tooling/FileSystems/CheckoutsFileSystem.cs index 448ee8cd9b..9273457705 100644 --- a/src/Elastic.Documentation.Tooling/FileSystems/CheckoutsFileSystem.cs +++ b/src/Elastic.Documentation.Tooling/FileSystems/CheckoutsFileSystem.cs @@ -48,23 +48,17 @@ private static ScopedFileSystemOptions BuildReadOptions(IDirectoryInfo root, IEn var rootPath = root.FullName; var roots = new List { rootPath }; - // AppData is disjointness-filtered too: on CI the checkouts directory lives inside AppData - // (/home/runner/.local/share/elastic/docs-builder/checkouts/...), so AppData would subsume - // root and the ScopedFileSystem constructor would throw. - var appData = Paths.ApplicationData.FullName; - if (!IsSubPath(appData, rootPath, fs) && !IsSubPath(rootPath, appData, fs)) - roots.Add(appData); + // On CI (and for codex checkouts) the checkouts directory lives inside AppData + // (e.g. /home/runner/.local/share/elastic/docs-builder/checkouts/..., or + // AppData/codex/clone/). AddDisjointRoot keeps whichever of the two is the outer + // path rather than dropping AppData outright, so sibling AppData directories (e.g. + // config-runtime) stay in scope even when root itself is nested inside AppData. + roots.AddDisjointRoot(Paths.ApplicationData.FullName, fs); if (extraRoots is not null) { foreach (var extra in extraRoots) - { - if (string.IsNullOrEmpty(extra)) - continue; - // Drop descendants of root (already covered) and ancestors (would subsume root, causing overlap). - if (!IsSubPath(extra, rootPath, fs) && !IsSubPath(rootPath, extra, fs) && !roots.Contains(extra, StringComparer.OrdinalIgnoreCase)) - roots.Add(extra); - } + roots.AddDisjointRoot(extra, fs); } return new ScopedFileSystemOptions([.. roots]) diff --git a/src/Elastic.Documentation.Tooling/FileSystems/DocumentationFileSystem.cs b/src/Elastic.Documentation.Tooling/FileSystems/DocumentationFileSystem.cs index e3738dcc8f..9ab2486fec 100644 --- a/src/Elastic.Documentation.Tooling/FileSystems/DocumentationFileSystem.cs +++ b/src/Elastic.Documentation.Tooling/FileSystems/DocumentationFileSystem.cs @@ -84,31 +84,18 @@ private static ScopedFileSystemOptions BuildReadOptions(ResolvedDocumentationPat var checkoutPath = paths.CheckoutDirectory.FullName; var roots = new List { checkoutPath }; - // AppData is disjointness-filtered: on CI each individual docset checkout lives inside AppData - // (/home/runner/.local/share/elastic/docs-builder/checkouts/current/), so AppData would - // subsume checkoutPath and trigger ValidateRootsAreDisjoint. - var appData = Configuration.Paths.ApplicationData.FullName; - if (!IDirectoryInfoExtensions.IsSubPath(appData, checkoutPath, fs) - && !IDirectoryInfoExtensions.IsSubPath(checkoutPath, appData, fs)) - { - roots.Add(appData); - } + // On CI (and for codex checkouts) the docset checkout lives inside AppData + // (e.g. /home/runner/.local/share/elastic/docs-builder/checkouts/current/, or + // AppData/codex/clone/). AddDisjointRoot keeps whichever of the two is the outer + // path rather than dropping AppData outright, so sibling AppData directories (e.g. + // config-runtime) stay in scope even when the checkout itself is nested inside AppData. + roots.AddDisjointRoot(Configuration.Paths.ApplicationData.FullName, fs); foreach (var gitDir in paths.GitDirectories) - { - if (!IDirectoryInfoExtensions.IsSubPath(gitDir, checkoutPath, fs)) - roots.Add(gitDir); - } + roots.AddDisjointRoot(gitDir, fs); foreach (var extra in paths.ExtraRoots) - { - if (!string.IsNullOrEmpty(extra) - && !IDirectoryInfoExtensions.IsSubPath(extra, checkoutPath, fs) - && !roots.Contains(extra, StringComparer.OrdinalIgnoreCase)) - { - roots.Add(extra); - } - } + roots.AddDisjointRoot(extra, fs); return new ScopedFileSystemOptions([.. roots]) { diff --git a/src/Elastic.Documentation/Extensions/IFileInfoExtensions.cs b/src/Elastic.Documentation/Extensions/IFileInfoExtensions.cs index 8985ff2a23..9ca708fddb 100644 --- a/src/Elastic.Documentation/Extensions/IFileInfoExtensions.cs +++ b/src/Elastic.Documentation/Extensions/IFileInfoExtensions.cs @@ -121,6 +121,38 @@ public static bool IsSubPathOf(this IDirectoryInfo directory, IDirectoryInfo par public static bool IsSubPath(string path, string parent, IFileSystem fs) => fs.DirectoryInfo.New(path).IsSubPathOf(fs.DirectoryInfo.New(parent)); + /// + /// Adds to for a ScopedFileSystemOptions + /// root list, collapsing overlaps instead of just skipping them. + /// + /// A naive "only add if disjoint" filter (skip whenever it nests with + /// an existing root either way) silently narrows the scope to whichever root was added first. That + /// is wrong when the existing root is the narrower one — e.g. a docset checkout cloned under AppData + /// (AppData/checkouts/<repo>): keeping only the checkout path would hide sibling AppData + /// directories like config-runtime that legitimate reads/writes still need. This instead keeps + /// whichever of the two is the outer (containing) path. + /// + /// + public static void AddDisjointRoot(this List roots, string candidate, IFileSystem fs) + { + if (string.IsNullOrEmpty(candidate)) + return; + + for (var i = 0; i < roots.Count; i++) + { + if (IsSubPath(candidate, roots[i], fs)) // candidate already covered by an existing (wider) root + return; + if (IsSubPath(roots[i], candidate, fs)) // candidate is wider; it supersedes the existing root + { + roots[i] = candidate; + return; + } + } + + if (!roots.Contains(candidate, StringComparer.OrdinalIgnoreCase)) + roots.Add(candidate); + } + /// Checks if has parent directory , defaults to OrdinalIgnoreCase comparison public static bool HasParent(this IDirectoryInfo directory, string parentName, StringComparison comparison = OrdinalIgnoreCase) { diff --git a/src/Elastic.Documentation/FileSystems/AssemblyWriteFileSystem.cs b/src/Elastic.Documentation/FileSystems/AssemblyWriteFileSystem.cs index cdf2374ed7..f2a01d093a 100644 --- a/src/Elastic.Documentation/FileSystems/AssemblyWriteFileSystem.cs +++ b/src/Elastic.Documentation/FileSystems/AssemblyWriteFileSystem.cs @@ -57,18 +57,14 @@ private static ScopedFileSystemOptions BuildOptions( var checkoutPath = checkout.FullName; var roots = new List { checkoutPath }; - // AppData is disjointness-filtered: on CI the checkouts directory lives inside AppData - // (/home/runner/.local/share/elastic/docs-builder/checkouts/...), so AppData would subsume - // checkoutPath and trigger ValidateRootsAreDisjoint. - var appData = ApplicationDataPath; - if (!IDirectoryInfoExtensions.IsSubPath(appData, checkoutPath, fs) - && !IDirectoryInfoExtensions.IsSubPath(checkoutPath, appData, fs)) - { - roots.Add(appData); - } + // On CI the checkouts directory lives inside AppData + // (/home/runner/.local/share/elastic/docs-builder/checkouts/...). AddDisjointRoot keeps + // whichever of the two is the outer path rather than dropping AppData outright, so sibling + // AppData directories stay in scope even when the checkout itself is nested inside AppData. + roots.AddDisjointRoot(ApplicationDataPath, fs); - if (output is not null && !IDirectoryInfoExtensions.IsSubPath(output.FullName, checkoutPath, fs)) - roots.Add(output.FullName); + if (output is not null) + roots.AddDisjointRoot(output.FullName, fs); // MockFileSystem hardcodes its temp path ("C:\temp" on Windows, unix-ified to "/temp/" // elsewhere) instead of calling System.IO.Path.GetTempPath(). AllowedSpecialFolder.Temp uses diff --git a/src/Elastic.Documentation/FileSystems/DocumentationWriteFileSystem.cs b/src/Elastic.Documentation/FileSystems/DocumentationWriteFileSystem.cs index 3620699bf0..3930fecac7 100644 --- a/src/Elastic.Documentation/FileSystems/DocumentationWriteFileSystem.cs +++ b/src/Elastic.Documentation/FileSystems/DocumentationWriteFileSystem.cs @@ -63,18 +63,15 @@ private static ScopedFileSystemOptions BuildOptions( var checkoutPath = checkout.FullName; var roots = new List { checkoutPath }; - // AppData is disjointness-filtered: on CI each docset checkout lives inside AppData - // (/home/runner/.local/share/elastic/docs-builder/checkouts/current/), so AppData would - // subsume checkoutPath and trigger ValidateRootsAreDisjoint. - var appData = ApplicationDataPath; - if (!IDirectoryInfoExtensions.IsSubPath(appData, checkoutPath, fs) - && !IDirectoryInfoExtensions.IsSubPath(checkoutPath, appData, fs)) - { - roots.Add(appData); - } + // On CI (and for codex checkouts) the docset checkout lives inside AppData + // (e.g. /home/runner/.local/share/elastic/docs-builder/checkouts/current/, or + // AppData/codex/clone/). AddDisjointRoot keeps whichever of the two is the outer + // path rather than dropping AppData outright, so sibling AppData directories (e.g. + // config-runtime) stay in scope even when the checkout itself is nested inside AppData. + roots.AddDisjointRoot(ApplicationDataPath, fs); - if (output is not null && !IDirectoryInfoExtensions.IsSubPath(output.FullName, checkout.FullName, fs)) - roots.Add(output.FullName); + if (output is not null) + roots.AddDisjointRoot(output.FullName, fs); // MockFileSystem hardcodes its temp path ("C:\temp" on Windows, unix-ified to "/temp/" // elsewhere) instead of calling System.IO.Path.GetTempPath(). AllowedSpecialFolder.Temp uses diff --git a/src/Elastic.Markdown/Exporters/LlmMarkdownExporter.cs b/src/Elastic.Markdown/Exporters/LlmMarkdownExporter.cs index 053f756fa0..67584f10ef 100644 --- a/src/Elastic.Markdown/Exporters/LlmMarkdownExporter.cs +++ b/src/Elastic.Markdown/Exporters/LlmMarkdownExporter.cs @@ -10,6 +10,7 @@ using Elastic.Documentation.Configuration; using Elastic.Documentation.Configuration.Inference; using Elastic.Documentation.Configuration.Products; +using Elastic.Documentation.FileSystems; using Elastic.Markdown.Helpers; using Elastic.Markdown.Myst.Components; using Elastic.Markdown.Myst.Renderers.LlmMarkdown; @@ -20,7 +21,14 @@ namespace Elastic.Markdown.Exporters; /// /// Exports markdown files as LLM-optimized CommonMark using custom renderers /// -public class LlmMarkdownExporter(bool branded = false) : IMarkdownExporter +/// Omits Elastic boilerplate from generated llms.txt content when set. +/// +/// Filesystem to write exported files to. When , falls back to the per-file +/// 's write filesystem. Codex builds inject the +/// codex-wide write filesystem here, since this exporter writes sibling {folder}.md files one +/// level above a docset's own output directory, which is out of scope for a per-docset filesystem. +/// +public class LlmMarkdownExporter(bool branded = false, DocumentationWriteFileSystem? writeFileSystem = null) : IMarkdownExporter { private const string LlmsTxtTemplate = """ @@ -87,7 +95,7 @@ private static async Task AddFileAsync(ZipArchive archive, IFileInfo file, strin public async ValueTask ExportAsync(MarkdownExportFileContext fileContext, Cancel ctx) { - var fs = fileContext.BuildContext.WriteFileSystem; + var fs = writeFileSystem ?? fileContext.BuildContext.WriteFileSystem; var llmMarkdown = ConvertToLlmMarkdown(fileContext.Document, fileContext.BuildContext); var outputFile = GetLlmOutputFile(fs, fileContext); if (outputFile.Directory is { Exists: false }) diff --git a/src/services/Elastic.Documentation.Isolated/IsolatedBuildService.cs b/src/services/Elastic.Documentation.Isolated/IsolatedBuildService.cs index 67951bf718..b492828af7 100644 --- a/src/services/Elastic.Documentation.Isolated/IsolatedBuildService.cs +++ b/src/services/Elastic.Documentation.Isolated/IsolatedBuildService.cs @@ -13,15 +13,11 @@ using Elastic.Documentation.Diagnostics; using Elastic.Documentation.FileSystems; using Elastic.Documentation.LinkIndex; -using Elastic.Documentation.Links; using Elastic.Documentation.Links.CrossLinks; -using Elastic.Documentation.Navigation; using Elastic.Documentation.Services; -using Elastic.Documentation.Site.Navigation; using Elastic.Markdown; using Elastic.Markdown.Exporters; using Elastic.Markdown.IO; -using Elastic.Markdown.Page; using Microsoft.Extensions.Logging; using Nullean.ScopedFileSystem; @@ -191,75 +187,4 @@ public async Task Build( return strict.Value ? context.Collector.Errors + context.Collector.Warnings == 0 : context.Collector.Errors == 0; } - - /// - /// Builds a pre-configured documentation set with optional injected navigation. - /// Used by portal builds where navigation spans multiple documentation sets. - /// When is provided, those exporters are used instead of - /// creating new ones, and their lifecycle (Start/Stop) is not managed by this method. - /// - public async Task BuildDocumentationSet( - DocumentationSet documentationSet, - INavigationTraversable? navigation = null, - INavigationHtmlWriter? navigationHtmlWriter = null, - IReadOnlySet? exporters = null, - IMarkdownExporter[]? externalExporters = null, - IPageViewFactory? pageViewFactory = null, - Cancel ctx = default) - { - var context = documentationSet.Context; - var manageLifecycle = externalExporters is null; - - IMarkdownExporter[] allExporters; - if (externalExporters is not null) - { - allExporters = externalExporters; - } - else - { - exporters ??= ExportOptions.Default; - context.Endpoints.BuildType = "codex"; - allExporters = exporters.CreateMarkdownExporters(logFactory, context).ToArray(); - } - - if (manageLifecycle) - { - var startTasks = allExporters.Select(async e => await e.StartAsync(ctx)); - await Task.WhenAll(startTasks); - } - - // Use the provided navigation or fall back to the doc set's own navigation - var effectiveNavigation = navigation ?? documentationSet; - - var generator = new DocumentationGenerator( - documentationSet, - logFactory, - effectiveNavigation, - navigationHtmlWriter, - null, - allExporters, - pageViewFactory: pageViewFactory); - - var result = await generator.GenerateAll(ctx); - - if (manageLifecycle) - { - var finishTasks = allExporters.Select(async e => await e.FinishExportAsync(context.OutputDirectory, ctx)); - _ = await Task.WhenAll(finishTasks); - - var stopTasks = allExporters.Select(async e => await e.StopAsync(ctx)); - await Task.WhenAll(stopTasks); - } - - _logger.LogInformation("Finished building documentation set {Name}", documentationSet.Context.Git.RepositoryName); - - return new BuildDocumentationSetResult(context.Collector.Errors == 0, result.Redirects); - } } - -/// -/// Result of building a documentation set, including redirects for aggregation in portal builds. -/// -/// Whether the build completed without errors. -/// Redirect mappings from the documentation set, if available. -public record BuildDocumentationSetResult(bool Success, IReadOnlyDictionary Redirects); diff --git a/src/tooling/docs-builder/Commands/Codex/CodexCommands.cs b/src/tooling/docs-builder/Commands/Codex/CodexCommands.cs index 1bc343111f..6432c46ddb 100644 --- a/src/tooling/docs-builder/Commands/Codex/CodexCommands.cs +++ b/src/tooling/docs-builder/Commands/Codex/CodexCommands.cs @@ -4,7 +4,6 @@ using System.ComponentModel.DataAnnotations; using System.IO.Abstractions; -using Actions.Core.Services; using Documentation.Builder.Http; using Elastic.Codex; using Elastic.Codex.Building; @@ -13,7 +12,6 @@ using Elastic.Documentation.Configuration; using Elastic.Documentation.Diagnostics; using Elastic.Documentation.FileSystems; -using Elastic.Documentation.Isolated; using Elastic.Documentation.LinkIndex; using Elastic.Documentation.Services; using Microsoft.Extensions.Logging; @@ -33,9 +31,7 @@ namespace Documentation.Builder.Commands.Codex; internal sealed class CodexCommands( ILoggerFactory logFactory, IDiagnosticsCollector collector, - IConfigurationContext configurationContext, - ICoreService githubActionsService, - IEnvironmentVariables environmentVariables + IConfigurationContext configurationContext ) { /// Clone all repositories and build the portal in one step. @@ -76,8 +72,7 @@ public async Task CloneAndBuild( return cloneResult.Checkouts.Count > 0; }); - var isolatedBuildService = new IsolatedBuildService(logFactory, configurationContext, githubActionsService, environmentVariables); - var buildService = new CodexBuildService(logFactory, configurationContext, isolatedBuildService); + var buildService = new CodexBuildService(logFactory, configurationContext); serviceInvoker.AddCommand(buildService, (codexContext, cloneResult, fs), strict, async (s, col, state, c) => { @@ -159,8 +154,7 @@ public async Task Build( return 1; } - var isolatedBuildService = new IsolatedBuildService(logFactory, configurationContext, githubActionsService, environmentVariables); - var buildService = new CodexBuildService(logFactory, configurationContext, isolatedBuildService); + var buildService = new CodexBuildService(logFactory, configurationContext); serviceInvoker.AddCommand(buildService, (codexContext, cloneResult, fs), strict, async (s, col, state, c) => { diff --git a/src/tooling/docs-builder/Commands/Codex/CodexIndexCommand.cs b/src/tooling/docs-builder/Commands/Codex/CodexIndexCommand.cs index 95cb649d94..58ebf2a72e 100644 --- a/src/tooling/docs-builder/Commands/Codex/CodexIndexCommand.cs +++ b/src/tooling/docs-builder/Commands/Codex/CodexIndexCommand.cs @@ -4,7 +4,6 @@ using System.ComponentModel.DataAnnotations; using System.IO.Abstractions; -using Actions.Core.Services; using Elastic.Codex; using Elastic.Codex.Indexing; using Elastic.Codex.Sourcing; @@ -12,7 +11,6 @@ using Elastic.Documentation.Configuration; using Elastic.Documentation.Diagnostics; using Elastic.Documentation.FileSystems; -using Elastic.Documentation.Isolated; using Elastic.Documentation.Services; using Microsoft.Extensions.Logging; using Nullean.Argh; @@ -24,9 +22,7 @@ namespace Documentation.Builder.Commands.Codex; internal sealed class CodexIndexCommand( ILoggerFactory logFactory, IDiagnosticsCollector collector, - IConfigurationContext configurationContext, - ICoreService githubActionsService, - IEnvironmentVariables environmentVariables + IConfigurationContext configurationContext ) { /// Index the built portal documentation into Elasticsearch. @@ -58,8 +54,7 @@ public async Task Index( return 1; } - var isolatedBuildService = new IsolatedBuildService(logFactory, configurationContext, githubActionsService, environmentVariables); - var service = new CodexIndexService(logFactory, configurationContext, isolatedBuildService); + var service = new CodexIndexService(logFactory, configurationContext); serviceInvoker.AddCommand(service, (codexContext, cloneResult, fs, es), static async (s, col, state, c) => await s.Index(state.codexContext, state.cloneResult, state.fs, state.es, c) From cfe75d16b80e95db7bab5e69243d22db3b019cb9 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Fri, 14 Aug 2026 12:20:30 +0200 Subject: [PATCH 04/11] Hub pages 1/4: hub page layout and the {hero} directive (#3825) * Add hub page layout and the {hero} directive Adds the first two pieces of the hub page mechanism, rebuilt on the current navigation implementation. The prototype branch is merged with nav-v2, which is out of scope, so nothing from nav-v2 ports. Adds `layout: hub`, which drops the right-rail table of contents and the previous/next navigation, keeps the left sidebar, and gives the body the full content column. Page-title detection gains two fallbacks, so a page composed only of directives still resolves a title: an H1 nested in a directive, then the first {hero} directive's :title: option. Adds {hero}, the identity band. It carries a product icon, the page title, a description, and up to three optional actions. Promotes the prototype's hub-only link validator to a shared DirectiveLinkValidator. Directive links never pass through Markdig's inline link parser, so every directive that takes a URL had invented its own handling. {page-card} moves onto the shared class and its hand-rolled copy goes. It keeps its previous contract: relative links resolve against the source file, and no file-existence check runs, because page-card links can target generated pages that have no markdown file on disk. Guards DirectiveBlockParser.TryContinue so an ancestor directive stops consuming option lines once it has opened a nested directive child. Without the guard the ancestor swallows every descendant's options and the last one wins. This affects every nested directive, so it lands with regression tests over tab sets, steppers, and dropdowns. Adds LLM markdown and plain-text renderers for {hero}. A hub page has no body prose, so without them it exports as an empty shell. The plain-text renderer feeds the search index and emits the hero title and description only. Hub pages answer generic " docs" queries. Indexing section and card titles would let a hub compete with the pages it links to on specific queries. Co-Authored-By: Claude Opus 5 * Fix hub page regressions found in the rendered output Three defects, all introduced in this branch rather than carried from the prototype. Suppress the page-level H1 and the applies-to badge on a hub page. The prototype guards both in Index.cshtml and that guard was missed, so every hub page rendered the page title twice: once from Index.cshtml, once from {hero}. This also delivers the applies-to suppression that #1386 records but the code did not do. Drop the markdown-content class from the hub article. The class was added to reach the JS hooks, but those select on the markdown-content id, not the class. typography.css is unlayered and hub.css sits in @layer components, so unlayered rules win regardless of specificity. The class made typography.css restyle the hero eyebrow as a blue underlined link and skew the icon alignment against the heading. The id stays, so hljs, smooth-scroll and toc-nav keep working. Give hero actions the same link treatment as inline links. An external action now opens in a new tab with rel="noopener noreferrer" and no preload, and an anchor action no longer preloads. Only an internal link preloads. Fix an empty href for "/index.md". Stripping the whole "/index.md" segment left an empty string rather than the site root. The example page gains three actions, one internal and two external, to demonstrate both forms. Co-Authored-By: Claude Opus 5 * Align the hero product mark with the text column The mark sat about 9px right of the eyebrow and the description below it. Two insets stacked. Each icon's viewBox carried transparent padding around the glyph, which cost 5px at the rendered size. The 48px chip then centred the 40px SVG inside itself, which cost another 4px. Crops every icon's viewBox to its glyph, so no transparent padding is left to absorb, and lets the box hug the mark instead of forcing it into a fixed square. Width now follows from the glyph's own aspect ratio. The letter fallback keeps the chip. It has no glyph to align, and the chip's own edge already lines up with the text column. Co-Authored-By: Claude Opus 5 * Make the example a docs-builder hub, and keep cross-links out of new tabs The example page was an Elasticsearch hub whose links had all been repointed at docs-builder pages, leaving an Elasticsearch name, icon, hero and headings on top of docs-builder content. It is now a docs-builder hub throughout, renamed to docs/examples/products/docs-builder.md. Its hero demonstrates all three link forms: a site-absolute path, a docs-content cross-link, and an in-page anchor. The unknown `docs-builder` icon key also exercises the single-letter fallback. Fixes a defect the cross-link uncovered. A cross-link resolves to a full URL, so the hero treated it as external and opened it in a new tab. Inline links make the opposite call, and deliberately so: a cross-link still points at documentation this site serves. DirectiveLinkValidator now records the URLs it resolved from a cross-link scheme, and the view model consults that rather than guessing from the scheme. Adds doesNotContainHtml to the authoring assertions. Co-Authored-By: Claude Opus 5 * Apply review feedback to the hero and hub layout Martijn's review on #3825 and theletterf's questions. - The hero no longer adds its own horizontal padding. The content column supplies the gutter, so the hero aligned with the sections below it only above the shared max-width. Below it the hero sat 24px further in. - Hero type moves onto the site's scale. The root font size is 14px, so values written as 16px-root arithmetic rendered around 12% small. The description in particular used a size found nowhere else on the site. - The three hero actions carry equal weight and take the secondary button treatment from the {button} directive, rather than a bespoke hero button. The option names set order, not weight. - A page with `layout: hub` and no {hero} now fails the build. The layout removes the page H1, so without a hero the page has no title at all and falls back to its file path. Co-Authored-By: Claude Opus 5 * Raise the hero eyebrow to body size Martijn's point about tiny fonts applies to every piece of hub text, not only the ones in his screenshot. The eyebrow is a reading affordance, so it takes the body size. Co-Authored-By: Claude Opus 5 * Follow the site's rule for arrows on links The site puts an arrow on two kinds of link: one that sends the reader onward out of a section, such as "View all reference docs" on the landing page, and a row that is itself the target, such as {page-card} or the previous and next footer. It marks no ordinary link and no button. The hero followed neither. Its actions are buttons, so they carried an arrow the site gives no button, and only when the target was an in-page anchor. Both are gone. The eyebrow keeps its arrow, because it sends the reader onward to the docs home. It now uses the site's glyph and hover slide through one shared `.hub-arrow` class, rather than a second arrow drawn by hand. Co-Authored-By: Claude Opus 5 * Put the hero actions on the neutral button variant #3853 added `:type: neutral` to the {button} directive, a monochrome outline for clusters where blue competes with the primary action. That is exactly what the hero needs: three actions of equal rank, none of which should claim to be the call to action. #3853 also flagged that this stack used border colours failing the 3:1 non-text contrast ratio. The eyebrow pill moves from grey-20, which reads at 1.32:1, to grey-70 at 3.31:1. The border is what identifies that control, so it has to clear the threshold. Co-Authored-By: Claude Opus 5 * Add Logstash icon to hub ProductIcons (#3843) Hub heroes fall back to initials when a product key is missing from the inline SVG map. Logstash hubs need the product mark. Co-authored-by: Claude Sonnet 4.6 (1M context) Co-authored-by: Cursor Co-authored-by: Martijn Laarman --------- Co-authored-by: Claude Opus 5 Co-authored-by: Brandon Morelli Co-authored-by: Cursor Co-authored-by: Martijn Laarman --- docs/_docset.yml | 10 + docs/examples/index.md | 11 + docs/examples/products/docs-builder.md | 12 + docs/syntax/hero.md | 64 ++++ docs/syntax/hub-pages.md | 70 +++++ .../Assets/markdown/hub.css | 170 +++++++++++ .../Assets/styles.css | 1 + src/Elastic.Markdown/IO/MarkdownFile.cs | 22 ++ src/Elastic.Markdown/MarkdownPageLayout.cs | 3 +- .../Myst/Directives/DirectiveBlockParser.cs | 10 + .../Myst/Directives/DirectiveHtmlRenderer.cs | 40 +++ .../Myst/Directives/DirectiveLinkValidator.cs | 210 +++++++++++++ .../Myst/Directives/Hub/HeroBlock.cs | 75 +++++ .../Myst/Directives/Hub/HeroView.cshtml | 51 ++++ .../Myst/Directives/Hub/HeroViewModel.cs | 55 ++++ .../Myst/Directives/Hub/ProductIcons.cs | 77 +++++ .../Myst/Directives/PageCard/PageCardBlock.cs | 33 +- .../LlmMarkdown/LlmBlockRenderers.cs | 30 ++ .../PlainText/PlainTextBlockRenderers.cs | 13 + src/Elastic.Markdown/Page/Index.cshtml | 25 +- src/Elastic.Markdown/_Layout.cshtml | 32 ++ tests/authoring/Blocks/Hub/Hero.fs | 287 ++++++++++++++++++ .../Blocks/NestedDirectiveOptions.fs | 129 ++++++++ tests/authoring/Blocks/PageCards.fs | 77 +++++ tests/authoring/Framework/HtmlAssertions.fs | 44 +++ tests/authoring/authoring.fsproj | 3 + 26 files changed, 1525 insertions(+), 29 deletions(-) create mode 100644 docs/examples/index.md create mode 100644 docs/examples/products/docs-builder.md create mode 100644 docs/syntax/hero.md create mode 100644 docs/syntax/hub-pages.md create mode 100644 src/Elastic.Documentation.Site/Assets/markdown/hub.css create mode 100644 src/Elastic.Markdown/Myst/Directives/DirectiveLinkValidator.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/HeroBlock.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/HeroView.cshtml create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/HeroViewModel.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/ProductIcons.cs create mode 100644 tests/authoring/Blocks/Hub/Hero.fs create mode 100644 tests/authoring/Blocks/NestedDirectiveOptions.fs create mode 100644 tests/authoring/Blocks/PageCards.fs diff --git a/docs/_docset.yml b/docs/_docset.yml index 6f66132a8a..a05806da81 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -120,6 +120,8 @@ toc: - file: file_inclusion.md - file: footnotes.md - file: frontmatter.md + - file: hero.md + - file: hub-pages.md - file: icons.md - file: images.md - file: videos.md @@ -141,6 +143,14 @@ toc: - file: tabs.md - file: titles.md + # Examples + - folder: examples + children: + - file: index.md + - folder: products + children: + - file: docs-builder.md + # Documentation builds - folder: documentation children: diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 0000000000..54c82639bc --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,11 @@ +# Examples + +Complete pages that show docs-builder syntax rendering in context. Each syntax page explains one directive in isolation. These pages show how directives combine into a finished page. + +Use them to check what a page type looks like before you author one, and to verify rendering changes against a realistic page rather than a fixture. + +## Hubs + +Hub pages use `layout: hub` and are composed entirely from directives. See [Hub pages](../syntax/hub-pages.md). + +- [docs-builder documentation hub](products/docs-builder.md) diff --git a/docs/examples/products/docs-builder.md b/docs/examples/products/docs-builder.md new file mode 100644 index 0000000000..283f45e46b --- /dev/null +++ b/docs/examples/products/docs-builder.md @@ -0,0 +1,12 @@ +--- +layout: hub +description: docs-builder documentation. Build, validate, and publish Elastic documentation from Markdown across many repositories. +--- + +:::{hero} +:icon: docs-builder +:title: docs-builder documentation hub +:description: The toolchain that builds Elastic's documentation. Author in Markdown, validate cross-repository links, preview locally, and publish one unified site. +:primary-action: [Install docs-builder](/getting-started/installation.md) +:secondary-action: [Elastic documentation](docs-content://get-started/index.md) +::: diff --git a/docs/syntax/hero.md b/docs/syntax/hero.md new file mode 100644 index 0000000000..75d4be1fd5 --- /dev/null +++ b/docs/syntax/hero.md @@ -0,0 +1,64 @@ +# Hero + +A full-bleed identity band with a product icon, page title, description, and up to three actions. It is designed for the [hub layout](hub-pages.md), and it works on any page. + +All hero content comes from options. The directive body is not used. + +See the [Elasticsearch documentation hub](../examples/products/docs-builder.md) for a rendered hero. + +## Basic + +```markdown +:::{hero} +:icon: elasticsearch +:title: Elasticsearch documentation hub +:description: The distributed search and analytics engine at the heart of the Elastic platform. +::: +``` + +The `:title:` option doubles as the page title, so a hub page needs no body H1. See [Page title](hub-pages.md#page-title). + +## Options + +| Option | Type | Notes | +|---|---|---| +| `:title:` | string | **Required.** Renders as the page `

` next to the icon. Also used as the document title. | +| `:description:` | inline markdown | One-line summary below the title. Supports bold, italics, and links. | +| `:icon:` | string | Product key. Resolves to an inline SVG. Known keys: `elasticsearch`, `kibana`, `observability`, `security`. An unknown key falls back to a single-letter chip. | +| `:primary-action:` | markdown link | First action. Format: `[Label](/url)` or `[Label](#anchor)`. | +| `:secondary-action:` | markdown link | Second action. | +| `:tertiary-action:` | markdown link | Third action. | + +## Actions + +Each action is a single markdown link. Actions render left to right, in the order primary, secondary, tertiary. Actions are optional. Omit them for a pure identity hero. + +The option names set the order, not the weight. All three render as neutral buttons, the monochrome variant of the [button](/syntax/buttons.md) directive. A blue variant would make each action claim to be the call to action. + +```markdown +:::{hero} +:icon: elasticsearch +:title: Elasticsearch documentation hub +:description: The distributed search and analytics engine. +:primary-action: [Install Elasticsearch](https://www.elastic.co/downloads/elasticsearch) +:secondary-action: [Get started](#get-started) +:tertiary-action: [Syntax reference](/syntax/hero.md) +::: +``` + +Actions render as buttons, and no button on the site carries an arrow. The arrow belongs to the eyebrow link, which sends the reader onward to the docs home. + +Action URLs validate at build time. Use one of these forms: + +| Form | Example | Behavior | +|---|---|---| +| In-page anchor | `#get-started` | Jumps to a section on the same page. Does not preload. | +| Site-absolute path | `/syntax/hero.md` | The markdown extension is stripped. The link preloads on hover. | +| Cross-link scheme | `docs-content://get-started/index.md` | Resolves through the link index. Not treated as external, so it does not open in a new tab. | +| External URL | `https://www.elastic.co/downloads/elasticsearch` | Opens in a new tab, with `rel="noopener noreferrer"`. Does not preload. | + +A relative path such as `foo.md` is rejected. This differs from an inline markdown link, where a relative path resolves against the source file's directory. + +## Description markup + +`:description:` is a directive option, not a body block, so it never reaches the document pipeline. It renders with the default Markdown pipeline. Basic inline markup works. Substitutions, roles, and link validation do not apply inside it. Keep the description to plain prose. diff --git a/docs/syntax/hub-pages.md b/docs/syntax/hub-pages.md new file mode 100644 index 0000000000..2fb8ab6846 --- /dev/null +++ b/docs/syntax/hub-pages.md @@ -0,0 +1,70 @@ +# Hub pages + +A hub page is a product-scoped landing page. It gives a reader one 360° view of a product across versions, deployment types, and surfaces. + +Hub pages are composed entirely from directives. There is no free-form body content. That constraint is deliberate. It lets every link validate at build time, and it keeps every hub structurally consistent whoever authors it. + +See the [Elasticsearch documentation hub](../examples/products/docs-builder.md) for a complete page. + +## Enable the layout + +Set `layout: hub` in the page frontmatter: + +```yaml +--- +layout: hub +--- +``` + +A page with `layout: hub` must contain a `{hero}` directive. The build fails without one, because the layout removes the page H1 and leaves the page with no title. + +## What the layout changes + +The hub layout differs from the default page layout in three ways: + +- The right-rail table of contents is removed. The version dropdown lives in that rail, so a hub page does not show it. +- The previous and next page navigation is removed. +- The body owns the full width of the content column, so directives can render full-bleed sections. + +The left sidebar stays. A reader can move between sibling hubs from there. + +## Page title + +A hub page has no authored H1. The page title comes from the first `{hero}` directive's `:title:` option. + +Title detection tries three sources in order: + +1. A top-level H1 in the body. +2. An H1 nested inside a directive. +3. The `:title:` option of the first `{hero}`. + +One field therefore drives both the on-page heading and the browser tab title. + +## Search + +A hub page exists to answer generic queries such as "Elasticsearch docs". Two fields carry that: + +- The `{hero}` `:title:` option, which becomes the indexed page title. +- The frontmatter `description`, which becomes the indexed description. + +Write both deliberately. The search body indexes the hero title and description only. Section and card titles stay out, so a hub does not compete with the pages it links to on specific queries. + +## Directives + +| Directive | Purpose | +|---|---| +| [`{hero}`](hero.md) | Identity band. Carries the product icon, the page title, a description, and up to three actions. | + +## Page skeleton + +```markdown +--- +layout: hub +--- + +:::{hero} +:icon: elasticsearch +:title: Elasticsearch documentation hub +:description: The distributed search and analytics engine at the heart of the Elastic platform. +::: +``` diff --git a/src/Elastic.Documentation.Site/Assets/markdown/hub.css b/src/Elastic.Documentation.Site/Assets/markdown/hub.css new file mode 100644 index 0000000000..4274fa36a5 --- /dev/null +++ b/src/Elastic.Documentation.Site/Assets/markdown/hub.css @@ -0,0 +1,170 @@ +/* + * Hub-page styling. Class names mirror the directive output: + * + * .hub-page page wrapper, set by RenderHub in _Layout.cshtml + * .hub-content article wrapper inside the content column + * .hub-hero hero section, light, with a divider below + * + * Later hub directives append their own sections to this file. + */ + +@layer components { + /* Page wrapper: full-width content. Stays white so the page reads + consistently whether the user lands via full navigation or via an + htmx-boosted swap from a regular docs page. + + The content column supplies the horizontal gutter. No hub section adds one + of its own: a section that did would inset itself alone and break alignment + with the rest below the shared max-width. */ + .hub-page .hub-content { + @apply mb-20 w-full max-w-none p-0; + } + + /* Hero ------------------------------------------------------------- */ + /* Light hero on the page background, separated from the body by a rule + (matches the redesign, no dark band). */ + .hub-hero { + background-color: transparent; + color: var(--color-ink-dark); + padding: 40px 0 28px; + margin-bottom: 44px; + border-bottom: 1px solid var(--color-grey-20); + } + .hub-hero .hub-hero-inner { + @apply mx-auto w-full max-w-5xl; + } + .hub-hero .hub-hero-eyebrow { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 10px 14px; + margin: 0 0 20px; + font-size: var(--text-base); + letter-spacing: 0.02em; + } + .hub-hero .hub-hero-eyebrow-label { + font-weight: 600; + color: var(--color-ink-light); + } + .hub-hero .hub-hero-eyebrow-link { + display: inline-flex; + align-items: center; + gap: 6px; + padding: 4px 12px; + font-weight: 600; + color: var(--color-ink-dark); + text-decoration: none; + background: var(--color-white); + /* grey-70 is the lightest token clearing the 3:1 non-text contrast ratio, which + the border needs because it is what identifies this control. Same reasoning as + the neutral button in button.css. */ + border: 1px solid var(--color-grey-70); + border-radius: 999px; + transition: + background 0.15s ease, + border-color 0.15s ease; + } + .hub-hero .hub-hero-eyebrow-link:hover, + .hub-hero .hub-hero-eyebrow-link:focus-visible { + background: var(--color-grey-10); + border-color: var(--color-ink-dark); + } + /* Shared arrow ----------------------------------------------------- + The site puts an arrow on exactly two kinds of link: one that sends the + reader onward out of a section, and a row that is itself the target. It + never marks an ordinary link, and never a button. Hub links that qualify + use this class. + + The glyph and the hover slide come from `.link-arrow` in styles.css. The + class is not reused directly because it is nested under `.link`, which + also forces a blue semibold type treatment that a pill or a card would + have to undo. */ + .hub-arrow { + flex-shrink: 0; + width: 1.25em; + height: 1.25em; + transition: transform 0.15s ease-out; + } + a:hover .hub-arrow, + a:focus-visible .hub-arrow { + transform: translateX(4px); + } + .hub-hero .hub-hero-top { + display: flex; + align-items: center; + column-gap: 14px; + margin-bottom: 16px; + } + .hub-hero .hub-hero-icon { + @apply inline-flex h-13 w-13 shrink-0 items-center justify-center rounded-xl text-2xl font-bold; + width: 48px; + height: 48px; + background-color: var(--color-grey-10); + color: var(--color-ink-dark); + } + /* The letter fallback keeps the fixed chip. A product mark does not: its box hugs + the glyph, so the mark's left edge lines up with the eyebrow and the description + below it. Each icon's viewBox is cropped to its glyph, so there is no transparent + padding left to absorb. Width follows from the glyph's own aspect ratio. */ + .hub-hero .hub-hero-icon-svg { + width: auto; + height: 40px; + background-color: transparent; + border-radius: 0; + } + .hub-hero .hub-hero-icon-svg svg { + width: auto; + height: 40px; + } + .hub-hero .hub-hero-top h1 { + font-size: var(--text-4xl); + font-weight: 700; + line-height: 1.2; + letter-spacing: -0.5px; + color: var(--color-ink-dark); + margin: 0; + } + .hub-hero .hub-hero-top h1 a.headerlink { + color: var(--color-ink-dark); + text-decoration: none; + } + .hub-hero .hub-hero-desc { + font-size: var(--text-base); + color: var(--color-ink-light); + max-width: 760px; + line-height: 1.6; + margin: 0; + } + + .hub-hero .hub-hero-actions { + display: flex; + flex-wrap: wrap; + gap: 12px; + margin-top: 24px; + } + /* The three actions carry equal weight, so they all take the neutral button + treatment from the {button} directive rather than a bespoke hero button. A blue + variant would make each one claim to be the call to action. Only the layout + properties the hero needs are set here: the type, height, colour and radius come + from `.doc-button-neutral`. */ + .hub-hero .hub-hero-action { + gap: 8px; + } + .hub-hero .hub-hero-action svg { + flex-shrink: 0; + } + + /* The arrow slides and the hero animates its hover states. Honour a reduced-motion + preference. Nothing about the resting appearance changes. */ + @media (prefers-reduced-motion: reduce) { + .hub-hero .hub-hero-eyebrow-link, + .hub-hero .hub-hero-action, + .hub-arrow { + transition: none; + } + a:hover .hub-arrow, + a:focus-visible .hub-arrow { + transform: none; + } + } +} diff --git a/src/Elastic.Documentation.Site/Assets/styles.css b/src/Elastic.Documentation.Site/Assets/styles.css index c3599fa395..373aa70ed5 100644 --- a/src/Elastic.Documentation.Site/Assets/styles.css +++ b/src/Elastic.Documentation.Site/Assets/styles.css @@ -29,6 +29,7 @@ @import './markdown/cli-modifiers.css'; @import './markdown/contributors.css'; @import './markdown/storybook.css'; +@import './markdown/hub.css'; @import './api-docs.css'; @import 'tippy.js/dist/tippy.css'; diff --git a/src/Elastic.Markdown/IO/MarkdownFile.cs b/src/Elastic.Markdown/IO/MarkdownFile.cs index 9ad3b74072..ac18e68285 100644 --- a/src/Elastic.Markdown/IO/MarkdownFile.cs +++ b/src/Elastic.Markdown/IO/MarkdownFile.cs @@ -12,6 +12,7 @@ using Elastic.Markdown.Myst; using Elastic.Markdown.Myst.Directives; using Elastic.Markdown.Myst.Directives.Changelog; +using Elastic.Markdown.Myst.Directives.Hub; using Elastic.Markdown.Myst.Directives.Include; using Elastic.Markdown.Myst.Directives.Settings; using Elastic.Markdown.Myst.Directives.Stepper; @@ -153,14 +154,35 @@ private IReadOnlyDictionary GetSubstitutions() return allProperties; } + // A page with no top-level H1 can still declare its title inside a directive, either as a + // nested H1 or as {hero}'s :title: option. Hub pages are composed purely from directives, + // so this is the only title source they have. + private static string? FindNestedTitle(MarkdownDocument document) + { + if (document.Descendants().FirstOrDefault(h => h.Level == 1)?.GetData("header") is string nestedHeading) + return nestedHeading; + + var heroTitle = document.Descendants().FirstOrDefault()?.Title; + return string.IsNullOrWhiteSpace(heroTitle) ? null : heroTitle; + } + protected void ReadDocumentInstructions(MarkdownDocument document, Func documentationFileLookup) { Title = document .FirstOrDefault(block => block is HeadingBlock { Level: 1 })? .GetData("header") as string ?? Title; + if (Title == RelativePath) + Title = FindNestedTitle(document) ?? Title; + var yamlFrontMatter = ProcessYamlFrontMatter(document); YamlFrontMatter = yamlFrontMatter; + + // The hub layout suppresses the page H1, so {hero} is the only thing that can title the + // page. Without it the page renders with no title at all and falls back to its file path. + if (yamlFrontMatter.Layout == MarkdownPageLayout.Hub && !document.Descendants().Any()) + Collector.EmitError(FilePath, "A page with `layout: hub` requires a {hero} directive. Without it the page renders without a title."); + if (yamlFrontMatter.NavigationTitle is not null) NavigationTitle = yamlFrontMatter.NavigationTitle; if (yamlFrontMatter.Description is not null) diff --git a/src/Elastic.Markdown/MarkdownPageLayout.cs b/src/Elastic.Markdown/MarkdownPageLayout.cs index 6563b2a0fc..7f80d07134 100644 --- a/src/Elastic.Markdown/MarkdownPageLayout.cs +++ b/src/Elastic.Markdown/MarkdownPageLayout.cs @@ -11,5 +11,6 @@ public enum MarkdownPageLayout [EnumMember(Value = "landing-page")] LandingPage, [EnumMember(Value = "not-found")] NotFound, [EnumMember(Value = "archive")] Archive, - [EnumMember(Value = "full-search")] FullSearch + [EnumMember(Value = "full-search")] FullSearch, + [EnumMember(Value = "hub")] Hub } diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs index 550a0f0fa1..bafdbfcbd1 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs @@ -10,6 +10,7 @@ using Elastic.Markdown.Myst.Directives.Changelog; using Elastic.Markdown.Myst.Directives.CliModifiers; using Elastic.Markdown.Myst.Directives.CsvInclude; +using Elastic.Markdown.Myst.Directives.Hub; using Elastic.Markdown.Myst.Directives.Image; using Elastic.Markdown.Myst.Directives.Include; using Elastic.Markdown.Myst.Directives.Listing; @@ -137,6 +138,9 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor) if (info.IndexOf("{math}") > 0) return new MathBlock(this, context); + if (info.IndexOf("{hero}") > 0) + return new HeroBlock(this, context); + if (info.IndexOf("{agent-skill}") > 0) return new AgentSkillBlock(this, context); @@ -239,6 +243,12 @@ public override BlockState TryContinue(BlockProcessor processor, Block block) if (block is not DirectiveBlock directiveBlock) return base.TryContinue(processor, block); + // Once a directive has opened a nested directive child, an option line belongs to + // that inner directive, not this ancestor. Without this guard the ancestor swallows + // every descendant's options (last one wins) and corrupts its own. + if (directiveBlock.LastChild is DirectiveBlock) + return base.TryContinue(processor, block); + var tokens = line.ToString().Split(':', 2, RemoveEmptyEntries | TrimEntries); if (tokens.Length < 1) return base.TryContinue(processor, block); diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs index 1a97e90b4e..e0e989a156 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs @@ -16,6 +16,7 @@ using Elastic.Markdown.Myst.Directives.CliModifiers; using Elastic.Markdown.Myst.Directives.CsvInclude; using Elastic.Markdown.Myst.Directives.Dropdown; +using Elastic.Markdown.Myst.Directives.Hub; using Elastic.Markdown.Myst.Directives.Image; using Elastic.Markdown.Myst.Directives.Include; using Elastic.Markdown.Myst.Directives.Listing; @@ -104,6 +105,9 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo case MathBlock mathBlock: WriteMathBlock(renderer, mathBlock); return; + case HeroBlock heroBlock: + WriteHero(renderer, heroBlock); + return; case PageCardBlock pageCardBlock: WritePageCard(renderer, pageCardBlock); return; @@ -193,6 +197,42 @@ private static void WriteImageCarousel(HtmlRenderer renderer, ImageCarouselBlock RenderRazorSlice(slice, renderer); } + private static void WriteHero(HtmlRenderer renderer, HeroBlock block) + { + var slice = HeroView.Create(new HeroViewModel + { + DirectiveBlock = block, + IconKey = block.Icon, + IconSvg = block.IconSvg, + Title = block.Title, + DescriptionHtml = RenderInlineMarkdown(block.Description), + PrimaryActionLabel = block.PrimaryActionLabel, + PrimaryActionUrl = block.PrimaryActionUrl, + SecondaryActionLabel = block.SecondaryActionLabel, + SecondaryActionUrl = block.SecondaryActionUrl, + TertiaryActionLabel = block.TertiaryActionLabel, + TertiaryActionUrl = block.TertiaryActionUrl, + SitePathPrefix = block.Build.UrlPathPrefix + }); + RenderRazorSlice(slice, renderer); + } + + // The hero description is a directive option, not a body block, so it never reaches + // the document pipeline. Render it with the default Markdig pipeline for basic inline + // markup. Substitutions, roles, and link validation do not apply inside this option. + private static string? RenderInlineMarkdown(string? source) + { + if (string.IsNullOrWhiteSpace(source)) + return null; + + var html = Markdig.Markdown.ToHtml(source).Trim(); + const string open = "

"; + const string close = "

"; + if (html.StartsWith(open, StringComparison.Ordinal) && html.EndsWith(close, StringComparison.Ordinal)) + html = html[open.Length..^close.Length]; + return html; + } + private static void WritePageCard(HtmlRenderer renderer, PageCardBlock block) { var slice = PageCardView.Create(new PageCardViewModel diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveLinkValidator.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveLinkValidator.cs new file mode 100644 index 0000000000..09ccc14d6f --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveLinkValidator.cs @@ -0,0 +1,210 @@ +// 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.Documentation; +using Elastic.Documentation.Links; +using Elastic.Markdown.Diagnostics; + +namespace Elastic.Markdown.Myst.Directives; + +/// +/// Validates and resolves URL values supplied as directive options or in directive YAML +/// bodies. These URLs never pass through Markdig's LinkInlineParser, so without this +/// helper the normal cross-link resolution, missing-file checks, and link-index emission are +/// skipped and broken directive links ship silently. +/// +/// Returns the resolved URL (or the original on failure) so callers can write it back into +/// their own data. Errors and hints are emitted against the supplying . +/// +internal static class DirectiveLinkValidator +{ + /// + /// Resolve cross-link schemes and check that an internal path points at a real file. + /// Requires a site-absolute path, a cross-link scheme, an anchor, or an external URL. + /// Use this for directives whose links come from a YAML body or an option. + /// + public static string? ValidateAndResolve(string? url, DirectiveBlock block, ParserContext context) => + Resolve(url, block, context, allowRelative: false, checkFileExists: true); + + /// + /// Resolve cross-link schemes only, and accept a path relative to the source file. + /// Use this for directives whose links may target a generated page with no file on disk, + /// such as the CLI reference, where a file probe reports false positives. + /// + public static string? ResolveWithoutFileCheck(string? url, DirectiveBlock block, ParserContext context) => + Resolve(url, block, context, allowRelative: true, checkFileExists: false); + + private static string? Resolve(string? url, DirectiveBlock block, ParserContext context, bool allowRelative, bool checkFileExists) + { + if (string.IsNullOrWhiteSpace(url) || block.SkipValidation) + return url; + + var trimmed = url.Trim(); + if (trimmed.Length == 0 || trimmed[0] == '#') + return url; + + if (IsExternal(trimmed)) + return url; + + if (Uri.TryCreate(trimmed, UriKind.Absolute, out var uri) && CrossLinkValidator.IsCrossLink(uri)) + return ResolveCrossLink(url, uri, block, context); + + if (!trimmed.StartsWith('/') && !allowRelative) + { + block.EmitError($"Directive link `{url}` must be an absolute path starting with `/`, a cross-link scheme (for example `kibana://`), or an external URL."); + return url; + } + + if (checkFileExists) + ValidateInternal(url, block, context); + return url; + } + + /// + /// Turn a validated URL into a final href. Strips the markdown extension and applies the + /// site's URL path prefix. External URLs and anchors are returned unchanged. + /// + public static string? ToHref(string? url, string? sitePathPrefix) + { + if (string.IsNullOrEmpty(url)) + return url; + if (IsExternal(url) || url.StartsWith('#')) + return url; + + var (path, anchor) = SplitAnchor(url); + path = StripMarkdownExtension(path); + + if (string.IsNullOrEmpty(sitePathPrefix) || !path.StartsWith('/')) + return path + anchor; + + var prefix = "/" + sitePathPrefix.Trim('/'); + if (path == prefix || path.StartsWith(prefix + "/", StringComparison.OrdinalIgnoreCase)) + return path + anchor; + + return prefix + path + anchor; + } + + private const string ResolvedCrossLinksKey = "resolvedCrossLinks"; + + private static void RememberCrossLink(DirectiveBlock block, string resolved) + { + if (block.GetData(ResolvedCrossLinksKey) is not HashSet resolvedLinks) + { + resolvedLinks = []; + block.SetData(ResolvedCrossLinksKey, resolvedLinks); + } + _ = resolvedLinks.Add(resolved); + } + + /// True when came from a cross-link scheme on this block. + public static bool IsResolvedCrossLink(DirectiveBlock block, string? url) => + url is not null + && block.GetData(ResolvedCrossLinksKey) is HashSet resolvedLinks + && resolvedLinks.Contains(url, StringComparer.OrdinalIgnoreCase); + + private static bool IsExternal(string url) => + url.StartsWith("http://", StringComparison.OrdinalIgnoreCase) + || url.StartsWith("https://", StringComparison.OrdinalIgnoreCase) + || url.StartsWith("mailto:", StringComparison.OrdinalIgnoreCase); + + private static string StripMarkdownExtension(string path) + { + if (path.EndsWith("/index.md", StringComparison.OrdinalIgnoreCase)) + { + // "/index.md" is the site root, so stripping the whole segment would leave an + // empty href rather than "/". + var stripped = path[..^"/index.md".Length]; + return stripped.Length == 0 ? "/" : stripped; + } + + return path.EndsWith(".md", StringComparison.OrdinalIgnoreCase) + ? path[..^".md".Length] + : path; + } + + private static string ResolveCrossLink(string original, Uri uri, DirectiveBlock block, ParserContext context) + { + var resolver = context.CrossLinkResolver; + if (!resolver.IsDeclaredCrossLinkScheme(uri.Scheme)) + { + // Custom passthrough protocols (cursor:, vscode:) are left alone. + if (IsPassthroughCustomProtocolScheme(uri.Scheme)) + return original; + block.EmitError($"Directive link `{original}` uses cross-link scheme `{uri.Scheme}://` which is not declared under `cross_links` in docset.yml."); + return original; + } + + context.Build.Collector.EmitCrossLink(original); + if (!resolver.TryResolve(s => block.EmitError(s), uri, out var resolved)) + return original; + + // A cross-link resolves to a full URL, but it still points at documentation this site + // serves. Record it so the view model does not mistake it for an external link and open + // it in a new tab. Inline links make the same distinction. + RememberCrossLink(block, resolved.ToString()); + return resolved.ToString(); + } + + private static void ValidateInternal(string url, DirectiveBlock block, ParserContext context) + { + // In assembler and codex builds an absolute path may target a file owned by a different + // docset, because the assembled site is the union of every docset. The current docset's + // source directory is not the right basis for an existence check there, so flagging would + // produce false positives. Cross-docset references should use a cross-link scheme instead. + if (context.Build.BuildType != BuildType.Isolated) + return; + + var (path, _) = SplitAnchor(url); + if (string.IsNullOrEmpty(path) || path == "/") + return; + + var sourceDir = context.Build.DocumentationSourceDirectory.FullName; + var baseDir = path.StartsWith('/') ? sourceDir : context.MarkdownSourcePath.Directory!.FullName; + var relativeToBase = path.TrimStart('/'); + + foreach (var candidate in ProbeCandidates(relativeToBase)) + { + if (context.TryFindDocumentByRelativePath(candidate) is not null) + return; + if (context.Build.ReadFileSystem.File.Exists(Path.GetFullPath(Path.Join(baseDir, candidate)))) + return; + } + + if (TryEmitRedirectWarning(url, relativeToBase, block, context)) + return; + + block.EmitError($"Directive link `{url}` does not exist. If it was recently removed add a redirect."); + } + + // docs-builder URLs usually omit the extension, so /explore-analyze/discover may mean + // discover.md or discover/index.md. Probe as given first. + private static string[] ProbeCandidates(string path) => + path.EndsWith(".md", StringComparison.OrdinalIgnoreCase) + ? [path] + : [path, path + ".md", path.TrimEnd('/') + "/index.md"]; + + private static bool TryEmitRedirectWarning(string url, string relativeToBase, DirectiveBlock block, ParserContext context) + { + if (context.Configuration.Redirects is null + || !context.Configuration.Redirects.TryGetValue(relativeToBase, out var redirect)) + return false; + + var to = redirect.To + ?? (redirect.Many is not null + ? string.Join(", ", redirect.Many.Select(m => m.To)) + : "unknown"); + block.EmitWarning($"Directive link `{url}` has a redirect; update to: {to}"); + return true; + } + + private static (string Path, string? Anchor) SplitAnchor(string url) + { + var hash = url.IndexOf('#'); + return hash < 0 ? (url, null) : (url[..hash], url[hash..]); + } + + private static bool IsPassthroughCustomProtocolScheme(string scheme) => + scheme.Equals("cursor", StringComparison.OrdinalIgnoreCase) + || scheme.StartsWith("vscode", StringComparison.OrdinalIgnoreCase); +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/HeroBlock.cs b/src/Elastic.Markdown/Myst/Directives/Hub/HeroBlock.cs new file mode 100644 index 0000000000..913cafadb4 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/HeroBlock.cs @@ -0,0 +1,75 @@ +// 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 System.Text.RegularExpressions; +using Elastic.Markdown.Diagnostics; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// Renders a full-bleed page hero with a product icon, title, description, and +/// up to three call-to-action buttons. All content is supplied via options -- the +/// body is unused. Release cadence lives in {whats-new}. +/// +/// +/// +/// :::{hero} +/// :icon: kibana +/// :title: Kibana documentation hub +/// :description: The UI for the Elasticsearch platform. +/// :primary-action: [Get started](#get-started) +/// :secondary-action: [What's new](#whats-new) +/// :tertiary-action: [Explore Kibana docs](#explore) +/// ::: +/// +/// +public partial class HeroBlock(DirectiveBlockParser parser, ParserContext context) + : DirectiveBlock(parser, context) +{ + public override string Directive => "hero"; + + public string? Icon { get; private set; } + public string? IconSvg { get; private set; } + public string? Title { get; private set; } + public string? Description { get; private set; } + public string? PrimaryActionLabel { get; private set; } + public string? PrimaryActionUrl { get; private set; } + public string? SecondaryActionLabel { get; private set; } + public string? SecondaryActionUrl { get; private set; } + public string? TertiaryActionLabel { get; private set; } + public string? TertiaryActionUrl { get; private set; } + + public override void FinalizeAndValidate(ParserContext context) + { + Icon = Prop("icon"); + IconSvg = ProductIcons.Get(Icon); + Title = Prop("title"); + Description = Prop("description"); + (PrimaryActionLabel, PrimaryActionUrl) = ParseAction(Prop("primary-action"), context); + (SecondaryActionLabel, SecondaryActionUrl) = ParseAction(Prop("secondary-action"), context); + (TertiaryActionLabel, TertiaryActionUrl) = ParseAction(Prop("tertiary-action"), context); + + if (string.IsNullOrWhiteSpace(Title)) + this.EmitError("{hero} requires a `:title:` option."); + } + + private (string? Label, string? Url) ParseAction(string? value, ParserContext context) + { + if (string.IsNullOrWhiteSpace(value)) + return (null, null); + + var match = MarkdownLink().Match(value.Trim()); + if (!match.Success) + { + this.EmitError($"{{hero}} action `{value.Trim()}` must be a markdown link, for example `[Get started](#get-started)`."); + return (null, null); + } + + var url = DirectiveLinkValidator.ValidateAndResolve(match.Groups["url"].Value.Trim(), this, context); + return (match.Groups["label"].Value.Trim(), url); + } + + [GeneratedRegex(@"^\[(?

} + + @* Hub pages are composed entirely from directives and own the full content column. + They drop the right-rail table of contents and the prev/next nav, but keep the + pages nav so a reader can move between sibling hubs. *@ + private async Task RenderHub() + { +
+
+
+
+ @* Keeps the markdown-content id, which hljs, smooth-scroll and toc-nav select on, + but not the class. typography.css is unlayered and hub.css sits in @@layer + components, so the class would override every hub rule regardless of + specificity. Hub directives bring their own typography. *@ +
+ + @await RenderBodyAsync() +
+
+ @await RenderPartialAsync(_PagesNav.Create(Model)) +
+
+
+ } } @if (RenderHeaderAndFooter) @@ -87,6 +116,9 @@ case MarkdownPageLayout.FullSearch: await RenderPartialAsync(_FullSearch.Create(Model)); break; + case MarkdownPageLayout.Hub: + await RenderHub(); + break; default: await RenderDefault(); break; diff --git a/tests/authoring/Blocks/Hub/Hero.fs b/tests/authoring/Blocks/Hub/Hero.fs new file mode 100644 index 0000000000..252687db6c --- /dev/null +++ b/tests/authoring/Blocks/Hub/Hero.fs @@ -0,0 +1,287 @@ +// 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 +module ``AuthoringTests``.``block elements``.``hub``.``hero elements`` + +open Xunit +open authoring + +type ``hero with title only`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Elasticsearch documentation hub +::: +""" + + [] + let ``renders the title as an h1`` () = + markdown |> convertsToContainingHtml """

Elasticsearch documentation hub

""" + + [] + let ``renders the fixed eyebrow`` () = + markdown |> convertsToContainingHtml """Browse all Elastic docs""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``hero without a title`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:description: Missing the required title option. +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "{hero} requires a `:title:` option." + +type ``hero with a description`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Kibana documentation hub +:description: The UI for the **Elasticsearch** platform. +::: +""" + + [] + let ``renders inline markup in the description`` () = + markdown |> convertsToContainingHtml """Elasticsearch""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``hero with an unknown icon key`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:icon: notaproduct +:title: Something else +::: +""" + + [] + let ``falls back to a letter chip`` () = + markdown |> convertsToContainingHtml """""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``hero with anchor actions`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Elasticsearch documentation hub +:primary-action: [Get started](#get-started) +:secondary-action: [What's new](#whats-new) +::: +""" + + // Actions render as buttons, and no button on the site carries an arrow, not even + // an anchor action that jumps within the page. The assertion starts at the section, + // because the pretty-printer only matches from the outermost element of the output. + [] + let ``renders both actions as buttons without an arrow`` () = + markdown |> convertsToContainingHtml """ +
+
+
+ + Browse all Elastic docs + + +
+
+

Elasticsearch documentation hub

+
+
+ + + Get started + + + + + What's new + + +
+
+
+""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``hero with an external action`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Elasticsearch documentation hub +:primary-action: [Install Elasticsearch](https://www.elastic.co/downloads/elasticsearch) +::: +""" + + // External links follow the same rules as inline links: they open in a new tab. The + // assertion starts at the section, because the pretty-printer only matches from the + // outermost element of the directive output. It also strips `preload`, so the absence + // of preloading on an external action cannot be asserted here. + [] + let ``opens in a new tab`` () = + markdown |> convertsToContainingHtml """ +
+
+
+ + Browse all Elastic docs + + +
+
+

Elasticsearch documentation hub

+
+
+ + + Install Elasticsearch + + +
+
+
+""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``hero with an internal action`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Elasticsearch documentation hub +:primary-action: [Syntax reference](/index.md) +::: +""" + + [] + let ``strips the markdown extension and does not open a new tab`` () = + markdown |> convertsToContainingHtml """ +
+
+
+ + Browse all Elastic docs + + +
+
+

Elasticsearch documentation hub

+
+
+ + + Syntax reference + + +
+
+
+""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``hero with a relative action url`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Elasticsearch documentation hub +:primary-action: [Get started](get-started.md) +::: +""" + + [] + let ``rejects a relative path`` () = + markdown |> hasError "must be an absolute path starting with `/`" + +type ``hero with a malformed action`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: Elasticsearch documentation hub +:primary-action: Get started +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "must be a markdown link" + +type ``hero with a cross-link action`` () = + static let markdown = Setup.Markdown """ +:::{hero} +:title: docs-builder documentation hub +:primary-action: [Elastic documentation](docs-content://get-started/index.md) +::: +""" + + // A cross-link resolves to a full URL but still points at documentation this site serves, + // so it must not open in a new tab. Inline links make the same distinction. The assertion + // snapshots the section rather than looking for target="_blank" anywhere on the page, + // because site chrome carries that attribute too. + [] + let ``does not open in a new tab`` () = + markdown |> convertsToContainingHtml """ +
+
+
+ + Browse all Elastic docs + + +
+
+

docs-builder documentation hub

+
+
+ + + Elastic documentation + + +
+
+
+""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +// These two set frontmatter, so they use Setup.Document. Setup.Markdown prepends an H1, +// which would push the frontmatter into the body where it never parses. +type ``hub layout without a hero`` () = + static let markdown = Setup.Document """--- +layout: hub +--- + +Body content with no hero directive. +""" + + // The hub layout removes the page H1, so {hero} is the only thing that can title the page. + [] + let ``errors`` () = + markdown |> hasError "A page with `layout: hub` requires a {hero} directive." + +type ``hub layout with a hero`` () = + static let markdown = Setup.Document """--- +layout: hub +--- + +:::{hero} +:title: Elasticsearch documentation hub +::: +""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors diff --git a/tests/authoring/Blocks/NestedDirectiveOptions.fs b/tests/authoring/Blocks/NestedDirectiveOptions.fs new file mode 100644 index 0000000000..8427558d9c --- /dev/null +++ b/tests/authoring/Blocks/NestedDirectiveOptions.fs @@ -0,0 +1,129 @@ +// 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 +module ``AuthoringTests``.``block elements``.``nested directive options`` + +open Xunit +open authoring + +// DirectiveBlockParser.TryContinue stops an ancestor directive consuming an option line once +// it has opened a nested directive child. Without the guard the ancestor also takes every +// descendant's options, and the last one wins. +// +// No existing directive pair shares an option name, so the collision is latent for them: +// {tab-set} reads group while {tab-item} reads sync and selected, and {applies-switch} and +// {applies-item} split the same way. These tests pin that each option still reaches the block +// that declared it, which is what the guard must not break. + +type ``tab set with its own group and per-item sync`` () = + static let markdown = Setup.Markdown """ +::::{tab-set} +:group: install-method + +:::{tab-item} Local +:sync: local +local body +::: + +:::{tab-item} Container +:sync: container +container body +::: +:::: +""" + + // The group is declared on the tab-set before any child, so it still reaches the tab-set. + [] + let ``the tab set keeps its own group`` () = + markdown |> convertsToContainingRawHtml "data-sync-group=\"install-method\"" + + // Each sync reaches the item that declared it, rather than all landing on the last one. + [] + let ``the first item keeps its own sync`` () = + markdown |> convertsToContainingRawHtml "data-sync-id=\"local\"" + + [] + let ``the second item keeps its own sync`` () = + markdown |> convertsToContainingRawHtml "data-sync-id=\"container\"" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``applies switch with its own group and per-item sync`` () = + static let markdown = Setup.Markdown """ +::::{applies-switch} +:group: deployment + +:::{applies-item} serverless: ga +:sync: serverless +serverless body +::: + +:::{applies-item} stack: ga 9.0+ +:sync: self-managed +self-managed body +::: +:::: +""" + + [] + let ``the switch keeps its own group`` () = + markdown |> convertsToContainingRawHtml "data-sync-group=\"deployment\"" + + [] + let ``the first item keeps its own sync`` () = + markdown |> convertsToContainingRawHtml "data-sync-id=\"serverless\"" + + [] + let ``the second item keeps its own sync`` () = + markdown |> convertsToContainingRawHtml "data-sync-id=\"self-managed\"" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``stepper with per-step anchors`` () = + static let markdown = Setup.Markdown """ +::::{stepper} +:::{step} Install +:anchor: install-step +Install the thing. +::: +:::{step} Configure +:anchor: configure-step +Configure the thing. +::: +:::: +""" + + [] + let ``each step keeps its own anchor`` () = + markdown |> convertsToContainingRawHtml "install-step" + + [] + let ``the second step keeps its own anchor`` () = + markdown |> convertsToContainingRawHtml "configure-step" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``dropdown wrapping an admonition with its own name`` () = + static let markdown = Setup.Markdown """ +::::{dropdown} Outer summary +:open: +:::{note} +:name: inner-note +Inner content. +::: +:::: +""" + + [] + let ``the dropdown keeps its own open state`` () = + markdown |> convertsToContainingRawHtml "Outer summary" + + [] + let ``the nested admonition keeps its own name`` () = + markdown |> convertsToContainingRawHtml "inner-note" + + [] + let ``has no errors`` () = markdown |> hasNoErrors diff --git a/tests/authoring/Blocks/PageCards.fs b/tests/authoring/Blocks/PageCards.fs new file mode 100644 index 0000000000..600651afb7 --- /dev/null +++ b/tests/authoring/Blocks/PageCards.fs @@ -0,0 +1,77 @@ +// 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 +module ``AuthoringTests``.``block elements``.``page card elements`` + +open Xunit +open authoring + +// {page-card} moved onto the shared DirectiveLinkValidator. These tests pin the contract it +// had before that move: relative links resolve against the source file, and no file-existence +// check runs, because page-card links can target generated pages with no markdown on disk. + +type ``page card with a relative link`` () = + static let markdown = Setup.Markdown """ +:::{page-card} [Admonitions](admonitions.md) +Callout boxes for notes and warnings. +::: +""" + + [] + let ``resolves the link relative to the source file`` () = + markdown |> convertsToContainingHtml """ + +
+
Admonitions
+
+

Callout boxes for notes and warnings.

+
+
+ + + + +""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``page card with a dot-relative link`` () = + static let markdown = Setup.Markdown """ +:::{page-card} [Add](./add.md) +::: +""" + + // The CLI reference generates page-cards pointing at generated pages that have no markdown + // file on disk. A file-existence check here would report false positives on every one. + [] + let ``does not check that the target file exists`` () = markdown |> hasNoErrors + +type ``page card without a description`` () = + static let markdown = Setup.Markdown """ +:::{page-card} [Tables](tables.md) +::: +""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``page card with an absolute url`` () = + static let markdown = Setup.Markdown """ +:::{page-card} [Elastic](https://www.elastic.co) +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "page-card url must be a local .md path or crosslink" + +type ``page card without a markdown link`` () = + static let markdown = Setup.Markdown """ +:::{page-card} Admonitions +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "page-card requires a markdown link argument" diff --git a/tests/authoring/Framework/HtmlAssertions.fs b/tests/authoring/Framework/HtmlAssertions.fs index eaa648d322..2782987012 100644 --- a/tests/authoring/Framework/HtmlAssertions.fs +++ b/tests/authoring/Framework/HtmlAssertions.fs @@ -167,3 +167,47 @@ But was not found in: let defaultFile = actual.MarkdownResults |> Seq.find (fun r -> r.File.RelativePath = "index.md") defaultFile |> containsHtml expected + + /// Asserts a raw fragment is present in the rendered HTML, without pretty-printing. + /// The pretty-printed comparison only matches an element with no children, or one + /// snapshotted from the outermost element of the directive output. Use this to assert an + /// attribute on a container without snapshotting its whole subtree. + [] + let containsRawHtml (expected: string) (actual: MarkdownResult) = + if not <| actual.Html.Contains expected then + let msg = $"""Expected html to contain: +{expected} + +But it was not found in: + +{actual.Html} +""" + raise (XunitException(msg)) + + [] + let convertsToContainingRawHtml (expected: string) (actual: Lazy) = + let actual = actual.Value + + let defaultFile = actual.MarkdownResults |> Seq.find (fun r -> r.File.RelativePath = "index.md") + defaultFile |> containsRawHtml expected + + /// Asserts a fragment is absent from the rendered HTML. Checks the whole page, so the + /// needle must be unique to the directive under test and not appear in site chrome. + [] + let doesNotContainHtml (expected: string) (actual: MarkdownResult) = + if actual.Html.Contains expected then + let msg = $"""Expected html NOT to contain: +{expected} + +But it was found in: + +{actual.Html} +""" + raise (XunitException(msg)) + + [] + let doesNotConvertToContainingHtml (expected: string) (actual: Lazy) = + let actual = actual.Value + + let defaultFile = actual.MarkdownResults |> Seq.find (fun r -> r.File.RelativePath = "index.md") + defaultFile |> doesNotContainHtml expected diff --git a/tests/authoring/authoring.fsproj b/tests/authoring/authoring.fsproj index db9aafb701..7f299d64f7 100644 --- a/tests/authoring/authoring.fsproj +++ b/tests/authoring/authoring.fsproj @@ -53,6 +53,9 @@ + + + From b3b7944a9bad7ce3a14a72ec67a207749114b4f6 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Fri, 14 Aug 2026 12:20:30 +0200 Subject: [PATCH 05/11] Hub pages 2/4: {card-group}, {link-card}, and {explore} (#3826) * Add {card-group}, {link-card}, and {explore} These three ship together because {explore} is what switches the other two into their second rendering mode. A reviewer cannot judge the mechanism from any one of them alone. {card-group} is a section heading and a card grid. {link-card} is one card, with a title, a description, a primary link list, and an optional aside. Its body is a fixed YAML schema rather than markdown, so a missing title or invalid YAML fails the build. {explore} wraps card groups into a stack of collapsible accordions. Nesting drives the mode switch, not an option. Inside {explore} a card group renders as an accordion and a link card renders as a titled link column, with the description dropped and the aside rendered as a badge cluster under its own authored label. Driving this from the ancestor rather than a per-directive option means every card grid elsewhere on the site keeps working unchanged. Adds HubDirectiveViewModel, which centralises the attributes a hub link needs. Hub links come from options and YAML bodies, so they never pass through Markdig's link renderer and each view was repeating the external, anchor, and preload rules by hand. {hero} moves onto it too. The LLM export keeps the whole structure. The curated grouping of links is what a hub page is for, and the nav tree in llms.txt is neither ordered nor curated, so it is not a substitute. The search body deliberately gets nothing from these three directives: section, card, and link titles are the tokens that would let a hub outrank the pages it links to on a specific query. Adds doesNotContainHtml to the authoring assertions, for content a directive drops on purpose. Co-Authored-By: Claude Opus 5 * Apply review feedback to cards and the explore section Martijn's review on #3826. - Card link lists and column link lists take the site's standard link affordance: a bullet, blue, underlined. The leading chevron is gone. An arrow now means a control that behaves like a button, such as a hero action, rather than an entry in a link index. - The aside cluster takes the {button} directive's secondary treatment in a new small size, because those are buttons rather than cards. The size modifier composes with either button type and is available to any caller. - Only a card that carries its own link lifts on hover, and that card now has a whole-card target. A card holding several links and no link of its own no longer promises a click it cannot answer. - Card and explore type moves onto the site's scale. - Explore accordions no longer share a `name`, so a reader can hold several open and compare them. Co-Authored-By: Claude Opus 5 * Raise card and explore text to body size Martijn's point about tiny fonts applies to every piece of hub text. Card descriptions, column descriptions, and aside links now read at the body size. The two cluster labels sit one step down, so they stay distinct from the column headings beside them, and nothing renders below 14px. The aside buttons keep 14px. They support the column links above them, so they must not outweigh them. Co-Authored-By: Claude Opus 5 * Drop the now unused anchor flag on a hero action The flag only ever drove the arrow, and the shared link attributes do their own anchor check for preloading. Co-Authored-By: Claude Opus 5 * Drop the aside from a link card A link card held two kinds of link: a primary list and an aside that rendered as a badge cluster in a column, or as inline dot-separated links in a card. That is two visual languages for the same thing, in one card. The aside also could not express what it promised. It said "these are secondary", and the only signal was its label. At 12px that label was too small to read, and at 14px it was indistinguishable from the column heading beside it. There is no size that reads as subordinate but legible. A second group of links now becomes a second card. One shape, one treatment, everywhere. This removes the `aside` field, both of its renderings, the badge styling, and the small button size added for it, which nothing else used. It also removes the label sizing question and the sub-24px target on the badges. Follow-ups: elastic/docs-content-internal#1385 and #1549 both specify `aside` and need updating. Co-Authored-By: Claude Opus 5 * Make the linked card's hover state visible The hover border moved from grey-20 to grey-30, a change from 1.22:1 to 1.49:1 against white. That is not a visible state change, and a state indicator has to clear 3:1. It now uses grey-80 at 4.15:1, which is what {page-card} already uses for the same job. The resting border stays grey-20. It is a container edge rather than the thing that identifies the control, and {page-card} rests there too. Co-Authored-By: Claude Opus 5 * Restore the explore container width The explore stack lost its max-width, so the accordion rows ran the full content column while the section heading above them stayed within the shared width. The rows started well left of their own heading. The rule was collateral damage when the aside styling was removed: the deleted range ran past the aside block and took the container with it. The accordion also drops its horizontal padding, so a title starts on the same line as the section heading and the toggle icon ends on the same line as its right edge. Co-Authored-By: Claude Opus 5 --------- Co-authored-by: Claude Opus 5 --- docs/_docset.yml | 3 + docs/examples/products/docs-builder.md | 212 ++++++++++++ docs/syntax/card-group.md | 49 +++ docs/syntax/explore.md | 72 ++++ docs/syntax/hero.md | 2 +- docs/syntax/hub-pages.md | 5 +- docs/syntax/link-card.md | 60 ++++ .../Assets/markdown/hub.css | 311 +++++++++++++++++- .../Myst/Directives/DirectiveBlockParser.cs | 9 + .../Myst/Directives/DirectiveHtmlRenderer.cs | 50 +++ .../Myst/Directives/Hub/CardGroupBlock.cs | 46 +++ .../Myst/Directives/Hub/CardGroupView.cshtml | 44 +++ .../Myst/Directives/Hub/CardGroupViewModel.cs | 19 ++ .../Myst/Directives/Hub/ExploreBlock.cs | 49 +++ .../Myst/Directives/Hub/ExploreView.cshtml | 12 + .../Myst/Directives/Hub/ExploreViewModel.cs | 12 + .../Myst/Directives/Hub/HeroView.cshtml | 8 +- .../Myst/Directives/Hub/HeroViewModel.cs | 21 +- .../Directives/Hub/HubDirectiveViewModel.cs | 51 +++ .../Myst/Directives/Hub/HubExplore.cs | 36 ++ .../Myst/Directives/Hub/HubYamlBody.cs | 96 ++++++ .../Myst/Directives/Hub/LinkCardBlock.cs | 98 ++++++ .../Myst/Directives/Hub/LinkCardView.cshtml | 80 +++++ .../Myst/Directives/Hub/LinkCardViewModel.cs | 15 + .../LlmMarkdown/LlmBlockRenderers.cs | 80 ++++- .../PlainText/PlainTextBlockRenderers.cs | 7 + .../Myst/YamlSerialization.cs | 2 + tests/authoring/Blocks/Hub/CardsAndExplore.fs | 261 +++++++++++++++ tests/authoring/authoring.fsproj | 1 + 29 files changed, 1685 insertions(+), 26 deletions(-) create mode 100644 docs/syntax/card-group.md create mode 100644 docs/syntax/explore.md create mode 100644 docs/syntax/link-card.md create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/CardGroupBlock.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/CardGroupView.cshtml create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/CardGroupViewModel.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/ExploreBlock.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/ExploreView.cshtml create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/ExploreViewModel.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/HubDirectiveViewModel.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/HubExplore.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/HubYamlBody.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/LinkCardBlock.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/LinkCardView.cshtml create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/LinkCardViewModel.cs create mode 100644 tests/authoring/Blocks/Hub/CardsAndExplore.fs diff --git a/docs/_docset.yml b/docs/_docset.yml index a05806da81..e518cc269d 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -110,6 +110,7 @@ toc: - file: applies-switch.md - file: automated_settings.md - file: buttons.md + - file: card-group.md - file: changelog.md - file: code.md - file: comments.md @@ -117,6 +118,7 @@ toc: - file: csv-include.md - file: dropdowns.md - file: definition-lists.md + - file: explore.md - file: file_inclusion.md - file: footnotes.md - file: frontmatter.md @@ -126,6 +128,7 @@ toc: - file: images.md - file: videos.md - file: kbd.md + - file: link-card.md - file: math.md - file: diagrams.md - file: lists.md diff --git a/docs/examples/products/docs-builder.md b/docs/examples/products/docs-builder.md index 283f45e46b..1b13353a5d 100644 --- a/docs/examples/products/docs-builder.md +++ b/docs/examples/products/docs-builder.md @@ -9,4 +9,216 @@ description: docs-builder documentation. Build, validate, and publish Elastic do :description: The toolchain that builds Elastic's documentation. Author in Markdown, validate cross-repository links, preview locally, and publish one unified site. :primary-action: [Install docs-builder](/getting-started/installation.md) :secondary-action: [Elastic documentation](docs-content://get-started/index.md) +:tertiary-action: [Explore docs-builder](#explore) ::: + +::::{card-group} +:title: Get hands-on +:id: hands-on +:intro: New to the toolchain? Follow a guided path from install to published page. + +:::{link-card} +title: Write your first page +link: /getting-started/writing-content.md +description: Author a page, add links, and preview it locally. +links: + - label: Writing content + url: /getting-started/writing-content.md + - label: Pages and links + url: /getting-started/pages-and-links.md +::: + +:::{link-card} +title: Serve and publish +link: /getting-started/serve.md +description: Run the local preview server, then publish the built site. +links: + - label: Serve locally + url: /getting-started/serve.md + - label: Publish + url: /getting-started/publish.md +::: + +:::{link-card} +title: Syntax reference +link: /syntax/index.md +description: Every directive and role the toolchain understands. +links: + - label: Browse the syntax guide + url: /syntax/index.md + - label: Hub pages + url: /syntax/hub-pages.md +::: +:::: + +::::{card-group} +:title: Documentation this toolchain builds +:id: solutions +:intro: The published Elastic documentation, linked with cross-repository links. +:variant: solutions + +:::{link-card} +icon: elasticsearch +variant: es +title: Elasticsearch +description: Search and analytics documentation. +links: + - label: Search solution + url: docs-content://solutions/search.md + - label: Manage data + url: docs-content://manage-data/index.md +::: + +:::{link-card} +icon: observability +variant: obs +title: Observability +description: Logs, metrics, traces, and alerting documentation. +links: + - label: Observability solution + url: docs-content://solutions/observability.md + - label: Explore and analyze + url: docs-content://explore-analyze/index.md +::: + +:::{link-card} +icon: security +variant: sec +title: Security +description: SIEM, endpoint, and detection documentation. +links: + - label: Security solution + url: docs-content://solutions/security.md + - label: Deploy and manage + url: docs-content://deploy-manage/index.md +::: +:::: + +:::::{explore} +:id: explore +:title: Explore docs-builder +:intro: Find what you need, organized by task, from authoring and building to publishing and operating. + +::::{card-group} +:title: Authoring +:id: authoring + +:::{link-card} +title: Syntax +links: + - label: Directives + url: /syntax/directives.md + - label: Hub pages + url: /syntax/hub-pages.md + - label: Hero + url: /syntax/hero.md +::: + +:::{link-card} +title: Card directives +links: + - label: Card group + url: /syntax/card-group.md + - label: Link card + url: /syntax/link-card.md + - label: Explore + url: /syntax/explore.md + - label: Page card + url: /syntax/page-card.md +::: + +:::{link-card} +title: Getting started +links: + - label: Installation + url: /getting-started/installation.md + - label: Writing content + url: /getting-started/writing-content.md + - label: Pages and links + url: /getting-started/pages-and-links.md +::: + +:::{link-card} +title: Formatting +links: + - label: Code blocks + url: /syntax/code.md + - label: Tables + url: /syntax/tables.md + - label: Lists + url: /syntax/lists.md + - label: Admonitions + url: /syntax/admonitions.md +::: + +:::{link-card} +title: Page metadata +links: + - label: Frontmatter + url: /syntax/frontmatter.md + - label: Links + url: /syntax/links.md + - label: Substitutions + url: /syntax/substitutions.md +::: +:::: + +::::{card-group} +:title: Builds and configuration +:id: builds + +:::{link-card} +title: Build types +links: + - label: Isolated builds + url: /documentation/isolated/configure/index.md + - label: Assembler + url: /documentation/assembler/configure/index.md + - label: Codex + url: /documentation/codex/index.md +::: + +:::{link-card} +title: Catalog +links: + - label: Products + url: /documentation/catalog/products.md + - label: Versions + url: /documentation/catalog/versions.md +::: + +:::{link-card} +title: Catalog reference +links: + - label: Synonyms + url: /documentation/catalog/synonyms.md + - label: Legacy URLs + url: /documentation/catalog/legacy-url-mappings.md +::: +:::: + +::::{card-group} +:title: Structured data and operations +:id: data + +:::{link-card} +title: Exporters +links: + - label: Overview + url: /data/exporters/index.md + - label: LLM markdown + url: /data/exporters/llm.md + - label: Plain text + url: /data/exporters/plain-text.md +::: + +:::{link-card} +title: Operations +links: + - label: Distributed builds + url: /documentation/distributed-builds.md + - label: Infrastructure + url: /documentation/assembler/infrastructure.md +::: +:::: +::::: diff --git a/docs/syntax/card-group.md b/docs/syntax/card-group.md new file mode 100644 index 0000000000..b63b3ea3db --- /dev/null +++ b/docs/syntax/card-group.md @@ -0,0 +1,49 @@ +# Card group + +A section heading and a card grid container. It wraps one or more [`{link-card}`](link-card.md) directives. + +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for both rendering modes on one page. + +## Basic + +```markdown +::::{card-group} +:title: Install and administer +:id: install + +:::{link-card} +title: Self-managed +link: /getting-started/installation.md +description: Run on your own infrastructure. +::: + +:::{link-card} +title: Serve locally +link: /getting-started/serve.md +description: Preview the site while you write. +::: +:::: +``` + +The outer fence uses **four** colons, so the inner three-colon fences are not read as a closing fence. Add as many extra colons to the outer fence as the nesting needs. + +## Options + +| Option | Notes | +|---|---| +| `:title:` | H2 heading. Optional. Without it, only the grid renders. | +| `:intro:` | Intro paragraph below the heading. | +| `:id:` | Section anchor. | +| `:variant:` | Set to `solutions` to lock a 3-up grid. | + +## Layout + +By default the grid auto-fills 1, 2, or 3 columns based on the available width. Card heights match within a row. + +With `:variant: solutions`, the grid locks to three equal columns, stepping to two and then one at narrower widths. A fourth card wraps to the next row instead of compressing the layout into a narrow fourth column. + +## Inside `{explore}` + +Nest a card group in an [`{explore}`](explore.md) section and it renders as a collapsible accordion instead of a titled grid. The `:title:` becomes the accordion header, and each child [`{link-card}`](link-card.md) renders as a link column. + +No option controls this. The `{explore}` ancestor drives it. That keeps every card grid elsewhere on the site working unchanged, and it means an author wraps existing groups in `{explore}` rather than learning a second directive. diff --git a/docs/syntax/explore.md b/docs/syntax/explore.md new file mode 100644 index 0000000000..e368f7532c --- /dev/null +++ b/docs/syntax/explore.md @@ -0,0 +1,72 @@ +# Explore + +The browse-everything section of a [hub page](hub-pages.md). It is a titled band holding a stack of collapsible accordions, and it wraps one or more [`{card-group}`](card-group.md) directives. + +A hub's full link list can run to nine or ten sections. Without grouping that is a very long page, so `{explore}` collapses it into a scannable stack. + +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered stack. + +## Basic + +```markdown +:::::{explore} +:id: explore +:title: Explore the docs toolchain +:intro: Find what you need, organized by task. + +::::{card-group} +:title: Quick links +:id: quick-links + +:::{link-card} +title: Releases and APIs +links: + - label: Exporters + url: /data/exporters/index.md + - label: API reference + url: /data/api.md +::: +:::: + +::::{card-group} +:title: Authoring +:id: authoring + +:::{link-card} +title: Syntax +links: + - label: Directives + url: /syntax/directives.md +::: +:::: +::::: +``` + +## Options + +| Option | Notes | +|---|---| +| `:title:` | **Required.** H2 heading, for example "Explore Elasticsearch". | +| `:intro:` | Intro paragraph below the heading. | +| `:id:` | Section anchor. Use `explore` so `{hero}`'s tertiary action can jump to it. | + +## What nesting changes + +`{explore}` carries no options for the accordions. Nesting drives everything: + +- Each [`{card-group}`](card-group.md) inside becomes one accordion. Its `:title:` is the accordion header. +- The first accordion is expanded. The rest are collapsed. +- A reader can expand as many accordions as they want. Expanding one does not collapse the others. +- Each [`{link-card}`](link-card.md) inside renders as a link column rather than a bordered card. + +Toggling uses native `
` and ``, so it works without JavaScript. + +## Fence depth + +Nesting three directives needs three fence widths. The outer fence always needs one more colon than its deepest child: + +| Directive | Fence | +|---|---| +| `{explore}` | `:::::` | +| `{card-group}` | `::::` | +| `{link-card}` | `:::` | diff --git a/docs/syntax/hero.md b/docs/syntax/hero.md index 75d4be1fd5..206693582e 100644 --- a/docs/syntax/hero.md +++ b/docs/syntax/hero.md @@ -4,7 +4,7 @@ A full-bleed identity band with a product icon, page title, description, and up All hero content comes from options. The directive body is not used. -See the [Elasticsearch documentation hub](../examples/products/docs-builder.md) for a rendered hero. +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered hero. ## Basic diff --git a/docs/syntax/hub-pages.md b/docs/syntax/hub-pages.md index 2fb8ab6846..048ed37e61 100644 --- a/docs/syntax/hub-pages.md +++ b/docs/syntax/hub-pages.md @@ -4,7 +4,7 @@ A hub page is a product-scoped landing page. It gives a reader one 360° view of Hub pages are composed entirely from directives. There is no free-form body content. That constraint is deliberate. It lets every link validate at build time, and it keeps every hub structurally consistent whoever authors it. -See the [Elasticsearch documentation hub](../examples/products/docs-builder.md) for a complete page. +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a complete page. ## Enable the layout @@ -54,6 +54,9 @@ Write both deliberately. The search body indexes the hero title and description | Directive | Purpose | |---|---| | [`{hero}`](hero.md) | Identity band. Carries the product icon, the page title, a description, and up to three actions. | +| [`{card-group}`](card-group.md) | Section heading and card grid. Renders as an accordion inside `{explore}`. | +| [`{link-card}`](link-card.md) | One card: title, description, and a list of links. Renders as a link column inside `{explore}`. | +| [`{explore}`](explore.md) | The browse-everything section. A stack of collapsible accordions. | ## Page skeleton diff --git a/docs/syntax/link-card.md b/docs/syntax/link-card.md new file mode 100644 index 0000000000..f9db9fb9c0 --- /dev/null +++ b/docs/syntax/link-card.md @@ -0,0 +1,60 @@ +# Link card + +A card with a title, a description, and a list of links. It is designed to sit inside a [`{card-group}`](card-group.md), and it renders standalone too. + +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for both rendering modes on one page. + +## Basic + +```markdown +:::{link-card} +title: Writing content +link: /getting-started/writing-content.md +description: Author a page, add links, and preview it locally. +links: + - label: Pages and links + url: /getting-started/pages-and-links.md + - label: Syntax guide + url: /syntax/index.md +::: +``` + +The body is **YAML, not markdown**. The directive expects a fixed schema and renders it, so an author fills in fields rather than writing markup. A missing `title` or invalid YAML fails the build. + +## Schema + +```yaml +title: Writing content # required, the card heading +link: /getting-started/serve.md # optional, makes the title clickable +description: One short blurb. # optional +icon: elasticsearch # optional, product-keyed inline SVG +variant: es # optional accent: es, obs, or sec +links: # optional, the card's links + - label: Pages and links + url: /getting-started/pages-and-links.md +``` + +A card holds one group of links. To present a second group, add a second card. There is no +sub-list, so every group of links reads the same way wherever it appears. + +## Variants + +`variant: es`, `obs`, or `sec` adds a left border in the matching solution colour. Use it for solution cards. + +`icon` takes the same product keys as [`{hero}`](hero.md): `elasticsearch`, `kibana`, `observability`, `security`. + +## Inside `{explore}` + +Nested in an [`{explore}`](explore.md) section, through a `{card-group}` ancestor, the same YAML renders as a titled link column instead of a bordered card. One thing changes: `description` is dropped, because a column is a pure link index. + +## Links + +Every `link` and every entry in `links` validates at build time. Use one of these forms: + +| Form | Example | Behavior | +|---|---|---| +| Site-absolute path | `/syntax/index.md` | The markdown extension is stripped. The link preloads on hover. | +| Cross-link scheme | `elasticsearch://reference/index.md` | Resolves through the link index. | +| External URL | `https://www.elastic.co/docs/api/doc/elasticsearch` | Opens in a new tab, with `rel="noopener noreferrer"`. | + +A relative path such as `foo.md` is rejected. Prefer a cross-link scheme for any page outside the current repository. A site-absolute path that points into another repository's documentation set is validated nowhere. diff --git a/src/Elastic.Documentation.Site/Assets/markdown/hub.css b/src/Elastic.Documentation.Site/Assets/markdown/hub.css index 4274fa36a5..0095fe2326 100644 --- a/src/Elastic.Documentation.Site/Assets/markdown/hub.css +++ b/src/Elastic.Documentation.Site/Assets/markdown/hub.css @@ -154,9 +154,316 @@ flex-shrink: 0; } - /* The arrow slides and the hero animates its hover states. Honour a reduced-motion - preference. Nothing about the resting appearance changes. */ + /* Zone (section heading) ------------------------------------------ */ + .hub-zone { + @apply mx-auto w-full max-w-5xl; + margin-top: 56px; + margin-bottom: 24px; + scroll-margin-top: 120px; + } + .hub-zone:first-of-type { + margin-top: 0; + } + .hub-zone .hub-zone-title { + font-size: var(--text-2xl); + font-weight: 700; + color: var(--color-ink-dark); + line-height: 1.2; + margin: 0; + } + .hub-zone .hub-zone-intro { + color: var(--color-ink-light); + margin-top: 8px; + } + + /* Card grid -------------------------------------------------------- */ + .hub-card-grid { + @apply m-0 mx-auto w-full max-w-5xl list-none p-0; + display: grid; + /* min() so a container narrower than one track shrinks it instead of overflowing. */ + grid-template-columns: repeat(auto-fill, minmax(min(310px, 100%), 1fr)); + gap: 24px; + } + + /* Solutions variant: lock to a 3-up layout that tolerates a future 4th card + (it wraps to the next row rather than shrinking into a 4th narrow column). */ + .hub-card-grid-solutions { + grid-template-columns: repeat(3, minmax(0, 1fr)); + } + + /* Card ------------------------------------------------------------- */ + .hub-card { + background: var(--color-white); + border: 1px solid var(--color-grey-20); + border-radius: 14px; + padding: 22px 22px 20px; + transition: + box-shadow 0.15s, + border-color 0.15s; + margin: 0; + list-style: none; + } + /* Only a card that is itself a link lifts on hover. A card without one holds + several links and no whole-card target, so a lift would promise a click the + card cannot answer. Keyboard focus still lifts either way, because it marks + where focus sits rather than what is clickable. */ + .hub-card-linked:hover, + .hub-card:focus-within { + /* grey-80 is what {page-card} uses for the same job, and it clears the 3:1 ratio a + state indicator needs. The resting grey-20 border is a container edge, not the + thing that identifies the control, so it stays quiet. */ + border-color: var(--color-grey-80); + box-shadow: 0 2px 8px rgb(0 0 0 / 0.05); + } + /* The card title's link covers the whole card, so the lift and the target agree. + Links inside the card sit above it and stay clickable in their own right. */ + .hub-card-linked .hub-card-title a::after { + content: ''; + position: absolute; + inset: 0; + } + .hub-card-linked { + position: relative; + } + .hub-card .hub-card-links { + position: relative; + } + + .hub-card .hub-card-head { + display: flex; + align-items: center; + gap: 10px; + margin-bottom: 6px; + } + .hub-card .hub-card-icon svg { + width: 28px; + height: 28px; + display: block; + } + .hub-card .hub-card-title { + font-size: var(--text-base); + font-weight: 700; + color: var(--color-ink-dark); + margin: 0; + } + .hub-card .hub-card-title a { + color: var(--color-ink-dark); + text-decoration: none; + } + .hub-card .hub-card-title a:hover { + color: var(--color-blue-elastic); + text-decoration: none; + } + + .hub-card .hub-card-desc { + font-size: var(--text-base); + color: var(--color-ink-light); + margin-bottom: 14px; + line-height: 1.5; + } + + /* A card's link list is an index, not a set of buttons, so its entries take the + site's standard link affordance: a bullet, blue, underlined. An arrow is + reserved for a control that behaves like a button, such as a hero action. */ + .hub-card .hub-card-links { + margin: 0; + padding-left: 1.1em; + list-style: disc; + } + .hub-card .hub-card-links li { + margin: 0 0 4px; + list-style: disc; + } + .hub-card .hub-card-links li a { + font-size: var(--text-base); + color: var(--color-blue-elastic-100); + text-decoration: underline; + /* Inline-block so the padding counts toward the target height. */ + display: inline-block; + padding-block: 2px; + line-height: 1.35; + } + .hub-card .hub-card-links li a:hover, + .hub-card .hub-card-links li a:focus-visible { + color: var(--color-blue-elastic-110); + } + + /* Explore {product} — accordion stack ------------------------------ */ + /* Shares the section max-width, so the accordion rows line up with the zone + heading rather than running wider than it. */ + .hub-explore { + @apply mx-auto w-full max-w-5xl; + border-top: 1px solid var(--color-grey-20); + } + + .hub-accordion { + border-bottom: 1px solid var(--color-grey-20); + } + .hub-accordion-summary { + display: flex; + align-items: center; + justify-content: space-between; + gap: 16px; + /* No horizontal padding: the accordion title has to start on the same line as the + section heading, and the toggle icon has to end on the same line as its right edge. */ + padding: 18px 0; + cursor: pointer; + list-style: none; + user-select: none; + } + /* Hide the native disclosure triangle across browsers. */ + .hub-accordion-summary::-webkit-details-marker { + display: none; + } + .hub-accordion-summary::marker { + content: ''; + } + .hub-accordion-title { + /* margin: 0 keeps the heading rendering exactly as the span it replaced. */ + margin: 0; + font-size: var(--text-xl); + font-weight: 700; + color: var(--color-ink-dark); + line-height: 1.3; + } + .hub-accordion-icon { + flex: none; + color: var(--color-ink-light); + } + /* Plus when collapsed, minus when open: drop the vertical stroke on [open]. */ + .hub-accordion-icon-v { + transition: opacity 0.15s ease; + } + .hub-accordion[open] > .hub-accordion-summary .hub-accordion-icon-v { + opacity: 0; + } + .hub-accordion-summary:hover .hub-accordion-title, + .hub-accordion-summary:focus-visible .hub-accordion-title { + color: var(--color-blue-elastic); + } + .hub-accordion-body { + padding: 4px 0 28px; + container-type: inline-size; + } + .hub-accordion-intro { + color: var(--color-ink-light); + margin: 0 0 20px; + } + + /* Columns inside an accordion -------------------------------------- */ + /* Column count follows the accordion body's own width (container query), not the + viewport — the hub's left nav narrows the body, so a viewport query would + under-count. Targets a 4-up layout like the design when there's room. */ + .hub-explore-cols { + @apply m-0 list-none p-0; + display: grid; + grid-template-columns: 1fr; + gap: 28px 24px; + align-items: start; + } + @container (min-width: 420px) { + .hub-explore-cols { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + } + @container (min-width: 620px) { + .hub-explore-cols { + grid-template-columns: repeat(3, minmax(0, 1fr)); + } + } + @container (min-width: 820px) { + .hub-explore-cols { + grid-template-columns: repeat(4, minmax(0, 1fr)); + } + } + .hub-col { + margin: 0; + list-style: none; + min-width: 0; + } + .hub-col-title { + font-size: var(--text-base); + font-weight: 700; + color: var(--color-ink-dark); + margin: 0 0 4px; + line-height: 1.3; + } + .hub-col-title a { + color: var(--color-ink-dark); + text-decoration: none; + } + .hub-col-title a:hover { + color: var(--color-blue-elastic); + text-decoration: underline; + } + .hub-col-desc { + font-size: var(--text-base); + color: var(--color-ink-light); + margin: 0 0 10px; + line-height: 1.4; + } + /* A column is a pure link index, so its entries carry the site's standard link + affordance rather than a quieter bespoke one. A list marker is used, not a flex + column, because markers do not render on flex children. */ + .hub-col-links { + margin: 0; + padding-left: 1.1em; + list-style: disc; + } + .hub-col-links li { + margin: 0 0 4px; + list-style: disc; + } + .hub-col-links a { + font-size: var(--text-base); + color: var(--color-blue-elastic-100); + text-decoration: underline; + /* Inline-block so the padding counts toward the target height. */ + display: inline-block; + padding-block: 2px; + line-height: 1.35; + } + .hub-col-links a:hover, + .hub-col-links a:focus-visible { + color: var(--color-blue-elastic-110); + } + + @media (max-width: 768px) { + .hub-hero h1 { + font-size: var(--text-3xl); + } + .hub-card-grid { + grid-template-columns: 1fr; + } + .hub-on-this-page { + position: static; + flex-direction: column; + } + .hub-card { + padding: 20px; + } + } + + /* Solutions grid steps down gracefully; declared after the base mobile rule + so it wins over .hub-card-grid on shared elements. */ + @media (max-width: 980px) { + .hub-card-grid-solutions { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + } + @media (max-width: 640px) { + .hub-card-grid-solutions { + grid-template-columns: 1fr; + } + } + + /* Hover and arrow transitions are decorative. Honour a reduced-motion preference. + Nothing about the resting appearance changes. */ @media (prefers-reduced-motion: reduce) { + .hub-card, + .hub-accordion-icon-v { + transition: none; + } .hub-hero .hub-hero-eyebrow-link, .hub-hero .hub-hero-action, .hub-arrow { diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs index bafdbfcbd1..565a9ab7c0 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs @@ -141,6 +141,15 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor) if (info.IndexOf("{hero}") > 0) return new HeroBlock(this, context); + if (info.IndexOf("{explore}") > 0) + return new ExploreBlock(this, context); + + if (info.IndexOf("{card-group}") > 0) + return new CardGroupBlock(this, context); + + if (info.IndexOf("{link-card}") > 0) + return new LinkCardBlock(this, context); + if (info.IndexOf("{agent-skill}") > 0) return new AgentSkillBlock(this, context); diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs index e0e989a156..7c4f5f6f1e 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs @@ -108,6 +108,15 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo case HeroBlock heroBlock: WriteHero(renderer, heroBlock); return; + case ExploreBlock exploreBlock: + WriteExplore(renderer, exploreBlock); + return; + case CardGroupBlock cardGroupBlock: + WriteCardGroup(renderer, cardGroupBlock); + return; + case LinkCardBlock linkCardBlock: + WriteLinkCard(renderer, linkCardBlock); + return; case PageCardBlock pageCardBlock: WritePageCard(renderer, pageCardBlock); return; @@ -217,6 +226,47 @@ private static void WriteHero(HtmlRenderer renderer, HeroBlock block) RenderRazorSlice(slice, renderer); } + private static void WriteExplore(HtmlRenderer renderer, ExploreBlock block) + { + var slice = ExploreView.Create(new ExploreViewModel + { + DirectiveBlock = block, + Title = block.Title, + Intro = block.Intro, + Anchor = block.Anchor + }); + RenderRazorSlice(slice, renderer); + } + + private static void WriteCardGroup(HtmlRenderer renderer, CardGroupBlock block) + { + var explore = HubExplore.FindAncestor(block); + var slice = CardGroupView.Create(new CardGroupViewModel + { + DirectiveBlock = block, + Title = block.Title, + Intro = block.Intro, + Anchor = block.Anchor, + Variant = block.Variant, + IsAccordion = explore is not null, + IsOpen = explore is not null && HubExplore.IsFirstCardGroup(explore, block) + }); + RenderRazorSlice(slice, renderer); + } + + private static void WriteLinkCard(HtmlRenderer renderer, LinkCardBlock block) + { + var slice = LinkCardView.Create(new LinkCardViewModel + { + DirectiveBlock = block, + Data = block.Data, + IconSvg = ProductIcons.Get(block.Data.Icon), + SitePathPrefix = block.Build.UrlPathPrefix, + IsColumn = HubExplore.FindAncestor(block) is not null + }); + RenderRazorSlice(slice, renderer); + } + // The hero description is a directive option, not a body block, so it never reaches // the document pipeline. Render it with the default Markdig pipeline for basic inline // markup. Substitutions, roles, and link validation do not apply inside this option. diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupBlock.cs b/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupBlock.cs new file mode 100644 index 0000000000..ed6a11d43a --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupBlock.cs @@ -0,0 +1,46 @@ +// 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.Myst.Directives.Hub; + +/// +/// Container directive that renders a titled section housing a grid of +/// children. Generic and reusable wherever a +/// linked-card grid is appropriate. +/// +/// +/// +/// ::::{card-group} +/// :title: Install and deploy +/// :intro: Set up Elasticsearch on your platform of choice. +/// :id: install +/// +/// :::{link-card} Self-managed +/// :link: /deploy-manage/deploy/self-managed +/// Run on your own infrastructure. +/// ::: +/// :::: +/// +/// +public class CardGroupBlock(DirectiveBlockParser parser, ParserContext context) + : DirectiveBlock(parser, context) +{ + public override string Directive => "card-group"; + + public string? Title { get; private set; } + public string? Intro { get; private set; } + public string? Anchor { get; private set; } + public string? Variant { get; private set; } + + public override void FinalizeAndValidate(ParserContext context) + { + Title = Prop("title"); + Intro = Prop("intro"); + Anchor = Prop("id"); + Variant = Prop("variant"); + } + + public override IEnumerable GeneratedAnchors => + string.IsNullOrWhiteSpace(Anchor) ? [] : [Anchor]; +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupView.cshtml b/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupView.cshtml new file mode 100644 index 0000000000..9ac42ef18d --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupView.cshtml @@ -0,0 +1,44 @@ +@inherits RazorSlice + +@if (Model.IsAccordion) +{ + @* No `name` attribute: a browse surface should let a reader keep several sections open + and compare them. A shared name would close every other accordion on each expand. *@ +
+ + @* A heading, not a span. Without it the accordion group is missing from the page + outline, and a reader navigating by heading jumps from the section straight into the + column titles inside it. *@ +

@Model.Title

+ + +
+ @if (!string.IsNullOrWhiteSpace(Model.Intro)) + { +

@Model.Intro

+ } +
    + @Model.RenderBlock() +
+
+
+} +else +{ + @if (!string.IsNullOrWhiteSpace(Model.Title)) + { +
+

@Model.Title

+ @if (!string.IsNullOrWhiteSpace(Model.Intro)) + { +

@Model.Intro

+ } +
+ } +
    + @Model.RenderBlock() +
+} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupViewModel.cs new file mode 100644 index 0000000000..4a29a646cf --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/CardGroupViewModel.cs @@ -0,0 +1,19 @@ +// 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.Myst.Directives.Hub; + +public class CardGroupViewModel : DirectiveViewModel +{ + public required string? Title { get; init; } + public required string? Intro { get; init; } + public required string? Anchor { get; init; } + public required string? Variant { get; init; } + + /// Rendered as a collapsible accordion group inside an {explore} section. + public bool IsAccordion { get; init; } + + /// The accordion is expanded by default (the first group in an Explore stack). + public bool IsOpen { get; init; } +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/ExploreBlock.cs b/src/Elastic.Markdown/Myst/Directives/Hub/ExploreBlock.cs new file mode 100644 index 0000000000..781e343107 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/ExploreBlock.cs @@ -0,0 +1,49 @@ +// 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.Markdown.Diagnostics; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// The "Explore {product}" hub section: a titled band that houses a stack of +/// children rendered as collapsible accordion groups. +/// Nested card-groups and their link-cards detect this ancestor and switch to +/// their accordion/column rendering. +/// +/// +/// +/// :::::{explore} +/// :title: Explore Kibana +/// :intro: Explore the apps and capabilities that help you act on your data. +/// +/// ::::{card-group} +/// :title: Install & admin +/// ... link-cards ... +/// :::: +/// ::::: +/// +/// +public class ExploreBlock(DirectiveBlockParser parser, ParserContext context) + : DirectiveBlock(parser, context) +{ + public override string Directive => "explore"; + + public string? Title { get; private set; } + public string? Intro { get; private set; } + public string? Anchor { get; private set; } + + public override void FinalizeAndValidate(ParserContext context) + { + Title = Prop("title"); + Intro = Prop("intro"); + Anchor = Prop("id"); + + if (string.IsNullOrWhiteSpace(Title)) + this.EmitError("{explore} requires a `:title:` option."); + } + + public override IEnumerable GeneratedAnchors => + string.IsNullOrWhiteSpace(Anchor) ? [] : [Anchor]; +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/ExploreView.cshtml b/src/Elastic.Markdown/Myst/Directives/Hub/ExploreView.cshtml new file mode 100644 index 0000000000..799ac3141f --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/ExploreView.cshtml @@ -0,0 +1,12 @@ +@inherits RazorSlice + +
+

@Model.Title

+ @if (!string.IsNullOrWhiteSpace(Model.Intro)) + { +

@Model.Intro

+ } +
+
+ @Model.RenderBlock() +
diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/ExploreViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/ExploreViewModel.cs new file mode 100644 index 0000000000..77415c609f --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/ExploreViewModel.cs @@ -0,0 +1,12 @@ +// 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.Myst.Directives.Hub; + +public class ExploreViewModel : DirectiveViewModel +{ + public required string? Title { get; init; } + public required string? Intro { get; init; } + public required string? Anchor { get; init; } +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/HeroView.cshtml b/src/Elastic.Markdown/Myst/Directives/Hub/HeroView.cshtml index 272d17debb..64f4befbdd 100644 --- a/src/Elastic.Markdown/Myst/Directives/Hub/HeroView.cshtml +++ b/src/Elastic.Markdown/Myst/Directives/Hub/HeroView.cshtml @@ -4,7 +4,7 @@
- + Browse all Elastic docs - + @action.Label diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/HeroViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/HeroViewModel.cs index 729dc6c682..c43be99b43 100644 --- a/src/Elastic.Markdown/Myst/Directives/Hub/HeroViewModel.cs +++ b/src/Elastic.Markdown/Myst/Directives/Hub/HeroViewModel.cs @@ -4,7 +4,7 @@ namespace Elastic.Markdown.Myst.Directives.Hub; -public class HeroViewModel : DirectiveViewModel +public class HeroViewModel : HubDirectiveViewModel { public required string? IconKey { get; init; } public required string? IconSvg { get; init; } @@ -16,9 +16,6 @@ public class HeroViewModel : DirectiveViewModel public required string? SecondaryActionUrl { get; init; } public required string? TertiaryActionLabel { get; init; } public required string? TertiaryActionUrl { get; init; } - public required string? SitePathPrefix { get; init; } - public string? PrefixUrl(string? url) => DirectiveLinkValidator.ToHref(url, SitePathPrefix); - public IReadOnlyList Actions { get @@ -36,20 +33,14 @@ private void Add(List actions, string? label, string? url) if (string.IsNullOrWhiteSpace(label) || string.IsNullOrWhiteSpace(url)) return; - var isAnchor = url[0] == '#'; - // A cross-link resolves to a full URL but still points at documentation this site serves, - // so it is not external. Inline links make the same distinction. - var isExternal = url.StartsWith("http", StringComparison.OrdinalIgnoreCase) - && !DirectiveLinkValidator.IsResolvedCrossLink((DirectiveBlock)DirectiveBlock, url); - actions.Add(new HeroAction(label, url, isAnchor, isExternal)); + actions.Add(new HeroAction(label, url)); } } /// /// One hero call to action. The three actions carry equal weight and render as neutral -/// buttons, so the option a label came from does not change its appearance. -/// drives the arrow that marks an in-page jump. -/// follows the same rules as inline links: an external link -/// opens in a new tab and skips preloading, and only an internal link is worth preloading. +/// buttons, so the option a label came from does not change its appearance. The href and +/// its link attributes come from , which +/// owns the anchor, external, and cross-link rules. /// -public sealed record HeroAction(string Label, string Url, bool IsAnchor, bool IsExternal); +public sealed record HeroAction(string Label, string Url); diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/HubDirectiveViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/HubDirectiveViewModel.cs new file mode 100644 index 0000000000..b7d71f80e8 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/HubDirectiveViewModel.cs @@ -0,0 +1,51 @@ +// 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 System.Text; +using Elastic.Documentation.Site; +using Microsoft.AspNetCore.Html; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// Shared base for hub directive view models. Hub links come from directive options and YAML +/// bodies, so they are written straight into an href rather than going through Markdig's link +/// renderer. This centralises the attributes an anchor needs, so every hub link behaves the +/// same way as an inline link. +/// +public abstract class HubDirectiveViewModel : DirectiveViewModel +{ + public required string? SitePathPrefix { get; init; } + + /// Resolve a URL to a final href, applying the site path prefix. + public string? PrefixUrl(string? url) => DirectiveLinkValidator.ToHref(url, SitePathPrefix); + + /// + /// Render the full attribute set for a hub link: the resolved href, plus the same treatment + /// inline links get. An external link opens in a new tab and is not preloaded. An in-page + /// anchor is not preloaded either. Only a link this site serves is worth preloading. + /// + public HtmlString LinkAttributes(string? url) + { + var href = PrefixUrl(url) ?? string.Empty; + var attributes = new StringBuilder(); + _ = attributes.Append("href=\"").Append(HtmlEncoder.Encode(href)).Append('"'); + + // A cross-link resolves to a full URL but still points at documentation this site serves, + // so it is not external. Inline links make the same distinction. + if (IsExternal(url) && !DirectiveLinkValidator.IsResolvedCrossLink((DirectiveBlock)DirectiveBlock, url)) + _ = attributes.Append(" target=\"_blank\" rel=\"noopener noreferrer\""); + else if (!IsAnchor(url)) + _ = attributes.Append(" preload=\"").Append(Htmx.Preload).Append('"'); + + return new HtmlString(attributes.ToString()); + } + + private static bool IsExternal(string? url) => + url is not null && url.StartsWith("http", StringComparison.OrdinalIgnoreCase); + + private static bool IsAnchor(string? url) => url is ['#', ..]; + + private static System.Text.Encodings.Web.HtmlEncoder HtmlEncoder => System.Text.Encodings.Web.HtmlEncoder.Default; +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/HubExplore.cs b/src/Elastic.Markdown/Myst/Directives/Hub/HubExplore.cs new file mode 100644 index 0000000000..602a759bd8 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/HubExplore.cs @@ -0,0 +1,36 @@ +// 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 Markdig.Syntax; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// Helpers for the "Explore {product}" section. Nested card-groups and link-cards +/// switch to their accordion/column rendering when they sit inside an +/// , detected by walking the Markdig parent chain. +/// +internal static class HubExplore +{ + public static ExploreBlock? FindAncestor(Block? block) + { + for (var parent = block?.Parent; parent is not null; parent = parent.Parent) + { + if (parent is ExploreBlock explore) + return explore; + } + return null; + } + + /// The first accordion in an Explore stack is expanded by default. + public static bool IsFirstCardGroup(ExploreBlock explore, CardGroupBlock card) + { + foreach (var child in explore) + { + if (child is CardGroupBlock candidate) + return ReferenceEquals(candidate, card); + } + return false; + } +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/HubYamlBody.cs b/src/Elastic.Markdown/Myst/Directives/Hub/HubYamlBody.cs new file mode 100644 index 0000000000..fe885e3ce0 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/HubYamlBody.cs @@ -0,0 +1,96 @@ +// 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 Markdig.Syntax; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// Helpers for directives that read their body as raw YAML directly from the +/// source file. The directive's children remain markdown blocks (so renderers +/// that don't recognize the directive still produce something), but the +/// canonical structured data comes from the YAML. +/// +internal static class HubYamlBody +{ + /// + /// Returns the raw text between the opening and closing fences of a directive + /// block, or null when no fenced body could be located. + /// + public static string? Extract(IBlockExtension block, IFileSystemFileReader reader) + { + if (block is not Block markdig) + return null; + + string source; + try + { + source = reader.ReadAllText(block.CurrentFile.FullName); + } + catch + { + return null; + } + + var lines = source.Split('\n'); + var openingLine = markdig.Line; + if (openingLine < 0 || openingLine >= lines.Length) + return null; + + var fence = ExtractFenceMarker(lines[openingLine]); + if (fence is null) + return null; + + var closingLine = -1; + for (var i = openingLine + 1; i < lines.Length; i++) + { + var trimmed = lines[i].TrimStart(); + if (trimmed.StartsWith(fence, StringComparison.Ordinal) && IsClosingFence(trimmed, fence)) + { + closingLine = i; + break; + } + } + if (closingLine < 0) + return null; + + var body = string.Join('\n', lines, openingLine + 1, closingLine - openingLine - 1); + return string.IsNullOrWhiteSpace(body) ? null : body; + } + + private static string? ExtractFenceMarker(string openingLine) + { + var trimmed = openingLine.TrimStart(); + var count = 0; + while (count < trimmed.Length && trimmed[count] == ':') + count++; + return count >= 3 ? new string(':', count) : null; + } + + private static bool IsClosingFence(string trimmed, string fence) + { + if (!trimmed.StartsWith(fence, StringComparison.Ordinal)) + return false; + for (var i = fence.Length; i < trimmed.Length; i++) + { + if (!char.IsWhiteSpace(trimmed[i])) + return false; + } + return true; + } +} + +/// +/// Minimal abstraction over file reading so HubYamlBody can be tested without a +/// full BuildContext. +/// +public interface IFileSystemFileReader +{ + string ReadAllText(string path); +} + +internal sealed class BuildContextFileReader(System.IO.Abstractions.IFileSystem fileSystem) : IFileSystemFileReader +{ + public string ReadAllText(string path) => fileSystem.File.ReadAllText(path); +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardBlock.cs b/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardBlock.cs new file mode 100644 index 0000000000..d98e21d3c2 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardBlock.cs @@ -0,0 +1,98 @@ +// 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.Markdown.Diagnostics; +using YamlDotNet.Core; +using YamlDotNet.Serialization; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// A card with a title, an optional link and description, and a list of links. The card +/// schema is YAML-formatted in the directive body for predictable structure. +/// +/// +/// +/// :::{link-card} +/// title: Discover +/// link: /discover/ +/// description: Browse documents, filter, and query your indices in real time. +/// links: +/// - label: Get started with Discover +/// url: /discover/get-started +/// - label: Use ES|QL in Kibana +/// url: /esql +/// ::: +/// +/// +public class LinkCardBlock(DirectiveBlockParser parser, ParserContext context) + : DirectiveBlock(parser, context), IBlockTitle +{ + public override string Directive => "link-card"; + + public LinkCardData Data { get; private set; } = LinkCardData.Empty; + + public string Title => Data.Title ?? string.Empty; + + public override void FinalizeAndValidate(ParserContext context) + { + var yaml = HubYamlBody.Extract(this, new BuildContextFileReader(Build.ReadFileSystem)); + if (yaml is null) + { + this.EmitError("{link-card} requires a YAML body. See the link-card directive docs."); + return; + } + + try + { + Data = YamlSerialization.Deserialize(yaml, Build.ProductsConfiguration) ?? LinkCardData.Empty; + } + catch (YamlException ex) + { + this.EmitError($"{{link-card}} YAML parse error: {ex.Message}"); + return; + } + + if (string.IsNullOrWhiteSpace(Data.Title)) + this.EmitError("{link-card} requires a `title` field in its YAML body."); + + Data.Link = DirectiveLinkValidator.ValidateAndResolve(Data.Link, this, context); + foreach (var link in Data.Links) + link.Url = DirectiveLinkValidator.ValidateAndResolve(link.Url, this, context); + } +} + +[YamlSerializable] +public record LinkCardData +{ + [YamlMember(Alias = "title")] + public string? Title { get; set; } + + [YamlMember(Alias = "link")] + public string? Link { get; set; } + + [YamlMember(Alias = "description")] + public string? Description { get; set; } + + [YamlMember(Alias = "icon")] + public string? Icon { get; set; } + + [YamlMember(Alias = "variant")] + public string? Variant { get; set; } + + [YamlMember(Alias = "links")] + public LinkCardLink[] Links { get; set; } = []; + + public static LinkCardData Empty { get; } = new(); +} + +[YamlSerializable] +public record LinkCardLink +{ + [YamlMember(Alias = "label")] + public string? Label { get; set; } + + [YamlMember(Alias = "url")] + public string? Url { get; set; } +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardView.cshtml b/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardView.cshtml new file mode 100644 index 0000000000..444093df7c --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardView.cshtml @@ -0,0 +1,80 @@ +@inherits RazorSlice + +@{ + var d = Model.Data; +} + +@if (Model.IsColumn) +{ +
  • +

    + @if (!string.IsNullOrWhiteSpace(d.Link)) + { + @d.Title + } + else + { + @d.Title + } +

    + + @if (d.Links.Length > 0) + { +
      + @foreach (var link in d.Links) + { + if (string.IsNullOrWhiteSpace(link.Url) || string.IsNullOrWhiteSpace(link.Label)) + continue; +
    • @link.Label
      • + } +
    + } +
    • +} +else +{ + var classes = "hub-card"; + // A card with its own link gets a whole-card target. Without one there is nothing + // for a card-wide hover state to point at. + if (!string.IsNullOrWhiteSpace(d.Link)) + classes += " hub-card-linked"; + if (!string.IsNullOrWhiteSpace(d.Variant)) + classes += " hub-card-sol hub-card-sol-" + d.Variant; + +
  • +
    + @if (!string.IsNullOrWhiteSpace(Model.IconSvg)) + { + @(new HtmlString(Model.IconSvg)) + } +

    + @if (!string.IsNullOrWhiteSpace(d.Link)) + { + @d.Title + } + else + { + @d.Title + } +

    +
    + + @if (!string.IsNullOrWhiteSpace(d.Description)) + { +

    @d.Description

    + } + + @if (d.Links.Length > 0) + { +
      + @foreach (var link in d.Links) + { + if (string.IsNullOrWhiteSpace(link.Url) || string.IsNullOrWhiteSpace(link.Label)) + continue; +
    • @link.Label
      • + } +
    + } + +
    • +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardViewModel.cs new file mode 100644 index 0000000000..cb9b7e8d26 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/LinkCardViewModel.cs @@ -0,0 +1,15 @@ +// 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.Myst.Directives.Hub; + +public class LinkCardViewModel : HubDirectiveViewModel +{ + public required LinkCardData Data { get; init; } + public required string? IconSvg { get; init; } + + /// Rendered as a titled link column inside an {explore} accordion. + public bool IsColumn { get; init; } + +} diff --git a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs index 4b3ddca5bd..a8de739529 100644 --- a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs +++ b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs @@ -505,6 +505,15 @@ protected override void Write(LlmMarkdownRenderer renderer, DirectiveBlock obj) case HeroBlock heroBlock: WriteHeroBlock(renderer, heroBlock); return; + case ExploreBlock exploreBlock: + WriteExploreBlock(renderer, exploreBlock); + return; + case CardGroupBlock cardGroupBlock: + WriteCardGroupBlock(renderer, cardGroupBlock); + return; + case LinkCardBlock linkCardBlock: + WriteLinkCardBlock(renderer, linkCardBlock); + return; } // Ensure single empty line before directive @@ -571,13 +580,82 @@ private static void WriteHeroBlock(LlmMarkdownRenderer renderer, HeroBlock heroB renderer.EnsureLine(); } + // The curated grouping of links is what a hub page is for, so the export keeps the whole + // structure: each section becomes a heading and each card a titled link list. + private static void WriteExploreBlock(LlmMarkdownRenderer renderer, ExploreBlock block) + { + renderer.EnsureBlockSpacing(); + if (!string.IsNullOrEmpty(block.Title)) + { + renderer.WriteLine($"## {block.Title}"); + renderer.EnsureLine(); + } + if (!string.IsNullOrEmpty(block.Intro)) + { + renderer.WriteLine(block.Intro); + renderer.EnsureLine(); + } + renderer.WriteChildren(block); + } + + private static void WriteCardGroupBlock(LlmMarkdownRenderer renderer, CardGroupBlock block) + { + renderer.EnsureBlockSpacing(); + if (!string.IsNullOrEmpty(block.Title)) + { + renderer.WriteLine($"### {block.Title}"); + renderer.EnsureLine(); + } + if (!string.IsNullOrEmpty(block.Intro)) + { + renderer.WriteLine(block.Intro); + renderer.EnsureLine(); + } + renderer.WriteChildren(block); + } + + private static void WriteLinkCardBlock(LlmMarkdownRenderer renderer, LinkCardBlock block) + { + var data = block.Data; + renderer.EnsureBlockSpacing(); + + if (!string.IsNullOrEmpty(data.Title)) + { + var heading = string.IsNullOrEmpty(data.Link) + ? data.Title + : $"[{data.Title}]({HubLinkForLlm(renderer, data.Link)})"; + renderer.WriteLine($"#### {heading}"); + renderer.EnsureLine(); + } + + // The description is hidden in column mode, but the export is not laid out, so it is + // always useful context here. + if (!string.IsNullOrEmpty(data.Description)) + { + renderer.WriteLine(data.Description); + renderer.EnsureLine(); + } + + foreach (var link in data.Links) + WriteHeroAction(renderer, link.Label, link.Url); + + renderer.EnsureLine(); + } + + // Also used for card links: the shape is the same, a labelled link on its own line. private static void WriteHeroAction(LlmMarkdownRenderer renderer, string? label, string? url) { if (string.IsNullOrEmpty(label) || string.IsNullOrEmpty(url)) return; - renderer.WriteLine($"- [{label}]({LlmRenderingHelpers.MakeAbsoluteUrl(renderer, url)})"); + renderer.WriteLine($"- [{label}]({HubLinkForLlm(renderer, url)})"); } + // Hub links are authored as markdown paths. Strip the extension so the export matches how + // inline links render. The site path prefix is not applied: MakeAbsoluteUrl resolves against + // the canonical base URL instead. + private static string? HubLinkForLlm(LlmMarkdownRenderer renderer, string? url) => + LlmRenderingHelpers.MakeAbsoluteUrl(renderer, DirectiveLinkValidator.ToHref(url, null)); + private static void WriteImageBlock(LlmMarkdownRenderer renderer, ImageBlock imageBlock) { renderer.EnsureBlockSpacing(); diff --git a/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs index a95c196818..6e60bfbe24 100644 --- a/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs +++ b/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs @@ -286,6 +286,13 @@ protected override void Write(PlainTextRenderer renderer, DirectiveBlock obj) renderer.EnsureLine(); return; + // Deliberately contributes nothing. Section, card, and link titles are the tokens + // that would let a hub outrank the pages it links to on a specific query. + case ExploreBlock: + case CardGroupBlock: + case LinkCardBlock: + return; + case AgentSkillBlock agentSkillBlock: renderer.EnsureBlockSpacing(); renderer.WriteLine("Agent skill available"); diff --git a/src/Elastic.Markdown/Myst/YamlSerialization.cs b/src/Elastic.Markdown/Myst/YamlSerialization.cs index e5b4c5c1b2..6dbe9b5933 100644 --- a/src/Elastic.Markdown/Myst/YamlSerialization.cs +++ b/src/Elastic.Markdown/Myst/YamlSerialization.cs @@ -81,4 +81,6 @@ public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializ [YamlSerializable(typeof(ChangelogDirectiveConfigYaml))] [YamlSerializable(typeof(ChangelogDirectiveBundleConfigYaml))] [YamlSerializable(typeof(ListingFrontMatter))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.LinkCardData))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.LinkCardLink))] public partial class DocsBuilderYamlStaticContext; diff --git a/tests/authoring/Blocks/Hub/CardsAndExplore.fs b/tests/authoring/Blocks/Hub/CardsAndExplore.fs new file mode 100644 index 0000000000..6605e4487e --- /dev/null +++ b/tests/authoring/Blocks/Hub/CardsAndExplore.fs @@ -0,0 +1,261 @@ +// 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 +module ``AuthoringTests``.``block elements``.``hub``.``card and explore elements`` + +open Xunit +open authoring + +// {card-group} and {link-card} render two ways. Which one is decided entirely by whether an +// {explore} ancestor is present, not by any option. These tests pin both modes and the +// ancestor detection that switches between them. + +type ``card group standalone`` () = + static let markdown = Setup.Markdown """ +::::{card-group} +:title: Get hands-on +:id: hands-on +:intro: Follow a guided quickstart. + +:::{link-card} +title: Writing content +link: /index.md +description: Author a page and preview it. +links: + - label: Pages and links + url: /index.md +::: +:::: +""" + + [] + let ``renders a heading and a grid, not an accordion`` () = + markdown |> convertsToContainingHtml """ +
    +

    Get hands-on

    +

    Follow a guided quickstart.

    +
    +""" + + [] + let ``renders the card with its description`` () = + markdown |> convertsToContainingHtml """

    Author a page and preview it.

    """ + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``card group with the solutions variant`` () = + static let markdown = Setup.Markdown """ +::::{card-group} +:title: Browse by area +:variant: solutions + +:::{link-card} +title: Build the docs +::: +:::: +""" + + [] + let ``locks the three column grid`` () = + markdown |> convertsToContainingHtml """ +
      +
    • +
      +

      + Build the docs +

      +
      +
      • +
    +""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``card group nested in explore`` () = + static let markdown = Setup.Markdown """ +:::::{explore} +:id: explore +:title: Explore the docs +:intro: Organized by task. + +::::{card-group} +:title: Quick links +:id: quick-links + +:::{link-card} +title: Releases +description: This description is dropped in column mode. +links: + - label: Exporters + url: /index.md +::: +:::: + +::::{card-group} +:title: Authoring +:id: authoring + +:::{link-card} +title: Syntax +::: +:::: +::::: +""" + + [] + let ``renders the explore heading`` () = + markdown |> convertsToContainingHtml """ +
    +

    Explore the docs

    +

    Organized by task.

    +
    +""" + + // One snapshot covers what nesting changes: accordion mode, the first accordion open and + // the rest closed, and link cards as columns. It also pins the heading levels, so an + // Explore stack keeps a complete outline: section h2, accordion h3, column h4. + [] + let ``renders the accordion stack`` () = + markdown |> convertsToContainingHtml """ +
    + +
    + +

    Authoring

    + +     +
    +
      +
    • +

      + Syntax +

      +
      • +
    +
    +
    +
    +""" + + // A column is a pure link index, so the description is deliberately dropped. + [] + let ``drops the description in column mode`` () = + markdown |> doesNotConvertToContainingHtml """This description is dropped in column mode.""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``link card without a title`` () = + static let markdown = Setup.Markdown """ +:::{link-card} +description: No title here. +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "requires a `title`" + +type ``link card with a relative link`` () = + static let markdown = Setup.Markdown """ +:::{link-card} +title: Broken +links: + - label: Relative + url: nope.md +::: +""" + + [] + let ``rejects a relative path`` () = + markdown |> hasError "must be an absolute path starting with `/`" + +type ``link card with a missing target`` () = + static let markdown = Setup.Markdown """ +:::{link-card} +title: Broken +links: + - label: Missing + url: /does-not-exist.md +::: +""" + + [] + let ``errors on a link that does not resolve`` () = + markdown |> hasError "does not exist" + +type ``link card with a cross-link`` () = + static let markdown = Setup.Markdown """ +::::{card-group} +:title: Documentation this toolchain builds + +:::{link-card} +icon: elasticsearch +variant: es +title: Elasticsearch +description: Search and analytics documentation. +links: + - label: Elastic documentation + url: docs-content://get-started/index.md +::: +:::: +""" + + // Covers three things at once: the icon and variant accent, and that a cross-link resolves + // to a full URL without being treated as external. Inline links make the same distinction. + [] + let ``renders the icon and variant, and does not open the cross-link in a new tab`` () = + markdown |> convertsToContainingHtml """ +
      +
    • +
      + + + +

      + Elasticsearch +

      +
      +

      Search and analytics documentation.

      + +
      • +
    +""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors diff --git a/tests/authoring/authoring.fsproj b/tests/authoring/authoring.fsproj index 7f299d64f7..723a8d7ba8 100644 --- a/tests/authoring/authoring.fsproj +++ b/tests/authoring/authoring.fsproj @@ -56,6 +56,7 @@ + From c807d4d4808368624e794893f7b9af82cce83e57 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Fri, 14 Aug 2026 12:20:31 +0200 Subject: [PATCH 06/11] Hub pages 3/4: {get-started} (#3827) * Add {get-started} The onboarding section of a hub page. It gives a new reader one opinionated path to a first success, before they face the full link list. The section is optional. Keeps the top-level install and tutorial pair as first-class fields rather than treating it as prototype back-compatibility. The designs use exactly that shape: a copyable command beside a tutorial card, with numbered steps below. The install snippet renders inside `.highlight pre` with a language class, which is what the site's copy button and syntax highlighter already select on. Both work with no extra wiring, because the hub layout kept the markdown-content id. Steps take one of three shapes: plain, a whole-card link, or two or more equally weighted options side by side. Numbering is automatic and sits before the title, because the section describes a sequence and the number is what carries that. Drops the prototype's per-step icon field. The icons restate the step title, the number badge is already the visual anchor, and a schema field for decoration makes every author pick icons that then drift between hubs. The LLM export renders the steps as an ordered list with options as sub-items. The search body gets nothing, for the same reason as the other hub directives. Co-Authored-By: Claude Opus 5 * Apply review feedback to the get-started section Martijn's review on #3825 covered the whole page, so the same rules apply here. - Get started type moves onto the site's scale. The values it carried were 16px-root arithmetic against a 14px root, so every one rendered small. - Step numbers move from grey-70 to ink-light. grey-70 reads at 3.31:1 on white, short of the 4.5:1 minimum, and ink-light carries the same quiet weight at 7.03:1. Co-Authored-By: Claude Opus 5 * Raise get-started text to body size Martijn's point about tiny fonts applies to every piece of hub text. Step descriptions, option labels, option descriptions, option buttons, and the step links now read at the body size. The install command keeps 14px, which is what every other code block on the site renders at. Co-Authored-By: Claude Opus 5 * Use the shared arrow in get-started Both links that carry an arrow here send the reader onward out of the card, which is one of the two cases the site marks. They now use the same glyph and hover slide as every other hub arrow. The option button carries none, like every other button on the site. Co-Authored-By: Claude Opus 5 * Let a get-started section run to any number of steps Nothing in the schema limited the section to three steps. One CSS rule did: when a step carried options, the grid locked to two tracks, which suits one wide step and two others exactly. A fourth step left one card alone on a half-width row. The directive now counts the steps that flow in columns and sets the track count. Three across when they divide by three, two when they are even, so the last row is never short. A step carrying options still spans the full row and takes no track. Below 640px of available width the steps stack. The width is measured on the section rather than the viewport, because the left sidebar narrows the body. The example hub gains a fourth step, so the preview shows the new arrangement. Co-Authored-By: Claude Opus 5 * Give a linked step the shared card hover The step card hovered to a blue border while the other two card types hovered to grey. Blue also makes one step in a sequence look like the call to action. It now uses grey-80, the same treatment as {page-card} and a linked {link-card}. Co-Authored-By: Claude Opus 5 --------- Co-authored-by: Claude Opus 5 --- docs/_docset.yml | 1 + docs/examples/products/docs-builder.md | 26 +++ docs/syntax/get-started.md | 105 +++++++++ docs/syntax/hub-pages.md | 1 + .../Assets/markdown/hub.css | 216 ++++++++++++++++++ .../Myst/Directives/DirectiveBlockParser.cs | 3 + .../Myst/Directives/DirectiveHtmlRenderer.cs | 40 ++++ .../Myst/Directives/Hub/GetStartedBlock.cs | 121 ++++++++++ .../Myst/Directives/Hub/GetStartedView.cshtml | 116 ++++++++++ .../Directives/Hub/GetStartedViewModel.cs | 51 +++++ .../LlmMarkdown/LlmBlockRenderers.cs | 48 ++++ .../PlainText/PlainTextBlockRenderers.cs | 1 + .../Myst/YamlSerialization.cs | 3 + tests/authoring/Blocks/Hub/GetStarted.fs | 154 +++++++++++++ tests/authoring/authoring.fsproj | 1 + 15 files changed, 887 insertions(+) create mode 100644 docs/syntax/get-started.md create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/GetStartedBlock.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/GetStartedView.cshtml create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/GetStartedViewModel.cs create mode 100644 tests/authoring/Blocks/Hub/GetStarted.fs diff --git a/docs/_docset.yml b/docs/_docset.yml index e518cc269d..d18d7681cc 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -122,6 +122,7 @@ toc: - file: file_inclusion.md - file: footnotes.md - file: frontmatter.md + - file: get-started.md - file: hero.md - file: hub-pages.md - file: icons.md diff --git a/docs/examples/products/docs-builder.md b/docs/examples/products/docs-builder.md index 1b13353a5d..1c15e9c8fb 100644 --- a/docs/examples/products/docs-builder.md +++ b/docs/examples/products/docs-builder.md @@ -12,6 +12,32 @@ description: docs-builder documentation. Build, validate, and publish Elastic do :tertiary-action: [Explore docs-builder](#explore) ::: +:::{get-started} +title: Get started in 4 steps +intro: Install docs-builder, write your first page, then preview and publish it. +steps: + - title: Install docs-builder + options: + - label: Build from source + description: Clone the repository and build the CLI yourself. + code: dotnet build + language: sh + - label: Run in a container + description: No local install needed. + url: /getting-started/installation.md + url-label: Container setup + - title: Write your first page + description: Author Markdown, add links, and use the directive set. + link: /getting-started/writing-content.md + link-label: Start writing + - title: Preview and publish + description: Serve the site locally with live reload, then publish it. + link: /getting-started/serve.md + link-label: Serve locally + - title: Validate the build + description: Check links, syntax, and frontmatter before you open a pull request. +::: + ::::{card-group} :title: Get hands-on :id: hands-on diff --git a/docs/syntax/get-started.md b/docs/syntax/get-started.md new file mode 100644 index 0000000000..b20baaa8ee --- /dev/null +++ b/docs/syntax/get-started.md @@ -0,0 +1,105 @@ +# Get started + +The onboarding section of a [hub page](hub-pages.md). It gives a new reader one opinionated path to a first success, before they face the full link list. + +The section is optional. Skip it when the hero already says what to do next. + +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered section. + +## Basic + +A hub's onboarding section is a numbered list of steps. Use as many as the path needs. The first step often offers two equally weighted ways to start, and the rest are single links. + +```markdown +:::{get-started} +title: Get started in 3 steps +intro: Install docs-builder, write your first page, then preview and publish it. +steps: + - title: Install docs-builder + options: + - label: Install locally + description: Install the CLI on your machine. + code: curl -sSL https://ela.st/docs-builder-install | sh + language: sh + - label: Run in a container + description: No local install needed. + url: /getting-started/installation.md + url-label: Container setup + - title: Write your first page + description: Author Markdown, add links, and use the directive set. + link: /getting-started/writing-content.md + link-label: Start writing + - title: Preview and publish + description: Serve the site locally with live reload, then publish it. + link: /getting-started/serve.md + link-label: Serve locally +::: +``` + +The body is YAML, not markdown, like [`{link-card}`](link-card.md). + +## Schema + +| Field | Notes | +|---|---| +| `title` | **Required.** H2 heading. | +| `intro` | One-line lead below the heading. | +| `steps` | The numbered steps. | + +Everything the section offers lives inside a step. An install command belongs in `steps[0].options[]`, which keeps the whole path inside the numbered sequence. + +A command in a step option goes through the standard code block, so it gets syntax highlighting and a copy button like every other code block on the site. + +Every field except `title` is optional. The [example hub](../examples/products/docs-builder.md) uses each one once, and shows all three step shapes, so you can start from it and delete what you do not need. + + +## How many steps + +There is no fixed number. The layout arranges whatever you write: + +- A step carrying `options` spans the full row. +- The remaining steps share the row, three across when they divide by three, two when they are even, so the last row is never short. +- Below a narrow width the steps stack into one column. + +Keep the list short enough to read as one path. Four steps still scan. Ten do not. + +## Step shapes + +A step takes one of three shapes. + +**Plain.** A `title` and a `description`. Nothing is clickable. + +```yaml +- title: Preview and publish + description: Serve the site locally, then publish it. +``` + +**Link.** Add `link` and `link-label`, and the whole step card becomes clickable. + +```yaml +- title: Write your first page + description: Author markdown, add links, and use the directive set. + link: /getting-started/writing-content.md + link-label: Start writing +``` + +**Options.** Add `options` for two or more equally weighted paths, shown side by side. Each option takes a `label`, a `description`, and either a copyable `code` snippet with its `language`, or a `url` with a `url-label`. + +```yaml +- title: Preview and publish + options: + - label: Preview locally + description: Serve the site with live reload while you write. + code: docs-builder serve + language: sh + - label: Publish + description: Build the site and publish it. + url: /getting-started/publish.md + url-label: How to publish +``` + +Steps are numbered automatically, in source order. The number sits before the title, because the section describes a sequence and the number is what carries that. + +## Links + +Every `steps[].link` and `options[].url` validates at build time, using the same forms as [`{link-card}`](link-card.md#links). diff --git a/docs/syntax/hub-pages.md b/docs/syntax/hub-pages.md index 048ed37e61..e01bec4672 100644 --- a/docs/syntax/hub-pages.md +++ b/docs/syntax/hub-pages.md @@ -56,6 +56,7 @@ Write both deliberately. The search body indexes the hero title and description | [`{hero}`](hero.md) | Identity band. Carries the product icon, the page title, a description, and up to three actions. | | [`{card-group}`](card-group.md) | Section heading and card grid. Renders as an accordion inside `{explore}`. | | [`{link-card}`](link-card.md) | One card: title, description, and a list of links. Renders as a link column inside `{explore}`. | +| [`{get-started}`](get-started.md) | Onboarding funnel. An install command, a tutorial link, and numbered steps. | | [`{explore}`](explore.md) | The browse-everything section. A stack of collapsible accordions. | ## Page skeleton diff --git a/src/Elastic.Documentation.Site/Assets/markdown/hub.css b/src/Elastic.Documentation.Site/Assets/markdown/hub.css index 0095fe2326..564cb73ee3 100644 --- a/src/Elastic.Documentation.Site/Assets/markdown/hub.css +++ b/src/Elastic.Documentation.Site/Assets/markdown/hub.css @@ -154,6 +154,222 @@ flex-shrink: 0; } + /* Get started ------------------------------------------------------ */ + /* A container, not the viewport: the left sidebar narrows the body, so the step + grid has to answer to the space it actually has. */ + .hub-get-started { + @apply mx-auto w-full max-w-5xl; + container-type: inline-size; + margin-bottom: 56px; + scroll-margin-top: 96px; + } + .hub-get-started .hub-get-started-title { + margin: 0 0 8px; + font-size: var(--text-xl); + font-weight: 700; + color: var(--color-ink); + } + .hub-get-started .hub-get-started-intro { + margin: 0 0 20px; + font-size: var(--text-base); + color: var(--color-ink-light, #4c4c4c); + line-height: 1.5; + } + .hub-get-started .hub-get-started-install { + position: relative; + flex: 1 1 380px; + min-width: 0; + margin: 0; + } + .hub-get-started .hub-get-started-install pre { + margin: 0; + padding: 12px 16px; + overflow-x: auto; + background: var(--color-ink-navy); + border-radius: 10px; + } + .hub-get-started .hub-get-started-install code { + font-family: var(--font-mono, monospace); + font-size: var(--text-sm); + color: var(--color-white); + background: transparent; + } + + /* The track count is authored, not inferred from the width: the directive counts the + steps that flow in columns and sets --hub-step-columns, so a section of any length + fills its rows evenly instead of leaving a short last row. */ + .hub-get-started .hub-get-started-steps { + @apply grid gap-4; + grid-template-columns: repeat( + var(--hub-step-columns, 2), + minmax(0, 1fr) + ); + margin: 0; + padding: 0; + list-style: none; + } + .hub-get-started .hub-get-started-step { + @apply relative flex flex-col; + padding: 20px; + background: var(--color-white); + border: 1px solid var(--color-grey-20); + border-radius: 14px; + } + .hub-get-started .hub-get-started-step-head { + @apply flex items-center; + gap: 12px; + margin-bottom: 10px; + padding-right: 34px; + } + .hub-get-started .hub-get-started-step-num { + position: absolute; + top: 20px; + right: 20px; + font-size: var(--text-base); + font-weight: 600; + /* grey-70 reads at 3.31:1 on white, short of the 4.5:1 minimum. ink-light + carries the same quiet weight at 7.03:1 and is what other secondary text + on the page already uses. */ + color: var(--color-ink-light); + letter-spacing: 0.06em; + } + .hub-get-started .hub-get-started-step-title { + margin: 0; + font-size: var(--text-base); + font-weight: 700; + color: var(--color-ink-dark); + } + .hub-get-started .hub-get-started-step-desc { + margin: 0; + font-size: var(--text-base); + color: var(--color-ink-light, #4c4c4c); + line-height: 1.45; + } + + /* Below this the tracks are too narrow to hold a step title and a description. */ + @container (max-width: 640px) { + .hub-get-started .hub-get-started-steps { + grid-template-columns: 1fr; + } + } + + /* A step offering equally weighted options spans the full row, whatever the track count. */ + .hub-get-started .hub-get-started-step-wide { + grid-column: 1 / -1; + container-type: inline-size; + } + .hub-get-started .hub-get-started-options { + display: grid; + grid-template-columns: 1fr 1fr; + margin-top: 16px; + padding-top: 16px; + border-top: 1px solid var(--color-grey-20); + } + .hub-get-started .hub-get-started-option { + @apply flex flex-col; + gap: 10px; + padding-right: 28px; + } + .hub-get-started .hub-get-started-option + .hub-get-started-option { + padding-right: 0; + padding-left: 28px; + border-left: 1px solid var(--color-grey-20); + } + .hub-get-started .hub-get-started-option-label { + font-size: var(--text-base); + font-weight: 700; + color: var(--color-ink-dark); + } + .hub-get-started .hub-get-started-option-desc { + margin: 0; + font-size: var(--text-base); + color: var(--color-ink-light, #4c4c4c); + line-height: 1.45; + } + .hub-get-started .hub-get-started-option .hub-get-started-install { + flex: none; + width: 100%; + margin-top: auto; + } + .hub-get-started .hub-get-started-option-btn { + @apply inline-flex items-center justify-center; + gap: 8px; + width: 100%; + min-height: 48px; + margin-top: auto; + padding: 0 18px; + font-size: var(--text-base); + font-weight: 600; + color: var(--color-ink-dark); + background: var(--color-white); + border: 1px solid var(--color-ink-dark); + border-radius: 8px; + transition: + background 0.15s ease, + border-color 0.15s ease; + } + .hub-get-started .hub-get-started-option-btn:hover, + .hub-get-started .hub-get-started-option-btn:focus-visible { + background: var(--color-grey-10); + border-color: var(--color-ink-dark); + color: var(--color-ink-dark); + } + .hub-get-started .hub-get-started-option-link { + @apply inline-flex items-center gap-1; + align-self: flex-start; + font-size: var(--text-base); + font-weight: 600; + color: var(--color-blue-elastic-100, #0b64dd); + } + .hub-get-started .hub-get-started-option-link:hover, + .hub-get-started .hub-get-started-option-link:focus-visible { + text-decoration: underline; + } + @container (max-width: 560px) { + .hub-get-started .hub-get-started-options { + grid-template-columns: 1fr; + } + .hub-get-started .hub-get-started-option { + padding-right: 0; + } + .hub-get-started .hub-get-started-option + .hub-get-started-option { + padding-left: 0; + padding-top: 16px; + margin-top: 4px; + border-left: 0; + border-top: 1px solid var(--color-grey-20); + } + } + + /* Steps 02/03 are clickable link cards. */ + .hub-get-started .hub-get-started-step-link { + padding: 0; + transition: + box-shadow 0.15s, + border-color 0.15s; + } + /* Same hover treatment as every other card that is itself a link. Blue would make + one step look like the call to action when they are a sequence. */ + .hub-get-started .hub-get-started-step-link:hover, + .hub-get-started .hub-get-started-step-link:focus-visible { + border-color: var(--color-grey-80); + box-shadow: 0 1px 4px rgb(0 0 0 / 0.07); + } + .hub-get-started .hub-get-started-step-anchor { + @apply flex h-full flex-col; + padding: 20px; + color: inherit; + text-decoration: none; + } + .hub-get-started .hub-get-started-step-arrow { + @apply inline-flex items-center gap-1; + margin-top: auto; + padding-top: 14px; + font-size: var(--text-base); + font-weight: 600; + color: var(--color-blue-elastic-100, #0b64dd); + } + /* Zone (section heading) ------------------------------------------ */ .hub-zone { @apply mx-auto w-full max-w-5xl; diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs index 565a9ab7c0..add4cf3626 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs @@ -150,6 +150,9 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor) if (info.IndexOf("{link-card}") > 0) return new LinkCardBlock(this, context); + if (info.IndexOf("{get-started}") > 0) + return new GetStartedBlock(this, context); + if (info.IndexOf("{agent-skill}") > 0) return new AgentSkillBlock(this, context); diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs index 7c4f5f6f1e..31057f6bd0 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs @@ -117,6 +117,9 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo case LinkCardBlock linkCardBlock: WriteLinkCard(renderer, linkCardBlock); return; + case GetStartedBlock getStartedBlock: + WriteGetStarted(renderer, getStartedBlock); + return; case PageCardBlock pageCardBlock: WritePageCard(renderer, pageCardBlock); return; @@ -267,6 +270,43 @@ private static void WriteLinkCard(HtmlRenderer renderer, LinkCardBlock block) RenderRazorSlice(slice, renderer); } + private static void WriteGetStarted(HtmlRenderer renderer, GetStartedBlock block) + { + var data = block.Data; + var steps = new List(data.Steps.Length); + for (var i = 0; i < data.Steps.Length; i++) + { + var step = data.Steps[i]; + steps.Add(new GetStartedStepViewModel + { + Number = i + 1, + Title = step.Title, + DescriptionHtml = RenderInlineMarkdown(step.Description), + Link = step.Link, + LinkLabel = step.LinkLabel, + Options = [.. step.Options.Select(option => new GetStartedOptionViewModel + { + Label = option.Label, + DescriptionHtml = RenderInlineMarkdown(option.Description), + Code = option.Code, + Language = option.Language, + Url = option.Url, + UrlLabel = option.UrlLabel + })] + }); + } + + var slice = GetStartedView.Create(new GetStartedViewModel + { + DirectiveBlock = block, + Title = data.Title, + IntroHtml = RenderInlineMarkdown(data.Intro), + Steps = steps, + SitePathPrefix = block.Build.UrlPathPrefix + }); + RenderRazorSlice(slice, renderer); + } + // The hero description is a directive option, not a body block, so it never reaches // the document pipeline. Render it with the default Markdig pipeline for basic inline // markup. Substitutions, roles, and link validation do not apply inside this option. diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedBlock.cs b/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedBlock.cs new file mode 100644 index 0000000000..d2915faa2a --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedBlock.cs @@ -0,0 +1,121 @@ +// 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.Markdown.Diagnostics; +using YamlDotNet.Core; +using YamlDotNet.Serialization; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// The first hub-body section: a short onboarding funnel with an intro line, an +/// optional install snippet, an optional tutorial link, and a set of numbered +/// steps. The schema is YAML-formatted in the directive body for predictable +/// structure. +/// +/// +/// +/// :::{get-started} +/// title: Get started in 3 steps +/// intro: Spin up Kibana, connect your data, and start exploring in minutes. +/// ::: +/// +/// +public class GetStartedBlock(DirectiveBlockParser parser, ParserContext context) + : DirectiveBlock(parser, context) +{ + public override string Directive => "get-started"; + + public GetStartedData Data { get; private set; } = GetStartedData.Empty; + + public override void FinalizeAndValidate(ParserContext context) + { + var yaml = HubYamlBody.Extract(this, new BuildContextFileReader(Build.ReadFileSystem)); + if (yaml is null) + { + this.EmitError("{get-started} requires a YAML body. See the get-started directive docs."); + return; + } + + try + { + Data = YamlSerialization.Deserialize(yaml, Build.ProductsConfiguration) ?? GetStartedData.Empty; + } + catch (YamlException ex) + { + this.EmitError($"{{get-started}} YAML parse error: {ex.Message}"); + return; + } + + if (string.IsNullOrWhiteSpace(Data.Title)) + this.EmitError("{get-started} requires a `title` field in its YAML body."); + + + foreach (var step in Data.Steps) + { + if (!string.IsNullOrWhiteSpace(step.Link)) + step.Link = DirectiveLinkValidator.ValidateAndResolve(step.Link, this, context); + foreach (var option in step.Options) + option.Url = DirectiveLinkValidator.ValidateAndResolve(option.Url, this, context); + } + } +} + +[YamlSerializable] +public record GetStartedData +{ + [YamlMember(Alias = "title")] + public string? Title { get; set; } + + [YamlMember(Alias = "intro")] + public string? Intro { get; set; } + + [YamlMember(Alias = "steps")] + public GetStartedStep[] Steps { get; set; } = []; + + public static GetStartedData Empty { get; } = new(); +} + +[YamlSerializable] +public record GetStartedStep +{ + [YamlMember(Alias = "title")] + public string? Title { get; set; } + + [YamlMember(Alias = "description")] + public string? Description { get; set; } + + /// When set, the whole step card links here. + [YamlMember(Alias = "link")] + public string? Link { get; set; } + + [YamlMember(Alias = "link-label")] + public string? LinkLabel { get; set; } + + /// Two-or-more equally-weighted start options rendered side by side. + [YamlMember(Alias = "options")] + public GetStartedStepOption[] Options { get; set; } = []; +} + +[YamlSerializable] +public record GetStartedStepOption +{ + [YamlMember(Alias = "label")] + public string? Label { get; set; } + + [YamlMember(Alias = "description")] + public string? Description { get; set; } + + [YamlMember(Alias = "code")] + public string? Code { get; set; } + + [YamlMember(Alias = "language")] + public string? Language { get; set; } + + [YamlMember(Alias = "url")] + public string? Url { get; set; } + + [YamlMember(Alias = "url-label")] + public string? UrlLabel { get; set; } +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedView.cshtml b/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedView.cshtml new file mode 100644 index 0000000000..3022ef2479 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedView.cshtml @@ -0,0 +1,116 @@ +@inherits RazorSlice + +
    +
    + @if (!string.IsNullOrWhiteSpace(Model.Title)) + { +

    @Model.Title

    + } + @if (!string.IsNullOrWhiteSpace(Model.IntroHtml)) + { +

    @(new HtmlString(Model.IntroHtml))

    + } +
    + + @if (Model.Steps.Count > 0) + { +
      + @foreach (var step in Model.Steps) + { + @if (step.Options.Count > 0) + { +
    1. +
      + + @if (!string.IsNullOrWhiteSpace(step.Title)) + { +

      @step.Title

      + } +
      + @if (!string.IsNullOrWhiteSpace(step.DescriptionHtml)) + { +

      @(new HtmlString(step.DescriptionHtml))

      + } +
      + @foreach (var option in step.Options) + { +
      + @if (!string.IsNullOrWhiteSpace(option.Label)) + { + @option.Label + } + @if (!string.IsNullOrWhiteSpace(option.DescriptionHtml)) + { +

      @(new HtmlString(option.DescriptionHtml))

      + } + @if (!string.IsNullOrWhiteSpace(option.Code)) + { +
      + 
      @option.Code
      +
      + } + @if (!string.IsNullOrWhiteSpace(option.Url)) + { + @if (!string.IsNullOrWhiteSpace(option.Code)) + { + + @(string.IsNullOrWhiteSpace(option.UrlLabel) ? "Learn more" : option.UrlLabel) + + + } + else + { + @(string.IsNullOrWhiteSpace(option.UrlLabel) ? "Get started" : option.UrlLabel) + } + } +
      + } +
      +
      2. + } + else if (!string.IsNullOrWhiteSpace(step.Link)) + { +
    2. + +
      + + @if (!string.IsNullOrWhiteSpace(step.Title)) + { +

      @step.Title

      + } +
      + @if (!string.IsNullOrWhiteSpace(step.DescriptionHtml)) + { +

      @(new HtmlString(step.DescriptionHtml))

      + } + +       +
      3. + } + else + { +
    3. +
      + + @if (!string.IsNullOrWhiteSpace(step.Title)) + { +

      @step.Title

      + } +
      + @if (!string.IsNullOrWhiteSpace(step.DescriptionHtml)) + { +

      @(new HtmlString(step.DescriptionHtml))

      + } +
      4. + } + } +
    + } +
    diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedViewModel.cs new file mode 100644 index 0000000000..7c6c8faa85 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/GetStartedViewModel.cs @@ -0,0 +1,51 @@ +// 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.Myst.Directives.Hub; + +public class GetStartedViewModel : HubDirectiveViewModel +{ + public required string? Title { get; init; } + public required string? IntroHtml { get; init; } + public required IReadOnlyList Steps { get; init; } + + /// + /// Track count for the step grid. A step carrying options spans the full row, so only the + /// remaining steps compete for columns. The count is picked to divide them evenly and leave + /// no short last row: three across when they divide by three, two when they are even, + /// otherwise as many as there are, up to three. + /// + public int StepColumns + { + get + { + var inFlow = Steps.Count(s => s.Options.Count == 0); + if (inFlow == 0) + return 1; + if (inFlow % 3 == 0) + return 3; + return inFlow % 2 == 0 ? 2 : inFlow < 3 ? inFlow : 3; + } + } +} + +public sealed record GetStartedStepViewModel +{ + public required int Number { get; init; } + public required string? Title { get; init; } + public required string? DescriptionHtml { get; init; } + public required string? Link { get; init; } + public required string? LinkLabel { get; init; } + public required IReadOnlyList Options { get; init; } +} + +public sealed record GetStartedOptionViewModel +{ + public required string? Label { get; init; } + public required string? DescriptionHtml { get; init; } + public required string? Code { get; init; } + public required string? Language { get; init; } + public required string? Url { get; init; } + public required string? UrlLabel { get; init; } +} diff --git a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs index a8de739529..0a40733226 100644 --- a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs +++ b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs @@ -514,6 +514,9 @@ protected override void Write(LlmMarkdownRenderer renderer, DirectiveBlock obj) case LinkCardBlock linkCardBlock: WriteLinkCardBlock(renderer, linkCardBlock); return; + case GetStartedBlock getStartedBlock: + WriteGetStartedBlock(renderer, getStartedBlock); + return; } // Ensure single empty line before directive @@ -580,6 +583,51 @@ private static void WriteHeroBlock(LlmMarkdownRenderer renderer, HeroBlock heroB renderer.EnsureLine(); } + // The onboarding path is a sequence, so it exports as an ordered list. Options under a step + // become sub-items, each with its command or its link. + private static void WriteGetStartedBlock(LlmMarkdownRenderer renderer, GetStartedBlock block) + { + var data = block.Data; + renderer.EnsureBlockSpacing(); + + if (!string.IsNullOrEmpty(data.Title)) + { + renderer.WriteLine($"## {data.Title}"); + renderer.EnsureLine(); + } + if (!string.IsNullOrEmpty(data.Intro)) + { + renderer.WriteLine(data.Intro); + renderer.EnsureLine(); + } + + for (var i = 0; i < data.Steps.Length; i++) + WriteGetStartedStep(renderer, data.Steps[i], i + 1); + + renderer.EnsureLine(); + } + + private static void WriteGetStartedStep(LlmMarkdownRenderer renderer, GetStartedStep step, int number) + { + renderer.EnsureLine(); + var title = string.IsNullOrEmpty(step.Link) + ? step.Title + : $"[{step.Title}]({HubLinkForLlm(renderer, step.Link)})"; + renderer.WriteLine($"{number}. {title}"); + + if (!string.IsNullOrEmpty(step.Description)) + renderer.WriteLine($" {step.Description}"); + + foreach (var option in step.Options) + { + renderer.WriteLine($" - {option.Label}: {option.Description}"); + if (!string.IsNullOrEmpty(option.Code)) + renderer.WriteLine($" `{option.Code}`"); + if (!string.IsNullOrEmpty(option.Url)) + renderer.WriteLine($" [{option.UrlLabel ?? "Get started"}]({HubLinkForLlm(renderer, option.Url)})"); + } + } + // The curated grouping of links is what a hub page is for, so the export keeps the whole // structure: each section becomes a heading and each card a titled link list. private static void WriteExploreBlock(LlmMarkdownRenderer renderer, ExploreBlock block) diff --git a/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs index 6e60bfbe24..3b01468f1d 100644 --- a/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs +++ b/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs @@ -291,6 +291,7 @@ protected override void Write(PlainTextRenderer renderer, DirectiveBlock obj) case ExploreBlock: case CardGroupBlock: case LinkCardBlock: + case GetStartedBlock: return; case AgentSkillBlock agentSkillBlock: diff --git a/src/Elastic.Markdown/Myst/YamlSerialization.cs b/src/Elastic.Markdown/Myst/YamlSerialization.cs index 6dbe9b5933..36bb30ce0a 100644 --- a/src/Elastic.Markdown/Myst/YamlSerialization.cs +++ b/src/Elastic.Markdown/Myst/YamlSerialization.cs @@ -83,4 +83,7 @@ public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializ [YamlSerializable(typeof(ListingFrontMatter))] [YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.LinkCardData))] [YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.LinkCardLink))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.GetStartedData))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.GetStartedStep))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.GetStartedStepOption))] public partial class DocsBuilderYamlStaticContext; diff --git a/tests/authoring/Blocks/Hub/GetStarted.fs b/tests/authoring/Blocks/Hub/GetStarted.fs new file mode 100644 index 0000000000..7ff8dd1eb0 --- /dev/null +++ b/tests/authoring/Blocks/Hub/GetStarted.fs @@ -0,0 +1,154 @@ +// 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 +module ``AuthoringTests``.``block elements``.``hub``.``get started elements`` + +open Xunit +open authoring + +type ``get started with a title and intro`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +title: Get started in 3 steps +intro: Install, write, preview. +steps: + - title: Install + description: Install the CLI. +::: +""" + + [] + let ``renders the heading`` () = + markdown |> convertsToContainingHtml """

    Get started in 3 steps

    """ + + [] + let ``numbers steps from one, zero padded`` () = + markdown |> convertsToContainingRawHtml """""" + + // Nothing renders between the intro and the numbered list. The section is the steps. + [] + let ``renders nothing above the steps`` () = + markdown |> doesNotConvertToContainingHtml "hub-get-started-actions" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``get started with a link step`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +title: Get started +steps: + - title: Write your first page + description: Author markdown. + link: /index.md + link-label: Start writing +::: +""" + + [] + let ``makes the whole step clickable`` () = + markdown |> convertsToContainingHtml """Start writing""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``get started with option steps`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +title: Get started +steps: + - title: Preview and publish + options: + - label: Preview locally + description: Serve with live reload. + code: docs-builder serve + language: sh + - label: Publish + description: Build and publish. + url: /index.md + url-label: How to publish +::: +""" + + [] + let ``renders both options`` () = + markdown |> convertsToContainingHtml """Preview locally""" + + [] + let ``renders the option command`` () = + markdown |> convertsToContainingHtml """docs-builder serve""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``get started with a relative step link`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +title: Get started +steps: + - title: Broken + link: nope.md +::: +""" + + [] + let ``rejects a relative path`` () = + markdown |> hasError "must be an absolute path starting with `/`" + +type ``get started without a body`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "{get-started}" + +// The section is not fixed at three steps. The track count follows the steps that flow in +// columns, so the last row is never short. A step carrying options spans the full row and +// takes no track. +type ``get started with four steps`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +title: Get started +steps: + - title: Install + options: + - label: Source + code: dotnet build + - label: Container + url: /index.md + - title: Write + - title: Preview + - title: Validate +::: +""" + + [] + let ``lays the three remaining steps across three tracks`` () = + markdown |> convertsToContainingRawHtml """
      """ + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``get started with five steps`` () = + static let markdown = Setup.Markdown """ +:::{get-started} +title: Get started +steps: + - title: One + - title: Two + - title: Three + - title: Four +::: +""" + + // Four steps divide evenly into two rows of two, so they take two tracks rather than + // three with a single step stranded on the last row. + [] + let ``pairs four steps into two tracks`` () = + markdown |> convertsToContainingRawHtml """
        """ + + [] + let ``has no errors`` () = markdown |> hasNoErrors diff --git a/tests/authoring/authoring.fsproj b/tests/authoring/authoring.fsproj index 723a8d7ba8..4bd3e42fe5 100644 --- a/tests/authoring/authoring.fsproj +++ b/tests/authoring/authoring.fsproj @@ -57,6 +57,7 @@ + From 5fabcbb967d5acad933820c40c1da90c901a52e8 Mon Sep 17 00:00:00 2001 From: Florent LB Date: Fri, 14 Aug 2026 12:20:32 +0200 Subject: [PATCH 07/11] Hub pages 4/4: {whats-new} (#3829) * Add {whats-new} A recency panel for a hub page. A reader who bookmarks a hub wants a quick answer to "what changed recently" without hunting through release notes. The panel content moves out of the build tool. The prototype reads config/whats-new.yml from docs-builder, which means a writer editing a highlight card opens a pull request against the build tool and waits for a release. It now reads hub-whats-new.yml from the root of the current documentation set, beside changelog.yml and redirects.yml. That makes the directive documentation-set scoped. It cannot render another repository's panel, and this is a constraint rather than a syntax gap. Cross-link resolution maps pages through the link index, and a YAML data file is not a page. In an isolated build the other repository is not checked out, so there would be no file to read. Every hub page lives in the same repository as its content file, so the limit costs nothing today. The common case stays one line, `:product: `. Omitting it accepts the same schema as an inline YAML body, for a one-off panel. Adds containsRawHtml to the authoring assertions. The pretty-printed comparison only matches a childless element or a snapshot taken from the outermost element of the directive output, so asserting a class on a container previously meant snapshotting its whole subtree. Follow-up, not in this change: a skill in docs-content that updates hub-whats-new.yml from the release notes of each product that has a hub page. Co-Authored-By: Claude Opus 5 * Apply review feedback to the what's new section Martijn's review on #3825 covered the whole page, so the same rule applies here. What's new type moves onto the site's scale. Every raw font size in hub.css is now a scale token. Co-Authored-By: Claude Opus 5 * Raise what's new text to body size, and stop shouting the date Martijn's point about tiny fonts applies to every piece of hub text. Card descriptions, release note links, and the footer now read at the body size. Card meta sits one step down at 14px. No hub text renders below 14px, and nothing uses the smallest step of the scale. The card date no longer forces uppercase. It is authored, so it keeps the casing the writer chose. The example data and the syntax page now use sentence case to match. Co-Authored-By: Claude Opus 5 * Use the shared arrow in what's new The card link and the upgrade link both send the reader onward, which is one of the two cases the site marks with an arrow. They now use the same glyph and hover slide as every other hub arrow. No hub directive draws its own arrow any more. Co-Authored-By: Claude Opus 5 * Give a what's new card the shared card hover The card hovered to a pale blue border reading 2.12:1 against white, so the state was barely visible. It now uses grey-80 at 4.15:1, the same treatment as every other card on a hub page that is itself a link. Every card that is a link now hovers the same way, and every state border in the hub clears the 3:1 ratio. Co-Authored-By: Claude Opus 5 --------- Co-authored-by: Claude Opus 5 --- docs/_docset.yml | 1 + docs/examples/products/docs-builder.md | 4 + docs/hub-whats-new.yml | 49 +++++ docs/syntax/hub-pages.md | 1 + docs/syntax/whats-new.md | 81 ++++++++ .../Assets/markdown/hub.css | 159 ++++++++++++++++ .../Myst/Directives/DirectiveBlockParser.cs | 3 + .../Myst/Directives/DirectiveHtmlRenderer.cs | 14 ++ .../Myst/Directives/Hub/WhatsNewBlock.cs | 173 ++++++++++++++++++ .../Myst/Directives/Hub/WhatsNewView.cshtml | 117 ++++++++++++ .../Myst/Directives/Hub/WhatsNewViewModel.cs | 10 + .../LlmMarkdown/LlmBlockRenderers.cs | 54 ++++++ .../PlainText/PlainTextBlockRenderers.cs | 1 + .../Myst/YamlSerialization.cs | 3 + tests/authoring/Blocks/Hub/WhatsNew.fs | 110 +++++++++++ tests/authoring/authoring.fsproj | 1 + 16 files changed, 781 insertions(+) create mode 100644 docs/hub-whats-new.yml create mode 100644 docs/syntax/whats-new.md create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewBlock.cs create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewView.cshtml create mode 100644 src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewViewModel.cs create mode 100644 tests/authoring/Blocks/Hub/WhatsNew.fs diff --git a/docs/_docset.yml b/docs/_docset.yml index d18d7681cc..89f358d3a2 100644 --- a/docs/_docset.yml +++ b/docs/_docset.yml @@ -146,6 +146,7 @@ toc: - file: tables.md - file: tabs.md - file: titles.md + - file: whats-new.md # Examples - folder: examples diff --git a/docs/examples/products/docs-builder.md b/docs/examples/products/docs-builder.md index 1c15e9c8fb..2457e2067a 100644 --- a/docs/examples/products/docs-builder.md +++ b/docs/examples/products/docs-builder.md @@ -38,6 +38,10 @@ steps: description: Check links, syntax, and frontmatter before you open a pull request. ::: +:::{whats-new} +:product: docs-builder +::: + ::::{card-group} :title: Get hands-on :id: hands-on diff --git a/docs/hub-whats-new.yml b/docs/hub-whats-new.yml new file mode 100644 index 0000000000..450b3a6c48 --- /dev/null +++ b/docs/hub-whats-new.yml @@ -0,0 +1,49 @@ +# Content for the {whats-new} panel on hub pages, keyed by product. +# +# This file lives at the root of the documentation set, alongside changelog.yml and +# redirects.yml, so a writer edits it without touching the build tool. A hub page renders +# a panel from it with one line: `:product: `. +# +# The directive reads this file from the current documentation set only. It cannot render +# another repository's panel. +products: + docs-builder: + title: What's new in docs-builder + id: whats-new + intro: Recent additions to the toolchain and the syntax it understands. + # More than one release stream can be listed here. + release-links: + - label: Release notes + url: /data/release-notes/index.md + - label: Changelog reference + url: /data/release-notes/overview.md + upgrade-link: + label: Upgrade docs-builder + url: /getting-started/installation.md + items: + - title: Hub pages + description: A product-scoped landing page composed entirely from directives. + link: /syntax/hub-pages.md + date: Aug 2026 + tag: Syntax + featured: true + - title: Explore sections + description: Collapse a long link list into a stack of accordions. + link: /syntax/explore.md + date: Aug 2026 + tag: Syntax + - title: Get started sections + description: One opinionated onboarding path, with a copyable install command. + link: /syntax/get-started.md + date: Aug 2026 + tag: Syntax + - title: Link cards + description: A card with a title, a description, and a validated link list. + link: /syntax/link-card.md + date: Aug 2026 + tag: Syntax + - title: Card groups + description: Group related cards under a heading, or as one accordion. + link: /syntax/card-group.md + date: Aug 2026 + tag: Syntax diff --git a/docs/syntax/hub-pages.md b/docs/syntax/hub-pages.md index e01bec4672..431f8d8e5c 100644 --- a/docs/syntax/hub-pages.md +++ b/docs/syntax/hub-pages.md @@ -57,6 +57,7 @@ Write both deliberately. The search body indexes the hero title and description | [`{card-group}`](card-group.md) | Section heading and card grid. Renders as an accordion inside `{explore}`. | | [`{link-card}`](link-card.md) | One card: title, description, and a list of links. Renders as a link column inside `{explore}`. | | [`{get-started}`](get-started.md) | Onboarding funnel. An install command, a tutorial link, and numbered steps. | +| [`{whats-new}`](whats-new.md) | Recency panel. Dated highlight cards, authored once in `hub-whats-new.yml`. | | [`{explore}`](explore.md) | The browse-everything section. A stack of collapsible accordions. | ## Page skeleton diff --git a/docs/syntax/whats-new.md b/docs/syntax/whats-new.md new file mode 100644 index 0000000000..27c1c1caf1 --- /dev/null +++ b/docs/syntax/whats-new.md @@ -0,0 +1,81 @@ +# What's new + +A recency panel for a [hub page](hub-pages.md). A reader who bookmarks a hub wants a quick answer to "what changed recently" without hunting through release notes. + +See the [docs-builder documentation hub](../examples/products/docs-builder.md) for a rendered panel. + +## Basic + +The common case is one line: + +```markdown +:::{whats-new} +:product: docs-builder +::: +``` + +`:product:` looks the key up in `hub-whats-new.yml` at the root of the documentation set. The content is authored once there and every page that names the same product renders the same panel. One edit updates them all. + +## Where the content lives + +`hub-whats-new.yml` sits beside `changelog.yml` and `redirects.yml`, at the root of the content repository rather than in the build tool. A writer edits the panel without opening docs-builder, and without waiting for a docs-builder release. + +```yaml +products: + docs-builder: + title: What's new in docs-builder + id: whats-new + intro: Recent additions to the toolchain. + release-links: + - label: View release notes + url: /data/release-notes/index.md + items: + - title: Hub pages + description: A product-scoped landing page composed entirely from directives. + link: /syntax/hub-pages.md + date: Aug 2026 + tag: Syntax + featured: true +``` + +| Field | Notes | +|---|---| +| `title` | H2 heading. | +| `id` | Section anchor. Use `whats-new` so `{hero}`'s secondary action can jump to it. | +| `intro` | One-line lead. | +| `release-links` | Links to the full release notes, shown beside the heading. List more than one when a product has several release streams. | +| `upgrade-link` | An upgrade prompt below the grid. Takes `label` and `url`. | +| `items` | The highlight cards. | + +Each item takes a `title`, a `description`, a `link`, a `date` and a `tag`. Mark one item `featured: true` to span two columns. + +The `date` renders as you write it. Use sentence case, for example `Aug 2026`. + +Every field except `title` is optional. The example file uses each one once, so you can start from it and delete what you do not need. + +## Inline body + +Omit `:product:` and give the directive the same schema as a YAML body, for a one-off panel that does not belong in the shared file: + +```markdown +:::{whats-new} +title: What's new +items: + - title: Hub pages + description: A product-scoped landing page. + link: /syntax/hub-pages.md + date: Aug 2026 +::: +``` + +## Scope limit + +The directive reads the file in the current documentation set. It cannot render another repository's panel. + +That is not a syntax gap. Cross-link resolution maps pages through the link index, and a YAML data file is not a page. In an isolated build the other repository is not checked out, so there is no file to read at all. + +Every hub page lives in the same repository as its content file, so this costs nothing today. + +## Links + +Every `release-links[].url`, `upgrade-link.url`, and `items[].link` validates at build time, using the same forms as [`{link-card}`](link-card.md#links). diff --git a/src/Elastic.Documentation.Site/Assets/markdown/hub.css b/src/Elastic.Documentation.Site/Assets/markdown/hub.css index 564cb73ee3..1701003ba1 100644 --- a/src/Elastic.Documentation.Site/Assets/markdown/hub.css +++ b/src/Elastic.Documentation.Site/Assets/markdown/hub.css @@ -370,6 +370,165 @@ color: var(--color-blue-elastic-100, #0b64dd); } + /* What's new ------------------------------------------------------- */ + .hub-whats-new { + @apply mx-auto w-full max-w-5xl; + margin-bottom: 56px; + scroll-margin-top: 120px; + } + .hub-whats-new .hub-wn-header { + @apply mb-6 flex flex-wrap items-end justify-between gap-4; + } + .hub-whats-new .hub-wn-title { + font-size: var(--text-2xl); + font-weight: 700; + color: var(--color-ink-dark); + line-height: 1.2; + margin: 0; + } + .hub-whats-new .hub-wn-intro { + color: var(--color-ink-light); + margin-top: 8px; + max-width: 60ch; + } + .hub-whats-new .hub-wn-rn { + @apply flex flex-shrink-0 flex-wrap items-center gap-x-2 gap-y-1; + } + .hub-whats-new .hub-wn-footer { + @apply mt-4 flex flex-wrap items-center justify-center gap-x-2 gap-y-1; + } + .hub-whats-new .hub-wn-footer-text { + font-size: var(--text-base); + color: var(--color-ink-light); + } + .hub-whats-new .hub-wn-upgrade { + @apply inline-flex items-center gap-1.5; + font-size: var(--text-base); + font-weight: 600; + color: var(--color-blue-elastic-100); + text-decoration: none; + } + .hub-whats-new .hub-wn-upgrade:hover, + .hub-whats-new .hub-wn-upgrade:focus-visible { + text-decoration: underline; + } + .hub-whats-new .hub-wn-upgrade svg { + flex-shrink: 0; + } + .hub-whats-new .hub-wn-rn-label { + font-size: var(--text-base); + font-weight: 600; + color: var(--color-ink-light); + } + .hub-whats-new .hub-wn-rn-list { + @apply m-0 flex flex-wrap items-center p-0; + list-style: none; + } + .hub-whats-new .hub-wn-rn-list li { + @apply inline-flex items-center; + } + .hub-whats-new .hub-wn-rn-list li:not(:last-child)::after { + content: '·'; + color: var(--color-grey-40); + margin: 0 10px; + font-weight: 700; + } + .hub-whats-new .hub-wn-rn-link { + font-size: var(--text-base); + font-weight: 600; + color: var(--color-blue-elastic-100); + text-decoration: none; + } + .hub-whats-new .hub-wn-rn-link:hover, + .hub-whats-new .hub-wn-rn-link:focus-visible { + text-decoration: underline; + } + + /* What's new card grid */ + .hub-whats-new .hub-wn-grid { + @apply m-0 grid list-none p-0; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 16px; + } + .hub-whats-new .hub-wn-card { + margin: 0; + } + .hub-whats-new .hub-wn-card-featured { + grid-column: span 2; + } + .hub-whats-new .hub-wn-card-link { + @apply flex h-full flex-col gap-2.5; + padding: 18px 20px; + background: var(--color-white); + border: 1px solid var(--color-grey-20); + border-radius: 14px; + text-decoration: none; + color: inherit; + transition: + border-color 0.15s ease, + box-shadow 0.15s ease; + } + /* Same hover treatment as every other card that is itself a link. The pale blue this + replaced read at 2.12:1 against white, so the state was barely visible. */ + .hub-whats-new a.hub-wn-card-link:hover, + .hub-whats-new .hub-wn-card-link:focus-visible { + border-color: var(--color-grey-80); + box-shadow: 0 2px 10px rgb(0 0 0 / 0.06); + } + .hub-whats-new .hub-wn-card-meta { + @apply flex items-center justify-between gap-2; + font-size: var(--text-sm); + } + .hub-whats-new .hub-wn-card-meta-left { + @apply inline-flex items-center gap-2; + } + /* The date is authored, so it keeps the casing the writer chose. Forcing + uppercase shouts, and it mangles a month name in any language. */ + .hub-whats-new .hub-wn-card-date { + font-weight: 600; + color: var(--color-ink-light); + letter-spacing: 0.03em; + } + .hub-whats-new .hub-wn-card-tag { + color: var(--color-grey-80, #69707d); + font-weight: 500; + } + .hub-whats-new .hub-wn-card-title { + font-size: var(--text-base); + font-weight: 700; + color: var(--color-ink-dark); + line-height: 1.3; + margin: 0; + } + .hub-whats-new .hub-wn-card-featured .hub-wn-card-title { + font-size: var(--text-lg); + } + .hub-whats-new .hub-wn-card-desc { + font-size: var(--text-base); + color: var(--color-ink-light); + line-height: 1.45; + margin: 0; + } + .hub-whats-new .hub-wn-card-more { + @apply mt-auto inline-flex items-center gap-1.5; + font-size: var(--text-base); + font-weight: 600; + color: var(--color-blue-elastic-100); + } + @media (max-width: 900px) { + .hub-whats-new .hub-wn-grid { + grid-template-columns: repeat(2, minmax(0, 1fr)); + } + } + @media (max-width: 640px) { + .hub-whats-new .hub-wn-grid { + grid-template-columns: 1fr; + } + .hub-whats-new .hub-wn-card-featured { + grid-column: span 1; + } + } + /* Zone (section heading) ------------------------------------------ */ .hub-zone { @apply mx-auto w-full max-w-5xl; diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs index add4cf3626..d9e56299ad 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs @@ -153,6 +153,9 @@ protected override DirectiveBlock CreateFencedBlock(BlockProcessor processor) if (info.IndexOf("{get-started}") > 0) return new GetStartedBlock(this, context); + if (info.IndexOf("{whats-new}") > 0) + return new WhatsNewBlock(this, context); + if (info.IndexOf("{agent-skill}") > 0) return new AgentSkillBlock(this, context); diff --git a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs index 31057f6bd0..904c963f35 100644 --- a/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs +++ b/src/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs @@ -120,6 +120,9 @@ protected override void Write(HtmlRenderer renderer, DirectiveBlock directiveBlo case GetStartedBlock getStartedBlock: WriteGetStarted(renderer, getStartedBlock); return; + case WhatsNewBlock whatsNewBlock: + WriteWhatsNew(renderer, whatsNewBlock); + return; case PageCardBlock pageCardBlock: WritePageCard(renderer, pageCardBlock); return; @@ -270,6 +273,17 @@ private static void WriteLinkCard(HtmlRenderer renderer, LinkCardBlock block) RenderRazorSlice(slice, renderer); } + private static void WriteWhatsNew(HtmlRenderer renderer, WhatsNewBlock block) + { + var slice = WhatsNewView.Create(new WhatsNewViewModel + { + DirectiveBlock = block, + Data = block.Data, + SitePathPrefix = block.Build.UrlPathPrefix + }); + RenderRazorSlice(slice, renderer); + } + private static void WriteGetStarted(HtmlRenderer renderer, GetStartedBlock block) { var data = block.Data; diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewBlock.cs b/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewBlock.cs new file mode 100644 index 0000000000..1c54c33e2c --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewBlock.cs @@ -0,0 +1,173 @@ +// 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 System.Collections.Concurrent; +using Elastic.Markdown.Diagnostics; +using YamlDotNet.Core; +using YamlDotNet.Serialization; + +namespace Elastic.Markdown.Myst.Directives.Hub; + +/// +/// Renders the "What's new" panel for a product. Two usage shapes: +/// +/// Centralized lookup (preferred): +/// +/// :::{whats-new} +/// :product: kibana +/// ::: +/// +/// The directive looks the product key up in config/whats-new.yml +/// and renders the data declared there. Authors edit one file; any page can +/// surface the panel. +/// +/// Inline override: if no :product: option is provided, +/// the directive expects a YAML body declaring title, items, +/// etc. directly. Useful for one-offs that don't belong in the central +/// feed. +/// +public class WhatsNewBlock(DirectiveBlockParser parser, ParserContext context) + : DirectiveBlock(parser, context) +{ + private const string WhatsNewFileName = "hub-whats-new.yml"; + + private static readonly ConcurrentDictionary CentralConfigCache = new(); + + public override string Directive => "whats-new"; + + public WhatsNewData Data { get; private set; } = WhatsNewData.Empty; + + public override void FinalizeAndValidate(ParserContext context) + { + var product = Prop("product"); + + if (!string.IsNullOrWhiteSpace(product)) + { + var resolved = LoadFromCentralConfig(product); + if (resolved is null) + { + this.EmitError($"{{whats-new}} :product: '{product}' was not found in {WhatsNewFileName} at the root of this documentation set."); + return; + } + Data = resolved; + ValidateLinks(context); + return; + } + + var yaml = HubYamlBody.Extract(this, new BuildContextFileReader(Build.ReadFileSystem)); + if (yaml is null) + { + this.EmitError("{whats-new} requires either a `:product:` option or a YAML body."); + return; + } + + try + { + Data = YamlSerialization.Deserialize(yaml, Build.ProductsConfiguration) ?? WhatsNewData.Empty; + } + catch (YamlException ex) + { + this.EmitError($"{{whats-new}} YAML parse error: {ex.Message}"); + return; + } + + ValidateLinks(context); + } + + private void ValidateLinks(ParserContext context) + { + foreach (var link in Data.ReleaseLinks) + link.Url = DirectiveLinkValidator.ValidateAndResolve(link.Url, this, context); + if (Data.UpgradeLink is { } upgrade) + upgrade.Url = DirectiveLinkValidator.ValidateAndResolve(upgrade.Url, this, context); + foreach (var item in Data.Items) + item.Link = DirectiveLinkValidator.ValidateAndResolve(item.Link, this, context); + } + + /// + /// The panel content lives in the content repository, next to the pages that use it, so a + /// writer edits it without touching the build tool. It is read from the current documentation + /// set, which means the directive cannot render another repository's panel. In an isolated + /// build the other repository is not checked out at all, so there would be no file to read. + /// + private WhatsNewData? LoadFromCentralConfig(string productKey) + { + var path = Path.Combine(Build.DocumentationSourceDirectory.FullName, WhatsNewFileName); + if (!Build.ReadFileSystem.File.Exists(path)) + return null; + + var config = CentralConfigCache.GetOrAdd(path, p => + { + try + { + var yaml = Build.ReadFileSystem.File.ReadAllText(p); + return YamlSerialization.Deserialize(yaml, Build.ProductsConfiguration); + } + catch + { + return null; + } + }); + + if (config?.Products is null) + return null; + return config.Products.TryGetValue(productKey, out var data) ? data : null; + } + + public override IEnumerable GeneratedAnchors => + string.IsNullOrWhiteSpace(Data.Id) ? [] : [Data.Id]; +} + +[YamlSerializable] +public record WhatsNewConfig +{ + [YamlMember(Alias = "products")] + public Dictionary Products { get; set; } = []; +} + +[YamlSerializable] +public record WhatsNewData +{ + [YamlMember(Alias = "title")] + public string? Title { get; set; } + + [YamlMember(Alias = "id")] + public string? Id { get; set; } + + [YamlMember(Alias = "intro")] + public string? Intro { get; set; } + + [YamlMember(Alias = "release-links")] + public LinkCardLink[] ReleaseLinks { get; set; } = []; + + [YamlMember(Alias = "upgrade-link")] + public LinkCardLink? UpgradeLink { get; set; } + + [YamlMember(Alias = "items")] + public WhatsNewItem[] Items { get; set; } = []; + + public static WhatsNewData Empty { get; } = new(); +} + +[YamlSerializable] +public record WhatsNewItem +{ + [YamlMember(Alias = "title")] + public string? Title { get; set; } + + [YamlMember(Alias = "description")] + public string? Description { get; set; } + + [YamlMember(Alias = "link")] + public string? Link { get; set; } + + [YamlMember(Alias = "date")] + public string? Date { get; set; } + + [YamlMember(Alias = "tag")] + public string? Tag { get; set; } + + [YamlMember(Alias = "featured")] + public bool Featured { get; set; } +} diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewView.cshtml b/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewView.cshtml new file mode 100644 index 0000000000..d61d05ecbe --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewView.cshtml @@ -0,0 +1,117 @@ +@inherits RazorSlice + +@{ + var d = Model.Data; + var upgrade = d.UpgradeLink; + var hasUpgrade = upgrade is not null && !string.IsNullOrWhiteSpace(upgrade.Url) && !string.IsNullOrWhiteSpace(upgrade.Label); +} + +
        +
        +
        + @if (!string.IsNullOrWhiteSpace(d.Title)) + { +

        @d.Title

        + } + @if (!string.IsNullOrWhiteSpace(d.Intro)) + { +

        @d.Intro

        + } +
        + @if (d.ReleaseLinks.Length > 0) + { +
        + Latest release notes: +
          + @foreach (var link in d.ReleaseLinks) + { + if (string.IsNullOrWhiteSpace(link.Url) || string.IsNullOrWhiteSpace(link.Label)) + { + continue; + } +
        • @link.Label
          • + } +
        +
        + } +
        + + @if (d.Items.Length > 0) + { + + } + + @if (hasUpgrade) + { +
        + Ready to move to the latest version? + + @upgrade.Label + + +
        + } +
        diff --git a/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewViewModel.cs b/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewViewModel.cs new file mode 100644 index 0000000000..764c756e46 --- /dev/null +++ b/src/Elastic.Markdown/Myst/Directives/Hub/WhatsNewViewModel.cs @@ -0,0 +1,10 @@ +// 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.Myst.Directives.Hub; + +public class WhatsNewViewModel : HubDirectiveViewModel +{ + public required WhatsNewData Data { get; init; } +} diff --git a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs index 0a40733226..74265537a6 100644 --- a/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs +++ b/src/Elastic.Markdown/Myst/Renderers/LlmMarkdown/LlmBlockRenderers.cs @@ -517,6 +517,9 @@ protected override void Write(LlmMarkdownRenderer renderer, DirectiveBlock obj) case GetStartedBlock getStartedBlock: WriteGetStartedBlock(renderer, getStartedBlock); return; + case WhatsNewBlock whatsNewBlock: + WriteWhatsNewBlock(renderer, whatsNewBlock); + return; } // Ensure single empty line before directive @@ -583,6 +586,57 @@ private static void WriteHeroBlock(LlmMarkdownRenderer renderer, HeroBlock heroB renderer.EnsureLine(); } + // Dated highlights, so the export keeps the date and tag alongside each title. A reader + // asking "what changed recently in X" wants exactly this list. + private static void WriteWhatsNewBlock(LlmMarkdownRenderer renderer, WhatsNewBlock block) + { + var data = block.Data; + renderer.EnsureBlockSpacing(); + + if (!string.IsNullOrEmpty(data.Title)) + { + renderer.WriteLine($"## {data.Title}"); + renderer.EnsureLine(); + } + if (!string.IsNullOrEmpty(data.Intro)) + { + renderer.WriteLine(data.Intro); + renderer.EnsureLine(); + } + + foreach (var link in data.ReleaseLinks) + WriteHeroAction(renderer, link.Label, link.Url); + + foreach (var item in data.Items) + WriteWhatsNewItem(renderer, item); + + if (data.UpgradeLink is { } upgrade) + WriteHeroAction(renderer, upgrade.Label, upgrade.Url); + + renderer.EnsureLine(); + } + + private static void WriteWhatsNewItem(LlmMarkdownRenderer renderer, WhatsNewItem item) + { + if (string.IsNullOrEmpty(item.Title)) + return; + + renderer.EnsureLine(); + var title = string.IsNullOrEmpty(item.Link) + ? item.Title + : $"[{item.Title}]({HubLinkForLlm(renderer, item.Link)})"; + + var meta = new List(2); + if (!string.IsNullOrEmpty(item.Date)) + meta.Add(item.Date); + if (!string.IsNullOrEmpty(item.Tag)) + meta.Add(item.Tag); + + renderer.WriteLine(meta.Count > 0 ? $"- {title} ({string.Join(", ", meta)})" : $"- {title}"); + if (!string.IsNullOrEmpty(item.Description)) + renderer.WriteLine($" {item.Description}"); + } + // The onboarding path is a sequence, so it exports as an ordered list. Options under a step // become sub-items, each with its command or its link. private static void WriteGetStartedBlock(LlmMarkdownRenderer renderer, GetStartedBlock block) diff --git a/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs b/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs index 3b01468f1d..49c8f4dfd3 100644 --- a/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs +++ b/src/Elastic.Markdown/Myst/Renderers/PlainText/PlainTextBlockRenderers.cs @@ -292,6 +292,7 @@ protected override void Write(PlainTextRenderer renderer, DirectiveBlock obj) case CardGroupBlock: case LinkCardBlock: case GetStartedBlock: + case WhatsNewBlock: return; case AgentSkillBlock agentSkillBlock: diff --git a/src/Elastic.Markdown/Myst/YamlSerialization.cs b/src/Elastic.Markdown/Myst/YamlSerialization.cs index 36bb30ce0a..65ed9abcf7 100644 --- a/src/Elastic.Markdown/Myst/YamlSerialization.cs +++ b/src/Elastic.Markdown/Myst/YamlSerialization.cs @@ -86,4 +86,7 @@ public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializ [YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.GetStartedData))] [YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.GetStartedStep))] [YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.GetStartedStepOption))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.WhatsNewData))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.WhatsNewItem))] +[YamlSerializable(typeof(Elastic.Markdown.Myst.Directives.Hub.WhatsNewConfig))] public partial class DocsBuilderYamlStaticContext; diff --git a/tests/authoring/Blocks/Hub/WhatsNew.fs b/tests/authoring/Blocks/Hub/WhatsNew.fs new file mode 100644 index 0000000000..fd93206767 --- /dev/null +++ b/tests/authoring/Blocks/Hub/WhatsNew.fs @@ -0,0 +1,110 @@ +// 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 +module ``AuthoringTests``.``block elements``.``hub``.``whats new elements`` + +open Xunit +open authoring + +// The :product: path reads hub-whats-new.yml from the documentation set root. The authoring +// harness builds from a temporary set with no such file, so these cover the inline-body path +// and the error raised when a product key cannot be resolved. + +type ``whats new with an inline body`` () = + static let markdown = Setup.Markdown """ +:::{whats-new} +title: What's new in docs-builder +id: whats-new +intro: Recent additions to the toolchain. +items: + - title: Hub pages + description: A product-scoped landing page. + link: /index.md + date: AUG 2026 + tag: Syntax + featured: true + - title: Explore sections + description: Collapse a long link list. + link: /index.md + date: AUG 2026 + tag: Syntax +::: +""" + + [] + let ``renders the heading and intro`` () = + markdown |> convertsToContainingHtml """

        What's new in docs-builder

        """ + + [] + let ``renders a card per item`` () = + markdown |> convertsToContainingHtml """

        Hub pages

        """ + + [] + let ``spans the featured card across two columns`` () = + markdown |> convertsToContainingRawHtml """
      1. """ + + [] + let ``renders the date and tag`` () = + markdown |> convertsToContainingHtml """Syntax""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``whats new with release and upgrade links`` () = + static let markdown = Setup.Markdown """ +:::{whats-new} +title: What's new +release-links: + - label: View release notes + url: /index.md +upgrade-link: + label: Upgrade + url: /index.md +::: +""" + + [] + let ``renders the release link`` () = + markdown |> convertsToContainingHtml """View release notes""" + + [] + let ``renders the upgrade prompt`` () = + markdown |> convertsToContainingHtml """Ready to move to the latest version?""" + + [] + let ``has no errors`` () = markdown |> hasNoErrors + +type ``whats new with an unresolvable product`` () = + static let markdown = Setup.Markdown """ +:::{whats-new} +:product: not-a-product +::: +""" + + [] + let ``errors and names the file it looked in`` () = + markdown |> hasError "hub-whats-new.yml" + +type ``whats new with neither product nor body`` () = + static let markdown = Setup.Markdown """ +:::{whats-new} +::: +""" + + [] + let ``errors`` () = + markdown |> hasError "requires either a `:product:` option or a YAML body" + +type ``whats new with a relative item link`` () = + static let markdown = Setup.Markdown """ +:::{whats-new} +title: What's new +items: + - title: Broken + link: nope.md +::: +""" + + [] + let ``rejects a relative path`` () = + markdown |> hasError "must be an absolute path starting with `/`" diff --git a/tests/authoring/authoring.fsproj b/tests/authoring/authoring.fsproj index 4bd3e42fe5..639e310423 100644 --- a/tests/authoring/authoring.fsproj +++ b/tests/authoring/authoring.fsproj @@ -58,6 +58,7 @@ + From 69aef2b4470e1c62fb37b98c8859e63eec947b77 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Fri, 14 Aug 2026 12:36:45 +0200 Subject: [PATCH 08/11] =?UTF-8?q?AsciiDoc=20=E2=86=92=20Markdown=20convert?= =?UTF-8?q?er=20for=20elastic.co/guide=20books=20(#3802)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add legacy /guide AsciiDoc-to-Markdown migration tool Implements a native C# converter to migrate elastic.co/guide content (AsciiDoc served by the legacy elastic/docs system) into Markdown docsets that docs-builder can render. New project: Elastic.LegacyDocs.Migration with: - conf.yaml parser for the elastic/docs book definitions - Source repo manager for resolving branches and paths - AsciiDoc lexer, parser, and AST (sections, code blocks, tables, admonitions, lists, includes, conditionals, inline formatting) - Markdown emitter targeting MyST syntax - Page chunker to split documents by section level - Archive and Latest docset generators producing docset.yml/toc.yml - CLI command: `docs-builder guide migrate` Made-with: Cursor * Fix migration output to pass docs-builder validation Fixes found by running the converter end-to-end and building with docs-builder: - Fix section level off-by-one in lexer (= is level 0, == is level 1) - Fix Repos model to handle nested YAML objects (Dict) - Fix basePath in generators to use index file directory for includes - Fix chunker to walk into level-0 sections and promote chunked sections to H1 for standalone pages - Use docs-builder anchor syntax (# Title [anchor]) instead of MyST (anchor)= targets - Map unsupported directives: caution→warning, sidebar→admonition - Add cross-page anchor-to-slug map so refs emit file links - Add bare URL[text] pattern to inline parser - Prevent double image path prefix Made-with: Cursor * Extract migration to isolated CLI tool and add missing parser features - Add DSV/CSV/TSV table format support (384 occurrences in ES|QL docs) - Add pass:[] and +inline+ passthrough inline patterns - Add unconstrained bold (**text**) support - Add [role]#text# inline macro support - Extract migration command into standalone docs-migrate CLI tool (removable by deleting src/tooling/docs-migrate/ and src/authoring/Elastic.LegacyDocs.Migration/) - Remove migration coupling from docs-builder Made-with: Cursor * Refactor docs-migrate into subcommands and switch to bare-clone + worktree strategy - Split monolithic MigrateCommand into init/list/clone/convert/serve subcommands - SourceRepoManager now uses bare clones + git worktrees + sparse checkout (cone mode) to avoid redundant full clones per branch and only fetch needed directory trees - Add Proc package for process execution in place of raw System.Diagnostics.Process - Add guide-nav feature flag to configuration layer (FeatureFlags, DocumentationSetFile, ConfigurationFile) so converted docsets can signal the guide-archive nav mode Co-Authored-By: Claude Sonnet 4.6 * Fix conf.yaml parser missing nested section groups The conf.yaml structure has up to 3 levels of nesting: a category's sections can contain sub-groups (with base_dir + sections) rather than books directly. LegacyBook had no Sections property so IgnoreUnmatchedProperties silently dropped all nested books, causing entire families to disappear (Elasticsearch clients, all APM agents, ECS logging, etc.). Add BaseDir and Sections to LegacyBook, then recursively flatten after deserialization, accumulating the base_dir prefix so leaf book prefixes are fully qualified (e.g. en/elasticsearch/client/net-api). Co-Authored-By: Claude Sonnet 4.6 * Normalize docs-migrate default work dir to AppData Use LocalApplicationData/elastic/docs-migrate as the default work directory, matching the pattern from Paths.ApplicationData in the main codebase. Includes the same Docker/CI fallback to GetTempPath() when LocalApplicationData returns an empty string. Co-Authored-By: Claude Sonnet 4.6 * Write conversion output to cwd/.artifacts/migrated Output from convert and serve now lands in .artifacts/migrated relative to the current working directory, separate from the AppData work dir that holds conf.yaml and repo clones. Co-Authored-By: Claude Sonnet 4.6 * Add --no-hud flag to serve and fix branch resolution for repos without versioned branches - Add --no-hud to docs-builder serve: disables diagnostics HUD and skips background in-memory validation builds - docs-migrate serve passes --no-hud automatically - Fix SourceRepoManager branch resolution: check local branches before fetching, use --detach for worktrees so repos like elastic/docs (only has master) can serve multiple version worktrees - Use Proc.Start for branch probing to suppress expected git errors Made-with: Cursor * Rewrite guide URLs to internal links and emit docs-builder substitutions - Rewrite https://www.elastic.co/guide/... URLs to absolute internal markdown links (/prefix/version/page.md) so docs-builder validates them - Emit {{name}} (double braces) for unresolved AsciiDoc attribute references so docs-builder recognizes them as substitution variables - Add SharedAttributes with ~130 well-known product-name attributes from shared/attributes.asciidoc (es, kib, agent, fleet, etc.) - Write subs: section in generated docset.yml with all product names Made-with: Cursor * Preserve block anchors as docs-builder inline anchors AsciiDoc [[id]] anchors on non-section blocks (paragraphs, tables, description lists, etc.) were silently discarded. Now they are wrapped in an AnchoredBlock node and emitted as $$$id$$$ inline anchors that docs-builder renders as link targets. Made-with: Cursor * Fix conditionals inside verbatim blocks, anchor map coverage, and source attributes - Fix lexer: conditionals inside verbatim/table blocks were being parsed as conditional tokens instead of raw text; now only recognized outside those contexts - Fix table delimiter regex to accept |=== with 3+ = signs - Fix parser: attribute substitution in section titles and image alt/title; preserve pending id/title/blockAttr across list-continuation blocks; track pendingStart to reset pos on section-level break - Fix page chunker: include AnchoredBlock IDs in anchor-to-slug map - Fix ConvertCommand: pass source_branch and per-repo root attributes to parser; guard against missing Current version when building overview Co-Authored-By: Claude Sonnet 4.6 * Migrate docs-migrate CLI to Nullean.Argh docs-migrate was the last CLI still on ConsoleAppFramework, which had no PackageVersion entry and so failed restore under Central Package Management. Align it with docs-builder and essc: Host.CreateApplicationBuilder + AddArgh, app.Map() registration, and CancellationToken in place of Cancel. Co-Authored-By: Claude Sonnet 4.6 * Fix converter defects blocking elastic.co/guide book migration Fixes eight root-cause bugs that produced garbled output across 21,962+ files in the converted corpus. All changes are covered by a new tests/Elastic.LegacyDocs.Migration.Tests/ project (19 tests). Step 0: Add test project, diagnostics channel (OnDiagnostic on AsciidocParserOptions), and AGENTS.md test-project table row. Step 1: Fix `--` open blocks — lexer dispatched on delimChar before checking length so `--` fell into the verbatim path. Now length < 4 routes to BlockDelimiter; IsMatchingDelimiter/IsMatchingClose require exact length so `--------` can no longer close a `----` block. PageChunker now recurses into OpenBlockNode for anchor collection and page extraction. Step 2: Add IncludeDirective case to ParseBlock's switch — includes were silently skipped (SkipToken) instead of being processed. Step 3: Attribute resolution — eager expansion via SetAttribute helper, SetBasePath keeps docdir in sync, Path.GetFullPath normalization in ProcessInclude fixes 863 `../../shared/attributes.asciidoc` paths, docs-root/asciidoc-dir seeded in ConvertCommand, docdir saved and restored across include file boundaries. Step 4: Emitter substitution — undefined attributes emit `{name}` not `{{name}}`; ProductNames keys pass through as `{{name}}` for docs-builder subs. SetAttribute skips ProductNames so shared/ attributes.asciidoc cannot shadow them. Step 5: Callout annotations — populate CodeBlockNode.Callouts from trailing ` text` lines after a code block closing delimiter, making the emitter's ordered-list output live. Step 6: include-tagged:: — new ResolveVerbatimIncludes handles `include-tagged::` directives inside listing blocks; tag/end regexes widened to allow hyphens and drop the //prefix requirement. Step 7: Xref regex uses non-greedy `.+?` to allow `>` in link text; multi-line admonition paragraphs collect continuation Text tokens instead of truncating at the first line. Co-Authored-By: Claude Sonnet 4.6 * Fix 4 conversion quality bugs in MarkdownEmitter - Headings: apply attribute substitution to document/section titles so {es} → {{es}} rather than leaking as raw text - Same-page xrefs: compare resolved anchor slug against current page slug; emit #anchor for same-page and slug.md#anchor for cross-page - AnchoredBlock: emit a blank line after $$$anchor$$$ so docs-builder treats it as a standalone inline anchor block - titleabbrev: PassthroughNode wrapping … was missed by the ParagraphNode filter; add the check to the PassthroughNode emit branch Co-Authored-By: Claude Sonnet 4.6 * docs-migrate: --minors flag, default port 3001, version URL routing fix - Add --minors N to clone and convert commands to cap minor versions per major; stored in FilterOptions and persisted to .clone-options.json - Change docs-migrate serve default port from 3000 to 3001 - Fix /8.19 URL routing: Path.GetExtension treats version segments like 8.19 as having extension .19; restrict hasKnownExtension check to actual document file types so version-number slugs resolve correctly Co-Authored-By: Claude Sonnet 4.6 * Fix xref display text, link attr substitution, and chunk level - Build AnchorToTitleMap alongside AnchorToSlugMap in PageChunker; when a section has , use that as the display title (matches the abbreviated nav title on elastic.co, e.g. "Indices and documents" vs full "Indices, documents, and fields") - EmitCrossRef: resolve <> with no text to the section title from AnchorToTitleMap, not the raw anchor ID - EmitLink: apply SubstituteTitleAttrs to link text so {es}//{kib} references in URL link text become {{es}}/{{kib}} instead of leaking as single-brace literals - ConvertCommand: conf.yaml chunk:N maps to chunkLevel N+1 in our AST (chunk:1 → chunkLevel 2 creates separate pages for === sections, matching elastic.co's page-per-section structure; 423 → 3376 pages) Co-Authored-By: Claude Sonnet 4.6 * Fix xref conversion: inline regex ordering, bold/italic spanning, DL multi-line collection, title xrefs - Prevent double-backtick AsciiDoc curly-quotes from opening a code span by adding (?> xref openers in cross-mark content (e.g. *word*<>) - Fix ParseDescriptionList to collect consecutive Text tokens into one paragraph (matching ParseParagraph behaviour) so xrefs that wrap across continuation lines within a DL item are kept in a single ParseInlines call - Add SubstituteTitleXrefs helper to MarkdownEmitter and apply it to section headings, document titles, and callout descriptions, which previously used SubstituteTitleAttrs only and left <> patterns unconverted - Add ifeval:: lexer fix: relax middle group from .+ to .* to allow empty attribute name - Add GetBlockAttributeRegex trailing-whitespace trim to avoid false negatives - Add test coverage: curly-quote context, ordered-list items, bold-asterisk interference Result: raw xref leftovers in en/elasticsearch/reference/8.19 drop from 273 to 9 files. The remaining 9 are source-level bugs (malformed single >), code-block placeholders, or xrefs genuinely inside code spans -- all correct not-converted behaviour. Co-Authored-By: Claude Sonnet 4.6 * Inline include:: directives inside pipe tables When a pipe table contains an include:: on its own line (typical for shared common-options snippets), the lexer emits it as a Text token (not IncludeDirective) because the inTable state flag is not set during include resolution. ParseTable now detects the include:: pattern in Text tokens, reads the referenced file, and appends its | ... | rows directly to the current table instead of leaking the directive text into the last cell. Also handles the IncludeDirective token type for future-proofing. Result: include:: leftovers drop from 58 to 24 (remaining 24 are {esql-specs} references to external test fixture files that are not part of the repository and cannot be resolved). Co-Authored-By: Claude Sonnet 4.6 * Fix callout collection: skip comments/blank after code blocks, add ParseCalloutList for orphan markers - After a listing block, skip any trailing comment tokens (// TEST[...]) and one optional blank line before attempting callout collection; restore position if no callout markers follow, preventing skipped blank lines from orphaning later content - Add ParseCalloutList routed from ParseBlock for standalone callout lines that appear after continuation text or in other contexts where the code-block collector already broke; collects multi-line descriptions via continuation join - Lexer: relax ifeval:: middle group .+ → .* to allow empty attribute name - Lexer: allow trailing whitespace on block attribute lines [attr]\s* Result: raw callout markers in en/elasticsearch/reference/8.19 drop from ~396 to ~90 files. Remaining cases are multi-callout blocks where <1> description wraps across lines, breaking the code-block collector before reaching <2>+. Co-Authored-By: Claude Sonnet 4.6 * Fix multi-line callout descriptions and DL inline xref spanning - ParseParagraph: stop collecting Text tokens at callout markers () so ParseCalloutList gets to handle the run instead of having them swallowed into paragraph content - ParseDescriptionList: same guard in the inline Text-continuation loop - Code-block callout collector: collect continuation lines for each description so multi-line callout text is fully captured rather than truncated at the first line - ParseDescriptionList: when inline description text (after ::) contains an unclosed <<, join continuation Text tokens until the xref closes, enabling multi-line xref spanning within DL items Result: callout markers drop from 90 to 0; residual raw xrefs drop from 23 to 22 all of which are either inside code spans/fences (correct behaviour) or source-level malformed >> (not fixable). Co-Authored-By: Claude Sonnet 4.6 * Load shared/attributes.asciidoc before converting each book Pre-parse docs-repo/shared/attributes.asciidoc using the existing AsciidocParser with branch/version seed attributes already set, so feature and product-name abbreviations like {transform}, {ilm-init}, {anomaly-detect} and cross-guide URL attributes like {ref}, {logstash-ref} are resolved at conversion time. ProductNames keys (es, kib, etc.) are still excluded from eager expansion so they continue to emit as {{name}} docs-builder substitution placeholders that get resolved from the generated docset.yml subs: block. Adds AsciidocParser.LoadAttributeFile static helper and ResolvedAttributes property to support this pre-parse pattern. Co-Authored-By: Claude Sonnet 4.6 * Convert AsciiDoc typographic double quotes to straight quotes Add group 23 to InlineCombinedRegex to match ``text'' (AsciiDoc opening double-backtick + closing double-apostrophe) and emit as "text" (straight double-quote pair). The existing lookbehind on the mono group already prevents `` from opening a code span, so group 23 matches the remaining cases that fall through to raw text. Eliminates 21 occurrences of visible AsciiDoc typographic quote syntax in en/elasticsearch/reference/8.19. Co-Authored-By: Claude Sonnet 4.6 * Fix chunking: each included file becomes a separate page regardless of section level - Add IsIncludeRoot flag to SectionNode to mark sections produced at the top level of a ProcessInclude call - Set IsIncludeRoot=true in ParseSection's IncludeDirective handler and in ProcessInclude's main loop - Fix chunkLevel calculation: conf.yaml chunk:N maps directly to AST level N, so pass book.Chunk directly instead of book.Chunk+1 - Fix ExtractPages to recurse into inline sections (level > chunkLevel) when looking for nested IsIncludeRoot sections — this handles the case where an include appears after a discrete section, which nests the included content under the discrete section in the AST - Fix CollectAnchors to also recurse into inline sections for the same reason - Add IncludeChain_EachIncludedFile_BecomesASeparatePage test that mirrors the elastic.co search-your-data structure with 3-level include nesting and discrete sections Co-Authored-By: Claude Sonnet 4.6 * Fix: emit $$$anchor$$$ before H1 headings so docs-builder registers them docs-builder's anchor registry includes H2+ heading slugs and $$$...$$$ inline anchors but NOT H1 heading slugs. Cross-references like [text](page.md#page-anchor-id) were triggering 96 'does not exist' errors because the page-level anchor (from the original [[block-anchor]] before the first section) was emitted as '# Title [#anchor-id]' — a format docs-builder parses for H2+ but does not register in the anchor collection for H1. Fix: emit $$$anchor-id$$$ on a standalone line before H1 headings (both from document.Title and from Level=0 SectionNode). The $$$...$$$ syntax is the docs-builder InlineAnchor format, which is collected via document.Descendants() and included in markdown.Anchors. With this fix: 0 errors and 0 warnings from docs-builder serve. Co-Authored-By: Claude Sonnet 4.6 * Fix verbatim include resolution, ifeval stripping, and +..+ passthrough bug - Extend ResolveVerbatimIncludes to handle standard include::[tag=] and full-file include::[] directives inside verbatim blocks (fixes 164 ESQL pages) - Strip ifeval::/ifdef::/endif:: conditional markers from verbatim block content where they can't be evaluated (fixes 2 files) - Add lookbehind to constrained +..+ passthrough regex so '8.0+' and similar version indicators don't start a passthrough span (fixes xref leaking past the passthrough into prose) Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01LF2iCfVK3ecJgPeFCP6p6S * ServeCommand: catch OperationCanceledException so Ctrl+C exits cleanly Co-Authored-By: Claude Sonnet 4.6 (1M context) * Fix ifeval conditionals, trailing-space delimiters, and double-xref normalization - ConditionalProcessor: for ifeval::[expr], the condition expression lives inside the brackets (token.Metadata.Content / group 3 of the lexer regex), not before them (Condition / group 2 = empty). Read Content as the condition for ifeval and always push to conditionStack (ifeval is always block-level, never inline). Reduces leaked ifeval/endif markers from 126 files down to 3 in the logstash-versioned-plugins corpus. - AsciidocLexer.IsMatchingDelimiter + AsciidocParser.IsMatchingClose: both now trim trailing whitespace before length/char comparison so a source line like '---- ' (trailing space) correctly closes a '----' verbatim block. Fixes ~20 pages in app-search and fleet books where headings and xrefs appeared raw inside unclosed code fences. - AsciidocParser.ParseInlines: pre-normalize '<<<>, text>>' (double '<<' source authoring bug) to '<>' before regex matching, fixing the malformed '[< * Fix: trim openingDelim in parser + route [sidebar] blocks correctly Two related fixes in AsciidocParser: 1. `openingDelim = token.Raw.TrimEnd()` — the parser was keeping trailing whitespace from the raw delimiter line (e.g. `-- ` or `----- `), so IsMatchingClose's exact-length check would fail and the block never closed. Trimming at assignment fixes all downstream comparisons in both the verbatim and non-verbatim paths. 2. `[sidebar]` style on a `--` open block now routes to SidebarNode instead of OpenBlockNode, matching docs-builder's directive. Previously these caused entire sections (including subsequent headings and source blocks) to be consumed as unclosed block content, appearing raw in the output. Co-Authored-By: Claude Sonnet 4.6 (1M context) * Fix: dotnet format whitespace in test files Co-Authored-By: Claude Sonnet 4.6 (1M context) * Fix table comment leak, long-dash code fence tests, and book filter persistence - Lexer inTable branch: emit Comment tokens for // lines (tag::, end:: markers) so they are silently skipped rather than appended to the last table cell. - Tests: two EmitterTests covering 50-dash code block delimiters used in Watcher/Shield 2.4 docs (valid AsciiDoc: 4+ dashes). - SharedOptions: don't fall back to saved Book when --book is not passed; a bare `convert` should convert all books, not repeat the last --book filter. Co-Authored-By: Claude Sonnet 4.6 (1M context) * Regenerate CLI schema and fix Prettier formatting - docs/cli-schema.json: updated to include --no-hud flag added in ServeCommand - Frontend TSX/TS files: auto-fixed by Prettier (18 files from merge) Co-Authored-By: Claude Sonnet 4.6 (1M context) * fix: don't persist book filter across docs-migrate runs (#3835) Co-authored-by: Claude Sonnet 4.6 Co-authored-by: Claude Sonnet 4.6 (1M context) * Add adoc-compare dev tool and register it in the solution Small standalone CLI that parses a single .adoc file and prints the emitted Markdown to stdout — useful for local spot-checking the parser/emitter without running the full docs-migrate pipeline. Co-Authored-By: Claude Sonnet 4.6 * fix: add required license header to adoc-compare Program.cs Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Claude Sonnet 4.6 --- .cursor/.gitignore | 1 + AGENTS.md | 1 + docs-builder.slnx | 4 + docs/cli-schema.json | 8 + .../Builder/ConfigurationFile.cs | 2 + .../Builder/FeatureFlags.cs | 6 + .../Toc/DocumentationSetFile.cs | 2 + .../ArchiveDocsetGenerator.cs | 203 +++ .../Asciidoc/AsciidocLexer.cs | 616 +++++++ .../Asciidoc/AsciidocParser.cs | 1561 +++++++++++++++++ .../Asciidoc/Ast/AdmonitionNode.cs | 11 + .../Asciidoc/Ast/AsciidocDocument.cs | 13 + .../Asciidoc/Ast/CodeBlockNode.cs | 12 + .../Asciidoc/Ast/ColumnSpec.cs | 13 + .../Asciidoc/Ast/DescriptionListItemNode.cs | 11 + .../Asciidoc/Ast/DescriptionListNode.cs | 10 + .../Asciidoc/Ast/Enums.cs | 28 + .../Asciidoc/Ast/ExampleNode.cs | 10 + .../Asciidoc/Ast/IAsciidocNode.cs | 13 + .../Asciidoc/Ast/ImageNode.cs | 14 + .../Asciidoc/Ast/InlineNodes.cs | 33 + .../Asciidoc/Ast/ListItemNode.cs | 11 + .../Asciidoc/Ast/LiteralBlockNode.cs | 7 + .../Asciidoc/Ast/OpenBlockNode.cs | 10 + .../Asciidoc/Ast/OrderedListNode.cs | 10 + .../Asciidoc/Ast/PageBreakNode.cs | 7 + .../Asciidoc/Ast/ParagraphNode.cs | 10 + .../Asciidoc/Ast/PassthroughNode.cs | 7 + .../Asciidoc/Ast/SectionNode.cs | 15 + .../Asciidoc/Ast/SidebarNode.cs | 10 + .../Asciidoc/Ast/TableCellNode.cs | 12 + .../Asciidoc/Ast/TableNode.cs | 12 + .../Asciidoc/Ast/TableRowNode.cs | 10 + .../Asciidoc/Ast/ThematicBreakNode.cs | 7 + .../Asciidoc/Ast/UnorderedListNode.cs | 10 + .../Asciidoc/ConditionalProcessor.cs | 153 ++ .../Asciidoc/MarkdownEmitter.cs | 624 +++++++ .../Asciidoc/PageChunker.cs | 192 ++ .../BranchRefConverter.cs | 112 ++ .../Elastic.LegacyDocs.Migration.csproj | 16 + .../LatestDocsetGenerator.cs | 113 ++ .../LegacyConf.cs | 53 + .../LegacyConfParser.cs | 70 + .../SharedAttributes.cs | 170 ++ .../SourceRepoManager.cs | 256 +++ .../YamlWriter.cs | 54 + src/tooling/adoc-compare/Program.cs | 21 + src/tooling/adoc-compare/adoc-compare.csproj | 10 + .../docs-builder/Commands/ServeCommand.cs | 5 +- .../docs-builder/Http/DocumentationWebHost.cs | 17 +- .../Http/ReloadGeneratorService.cs | 23 +- src/tooling/docs-migrate/CloneCommand.cs | 86 + src/tooling/docs-migrate/ConvertCommand.cs | 274 +++ src/tooling/docs-migrate/InitCommand.cs | 59 + src/tooling/docs-migrate/ListCommand.cs | 41 + src/tooling/docs-migrate/Program.cs | 22 + src/tooling/docs-migrate/ServeCommand.cs | 37 + src/tooling/docs-migrate/SharedOptions.cs | 151 ++ src/tooling/docs-migrate/docs-migrate.csproj | 24 + .../Elastic.LegacyDocs.Migration.Tests.csproj | 11 + .../EmitterTests.cs | 307 ++++ .../LexerTests.cs | 47 + .../ParserTests.cs | 373 ++++ 63 files changed, 6014 insertions(+), 17 deletions(-) create mode 100644 .cursor/.gitignore create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/ArchiveDocsetGenerator.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocLexer.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AdmonitionNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AsciidocDocument.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/CodeBlockNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ColumnSpec.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListItemNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/Enums.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ExampleNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/IAsciidocNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ImageNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/InlineNodes.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ListItemNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/LiteralBlockNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OpenBlockNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OrderedListNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PageBreakNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ParagraphNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PassthroughNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SidebarNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableCellNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableRowNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ThematicBreakNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/UnorderedListNode.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/ConditionalProcessor.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/BranchRefConverter.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/Elastic.LegacyDocs.Migration.csproj create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/LatestDocsetGenerator.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/LegacyConf.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/LegacyConfParser.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/SharedAttributes.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/SourceRepoManager.cs create mode 100644 src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs create mode 100644 src/tooling/adoc-compare/Program.cs create mode 100644 src/tooling/adoc-compare/adoc-compare.csproj create mode 100644 src/tooling/docs-migrate/CloneCommand.cs create mode 100644 src/tooling/docs-migrate/ConvertCommand.cs create mode 100644 src/tooling/docs-migrate/InitCommand.cs create mode 100644 src/tooling/docs-migrate/ListCommand.cs create mode 100644 src/tooling/docs-migrate/Program.cs create mode 100644 src/tooling/docs-migrate/ServeCommand.cs create mode 100644 src/tooling/docs-migrate/SharedOptions.cs create mode 100644 src/tooling/docs-migrate/docs-migrate.csproj create mode 100644 tests/Elastic.LegacyDocs.Migration.Tests/Elastic.LegacyDocs.Migration.Tests.csproj create mode 100644 tests/Elastic.LegacyDocs.Migration.Tests/EmitterTests.cs create mode 100644 tests/Elastic.LegacyDocs.Migration.Tests/LexerTests.cs create mode 100644 tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs diff --git a/.cursor/.gitignore b/.cursor/.gitignore new file mode 100644 index 0000000000..8bf7cc27a1 --- /dev/null +++ b/.cursor/.gitignore @@ -0,0 +1 @@ +plans/ diff --git a/AGENTS.md b/AGENTS.md index 1df1497ed8..59db9c9813 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,6 +70,7 @@ Use the `/test` skill to pick the right test project automatically. A change to | `src/Elastic.Documentation.Configuration/` | `dotnet test tests/Elastic.Documentation.Configuration.Tests/` | | `src/Elastic.Documentation.Navigation/` | `dotnet test tests/Navigation.Tests/` (prefix dropped) | | `src/Elastic.Documentation.Indexing/` | `dotnet test tests/Elastic.Documentation.Indexing.Tests/` | +| `src/authoring/Elastic.LegacyDocs.Migration/` | `dotnet test tests/Elastic.LegacyDocs.Migration.Tests/` | | `src/tooling/essc/` | `dotnet test tests/Elastic.SiteSearch.Tests/` (essc's root namespace is `Elastic.SiteSearch.Cli`) | | `src/Elastic.ApiExplorer/` | `dotnet test tests/Elastic.ApiExplorer.Tests/` | | `src/Elastic.Documentation.Site/` | `cd src/Elastic.Documentation.Site && npm run test` | diff --git a/docs-builder.slnx b/docs-builder.slnx index e507aeaa7f..91ad0995dd 100644 --- a/docs-builder.slnx +++ b/docs-builder.slnx @@ -64,6 +64,7 @@ + @@ -86,6 +87,8 @@ + + @@ -111,6 +114,7 @@ + diff --git a/docs/cli-schema.json b/docs/cli-schema.json index abf6eb63b0..9298a52cc8 100644 --- a/docs/cli-schema.json +++ b/docs/cli-schema.json @@ -863,6 +863,14 @@ "summary": "Special flag for dotnet watch optimizations during development", "defaultValue": "false" }, + { + "role": "flag", + "name": "no-hud", + "type": "boolean", + "required": false, + "summary": "Disable the diagnostics HUD and background validation builds", + "defaultValue": "false" + }, { "role": "flag", "name": "log-level", diff --git a/src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs b/src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs index d7f56eb8a7..dd9b9a9e1d 100644 --- a/src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs +++ b/src/Elastic.Documentation.Configuration/Builder/ConfigurationFile.cs @@ -225,6 +225,8 @@ public ConfigurationFile(DocumentationSetFile docSetFile, IDocumentationSetConte _features["primary-nav"] = docSetFile.Features.PrimaryNav.Value; if (docSetFile.Features.DisableGithubEditLink.HasValue) _features["disable-github-edit-link"] = docSetFile.Features.DisableGithubEditLink.Value; + if (docSetFile.Features.GuideNav.HasValue) + _features["guide-nav"] = docSetFile.Features.GuideNav.Value; // primary-nav requires the Elastic global navigation which is not available for white-label builds if (Branding is not null && docSetFile.Features.PrimaryNav is true) diff --git a/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs b/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs index 2b0869bccf..ed7b7de9c8 100644 --- a/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs +++ b/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs @@ -58,6 +58,12 @@ public bool NavigationPreviewEnabled set => _featureFlags["navigation-preview"] = value; } + public bool GuideNavEnabled + { + get => IsEnabled("guide-nav"); + set => _featureFlags["guide-nav"] = value; + } + private bool IsEnabled(string key) { var envKey = $"FEATURE_{key.ToUpperInvariant().Replace('-', '_')}"; diff --git a/src/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cs b/src/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cs index 695c872eb7..f29db26c9f 100644 --- a/src/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cs +++ b/src/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cs @@ -960,6 +960,8 @@ public class DocumentationSetFeatures public bool? PrimaryNav { get; set; } [YamlMember(Alias = "disable-github-edit-link", ApplyNamingConventions = false)] public bool? DisableGithubEditLink { get; set; } + [YamlMember(Alias = "guide-nav", ApplyNamingConventions = false)] + public bool? GuideNav { get; set; } } [YamlSerializable] diff --git a/src/authoring/Elastic.LegacyDocs.Migration/ArchiveDocsetGenerator.cs b/src/authoring/Elastic.LegacyDocs.Migration/ArchiveDocsetGenerator.cs new file mode 100644 index 0000000000..d6c9a78573 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/ArchiveDocsetGenerator.cs @@ -0,0 +1,203 @@ +// 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.LegacyDocs.Migration.Asciidoc; +using Microsoft.Extensions.Logging; + +namespace Elastic.LegacyDocs.Migration; + +public record ArchiveGeneratorOptions +{ + public required string OutputDirectory { get; init; } + public string? BookFilter { get; init; } + public bool AllVersions { get; init; } + public int? MinMajorVersion { get; init; } + public required SourceRepoManager RepoManager { get; init; } +} + +public class ArchiveDocsetGenerator(ILogger logger) +{ + public async Task GenerateAsync(LegacyConf conf, ArchiveGeneratorOptions options, CancellationToken ct = default) + { + var books = conf.Contents + .SelectMany(c => c.Sections) + .Where(b => options.BookFilter is null || b.Prefix == options.BookFilter) + .ToList(); + + logger.LogInformation("Processing {BookCount} books in archive mode", books.Count); + + var tocRefs = new List(); + + foreach (var book in books) + { + ct.ThrowIfCancellationRequested(); + + var versions = GetVersionsToProcess(book, options.AllVersions, options.MinMajorVersion); + if (versions.Count == 0) + { + logger.LogWarning("No versions to process for {BookPrefix}", book.Prefix); + continue; + } + + logger.LogInformation("Book {Prefix}: {Count} versions to process", book.Prefix, versions.Count); + + var prefixDir = Path.Combine(options.OutputDirectory, book.Prefix); + var versionEntries = new List(); + + foreach (var version in versions) + { + ct.ThrowIfCancellationRequested(); + + var versionLabel = version.VersionLabel; + try + { + var pages = await ProcessBookVersion(book, version, options, ct); + if (pages.Count == 0) + continue; + + var versionDir = Path.Combine(prefixDir, versionLabel); + _ = Directory.CreateDirectory(versionDir); + + var fileEntries = await WritePages(pages, versionDir, ct); + YamlWriter.WriteTocYaml(Path.Combine(versionDir, "toc.yml"), fileEntries); + versionEntries.Add(new TocEntry { Folder = versionLabel }); + + logger.LogInformation("Wrote {PageCount} pages for {Prefix}/{Version}", + pages.Count, book.Prefix, versionLabel); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + logger.LogError(ex, "Failed to process {Prefix}/{Version}", book.Prefix, versionLabel); + } + } + + if (versionEntries.Count > 0) + { + tocRefs.Add(book.Prefix); + YamlWriter.WriteTocYaml(Path.Combine(prefixDir, "toc.yml"), versionEntries); + } + } + + if (tocRefs.Count > 0) + YamlWriter.WriteDocsetYaml(Path.Combine(options.OutputDirectory, "docset.yml"), "guide-archive", tocRefs); + + logger.LogInformation("Archive generation complete: {BookCount} books", tocRefs.Count); + } + + private async Task> ProcessBookVersion( + LegacyBook book, BranchRef version, ArchiveGeneratorOptions options, CancellationToken ct) + { + var versionLabel = version.VersionLabel; + var sources = await options.RepoManager.ResolveSourcesAsync(book, version, ct); + if (sources.Count == 0) + { + logger.LogWarning("No sources resolved for {Prefix} version {Version}", book.Prefix, versionLabel); + return []; + } + + var primarySource = sources[0]; + var indexPath = Path.Combine(primarySource.LocalPath, book.Index); + if (!File.Exists(indexPath)) + { + logger.LogWarning("Index file not found: {IndexPath}", indexPath); + return []; + } + + var content = await File.ReadAllTextAsync(indexPath, ct); + var basePath = Path.GetDirectoryName(indexPath) ?? primarySource.LocalPath; + var parserOptions = new AsciidocParserOptions + { + Attributes = new Dictionary + { + ["branch"] = versionLabel, + ["doc-tests-src"] = primarySource.LocalPath + } + }; + var parser = new AsciidocParser(parserOptions); + var document = parser.Parse(content, basePath); + + var emitterOptions = new MarkdownEmitterOptions + { + BookPrefix = book.Prefix, + Version = versionLabel + }; + var emitter = new MarkdownEmitter(emitterOptions); + + return PageChunker.Chunk(document, book.Chunk, emitter); + } + + private static async Task> WritePages( + IReadOnlyList pages, string directory, CancellationToken ct) + { + var entries = new List(); + foreach (var page in pages) + { + var filename = $"{page.Slug}.md"; + await File.WriteAllTextAsync(Path.Combine(directory, filename), page.MarkdownContent, ct); + entries.Add(new TocEntry { File = filename }); + } + return entries; + } + + internal static List GetVersionsToProcess(LegacyBook book, bool allVersions, int? minMajorVersion = null) + { + var branches = FilterByMinVersion(book.Branches, minMajorVersion); + + if (allVersions) + return SortBranchesDescending(branches); + + var selected = new HashSet(StringComparer.OrdinalIgnoreCase); + + if (!string.IsNullOrEmpty(book.Current)) + _ = selected.Add(book.Current); + + var grouped = branches + .Select(b => (Branch: b, Parsed: TryParseMajorMinor(b.VersionLabel))) + .Where(x => x.Parsed.HasValue) + .GroupBy(x => x.Parsed!.Value.Major); + + foreach (var group in grouped) + { + var topTwo = group + .OrderByDescending(x => x.Parsed!.Value.Minor) + .Take(2); + + foreach (var (branch, _) in topTwo) + _ = selected.Add(branch.VersionLabel); + } + + return SortBranchesDescending(branches.Where(b => selected.Contains(b.VersionLabel))); + } + + private static List FilterByMinVersion(IEnumerable branches, int? minMajor) + { + if (minMajor is null) + return branches.ToList(); + + return branches + .Where(b => + { + var parsed = TryParseMajorMinor(b.VersionLabel); + return parsed.HasValue && parsed.Value.Major >= minMajor; + }) + .ToList(); + } + + private static List SortBranchesDescending(IEnumerable branches) => + branches + .Select(b => (Branch: b, Parsed: TryParseMajorMinor(b.VersionLabel))) + .OrderByDescending(x => x.Parsed?.Major ?? 0) + .ThenByDescending(x => x.Parsed?.Minor ?? 0) + .Select(x => x.Branch) + .ToList(); + + private static (int Major, int Minor)? TryParseMajorMinor(string version) + { + var parts = version.Split('.'); + if (parts.Length >= 2 && int.TryParse(parts[0], out var major) && int.TryParse(parts[1], out var minor)) + return (major, minor); + + return null; + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocLexer.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocLexer.cs new file mode 100644 index 0000000000..9e3f5e993f --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocLexer.cs @@ -0,0 +1,616 @@ +// 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 System.Globalization; +using System.Text.RegularExpressions; + +namespace Elastic.LegacyDocs.Migration.Asciidoc; + +public enum TokenType +{ + SectionTitle, + AttributeEntry, + AttributeUnset, + BlockDelimiter, + BlockAnchor, + BlockTitle, + BlockAttribute, + ListItemUnordered, + ListItemOrdered, + ListContinuation, + DescriptionListItem, + TableDelimiter, + TableRow, + IncludeDirective, + ConditionalStart, + ConditionalEnd, + ImageBlock, + AdmonitionParagraph, + Comment, + CommentBlockDelim, + PageBreak, + ThematicBreak, + Blank, + Text +} + +public record Token(TokenType Type, string Raw, int LineNumber, TokenMetadata? Metadata = null); + +public record TokenMetadata +{ + public int? Level { get; init; } + public string? Id { get; init; } + public string? Language { get; init; } + public string? Path { get; init; } + public string? Title { get; init; } + public string? Content { get; init; } + public string? DelimiterChar { get; init; } + public string? AttributeName { get; init; } + public string? AttributeValue { get; init; } + public string? Condition { get; init; } + public string? BlockStyle { get; init; } + public Dictionary? NamedAttributes { get; init; } +} + +public static partial class AsciidocLexer +{ + private static readonly Regex SectionRegex = GetSectionRegex(); + private static readonly Regex AttributeEntryRegex = GetAttributeEntryRegex(); + private static readonly Regex AttributeUnsetRegex = GetAttributeUnsetRegex(); + private static readonly Regex BlockAnchorRegex = GetBlockAnchorRegex(); + private static readonly Regex BlockTitleRegex = GetBlockTitleRegex(); + private static readonly Regex BlockAttributeRegex = GetBlockAttributeRegex(); + private static readonly Regex BlockDelimiterRegex = GetBlockDelimiterRegex(); + private static readonly Regex UnorderedListRegex = GetUnorderedListRegex(); + private static readonly Regex OrderedListRegex = GetOrderedListRegex(); + private static readonly Regex ListContinuationRegex = GetListContinuationRegex(); + private static readonly Regex DescriptionListRegex = GetDescriptionListRegex(); + private static readonly Regex TableDelimiterRegex = GetTableDelimiterRegex(); + private static readonly Regex IncludeRegex = GetIncludeRegex(); + private static readonly Regex ConditionalStartRegex = GetConditionalStartRegex(); + private static readonly Regex ConditionalEndRegex = GetConditionalEndRegex(); + private static readonly Regex ImageBlockRegex = GetImageBlockRegex(); + private static readonly Regex AdmonitionRegex = GetAdmonitionRegex(); + private static readonly Regex CommentBlockDelimRegex = GetCommentBlockDelimRegex(); + private static readonly Regex CommentRegex = GetCommentRegex(); + private static readonly Regex PageBreakRegex = GetPageBreakRegex(); + private static readonly Regex ThematicBreakRegex = GetThematicBreakRegex(); + private static readonly Regex BlankRegex = GetBlankRegex(); + + [GeneratedRegex(@"^(={1,6})\s+(.+)$")] + private static partial Regex GetSectionRegex(); + + [GeneratedRegex(@"^:([^!:][^:]*?):\s*(.*)$")] + private static partial Regex GetAttributeEntryRegex(); + + [GeneratedRegex(@"^:!([^:]+):$")] + private static partial Regex GetAttributeUnsetRegex(); + + [GeneratedRegex(@"^\[\[([^\]]+)\]\]$")] + private static partial Regex GetBlockAnchorRegex(); + + [GeneratedRegex(@"^\.(\S.*)$")] + private static partial Regex GetBlockTitleRegex(); + + [GeneratedRegex(@"^\[(.+)\]\s*$")] + private static partial Regex GetBlockAttributeRegex(); + + [GeneratedRegex(@"^(-{4,}|\.{4,}|={4,}|\*{4,}|\+{4,}|/{4,}|-{2})\s*$")] + private static partial Regex GetBlockDelimiterRegex(); + + [GeneratedRegex(@"^(\*{1,5})\s+(.+)$")] + private static partial Regex GetUnorderedListRegex(); + + [GeneratedRegex(@"^(\.{1,5})\s+(.+)$")] + private static partial Regex GetOrderedListRegex(); + + [GeneratedRegex(@"^\+\s*$")] + private static partial Regex GetListContinuationRegex(); + + [GeneratedRegex(@"^(.+?)(:{2,4})\s*(.*)$")] + private static partial Regex GetDescriptionListRegex(); + + [GeneratedRegex(@"^\|={3,}\s*$")] + private static partial Regex GetTableDelimiterRegex(); + + [GeneratedRegex(@"^include::(.+?)\[(.*?)?\]$")] + private static partial Regex GetIncludeRegex(); + + [GeneratedRegex(@"^(ifdef|ifndef|ifeval)::(.*?)\[(.*?)?\]$")] + private static partial Regex GetConditionalStartRegex(); + + [GeneratedRegex(@"^endif::(.*?)?\[(.*?)?\]$")] + private static partial Regex GetConditionalEndRegex(); + + [GeneratedRegex(@"^image::(.+?)\[(.*?)?\]$")] + private static partial Regex GetImageBlockRegex(); + + [GeneratedRegex(@"^(NOTE|TIP|WARNING|IMPORTANT|CAUTION):\s+(.+)$")] + private static partial Regex GetAdmonitionRegex(); + + [GeneratedRegex(@"^/{4,}$")] + private static partial Regex GetCommentBlockDelimRegex(); + + [GeneratedRegex(@"^//\s*(.*)$")] + private static partial Regex GetCommentRegex(); + + [GeneratedRegex(@"^<<<\s*$")] + private static partial Regex GetPageBreakRegex(); + + [GeneratedRegex(@"^'{3,}\s*$")] + private static partial Regex GetThematicBreakRegex(); + + [GeneratedRegex(@"^\s*$")] + private static partial Regex GetBlankRegex(); + + public static IReadOnlyList Tokenize(string content) + { + var lines = content.Split('\n'); + var tokens = new List(); + var inCommentBlock = false; + var inVerbatimBlock = false; + var verbatimDelimiter = ""; + var inTable = false; + + for (var i = 0; i < lines.Length; i++) + { + var line = lines[i].TrimEnd('\r'); + var lineNumber = i + 1; + + if (inCommentBlock) + { + if (CommentBlockDelimRegex.IsMatch(line)) + inCommentBlock = false; + continue; + } + + if (inVerbatimBlock) + { + if (IsMatchingDelimiter(line, verbatimDelimiter)) + { + inVerbatimBlock = false; + tokens.Add(new Token(TokenType.BlockDelimiter, line, lineNumber, new TokenMetadata { DelimiterChar = verbatimDelimiter[..1] })); + } + else + { + tokens.Add(new Token(TokenType.Text, line, lineNumber)); + } + continue; + } + + if (CommentBlockDelimRegex.IsMatch(line)) + { + inCommentBlock = true; + continue; + } + + var match = BlockDelimiterRegex.Match(line); + if (match.Success) + { + var delim = match.Groups[1].Value; + var delimChar = delim[..1]; + + if (delimChar is "-" or "." or "/" or "+") + { + // `--` (length 2) is an open block delimiter, not verbatim. + // Only `----`, `....`, `++++`, `////` (length >= 4) are verbatim. + if (delim.Length < 4) + { + tokens.Add(new Token(TokenType.BlockDelimiter, line, lineNumber, new TokenMetadata { DelimiterChar = delimChar })); + continue; + } + + if (delimChar == "/") + { + inCommentBlock = true; + continue; + } + + inVerbatimBlock = true; + verbatimDelimiter = delim; + tokens.Add(new Token(TokenType.BlockDelimiter, line, lineNumber, new TokenMetadata { DelimiterChar = delimChar })); + continue; + } + + if (delimChar is "=" or "*") + { + tokens.Add(new Token(TokenType.BlockDelimiter, line, lineNumber, new TokenMetadata { DelimiterChar = delimChar })); + continue; + } + } + + if (inTable) + { + if (TableDelimiterRegex.IsMatch(line)) + { + inTable = false; + tokens.Add(new Token(TokenType.TableDelimiter, line, lineNumber)); + continue; + } + + if (BlankRegex.IsMatch(line)) + { + tokens.Add(new Token(TokenType.Blank, line, lineNumber)); + continue; + } + + var condStart = ConditionalStartRegex.Match(line); + if (condStart.Success) + { + tokens.Add(new Token(TokenType.ConditionalStart, line, lineNumber, new TokenMetadata + { + Condition = condStart.Groups[2].Value, + Content = condStart.Groups[3].Value, + BlockStyle = condStart.Groups[1].Value + })); + continue; + } + + var condEnd = ConditionalEndRegex.Match(line); + if (condEnd.Success) + { + tokens.Add(new Token(TokenType.ConditionalEnd, line, lineNumber, new TokenMetadata + { + Condition = condEnd.Groups[1].Value + })); + continue; + } + + if (CommentRegex.IsMatch(line)) + { + tokens.Add(new Token(TokenType.Comment, line, lineNumber)); + continue; + } + + if (line.StartsWith('|')) + { + tokens.Add(new Token(TokenType.TableRow, line, lineNumber, new TokenMetadata { Content = line[1..] })); + continue; + } + + tokens.Add(new Token(TokenType.Text, line, lineNumber)); + continue; + } + + if (TableDelimiterRegex.IsMatch(line)) + { + inTable = true; + tokens.Add(new Token(TokenType.TableDelimiter, line, lineNumber)); + continue; + } + + if (TryMatchToken(line, lineNumber, out var token)) + { + tokens.Add(token); + continue; + } + + tokens.Add(new Token(TokenType.Text, line, lineNumber)); + } + + return tokens; + } + + private static bool IsMatchingDelimiter(string line, string openDelimiter) + { + if (openDelimiter.Length < 2) + return false; + + var delimChar = openDelimiter[0]; + // Trim trailing whitespace so source bugs like `---- ` still close a `----` block + var trimmed = line.TrimEnd(); + // Require exact length so e.g. `--------` does not close a `----` block + return trimmed.Length == openDelimiter.Length && trimmed.All(c => c == delimChar); + } + + private static bool TryMatchToken(string line, int lineNumber, out Token token) + { + token = default!; + + var m = SectionRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.SectionTitle, line, lineNumber, new TokenMetadata + { + Level = m.Groups[1].Value.Length - 1, + Title = m.Groups[2].Value.Trim() + }); + return true; + } + + m = AttributeUnsetRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.AttributeUnset, line, lineNumber, new TokenMetadata + { + AttributeName = m.Groups[1].Value + }); + return true; + } + + m = AttributeEntryRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.AttributeEntry, line, lineNumber, new TokenMetadata + { + AttributeName = m.Groups[1].Value, + AttributeValue = m.Groups[2].Value + }); + return true; + } + + m = BlockAnchorRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.BlockAnchor, line, lineNumber, new TokenMetadata + { + Id = m.Groups[1].Value + }); + return true; + } + + m = ConditionalStartRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.ConditionalStart, line, lineNumber, new TokenMetadata + { + Condition = m.Groups[2].Value, + Content = m.Groups[3].Value, + BlockStyle = m.Groups[1].Value + }); + return true; + } + + m = ConditionalEndRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.ConditionalEnd, line, lineNumber, new TokenMetadata + { + Condition = m.Groups[1].Value + }); + return true; + } + + m = IncludeRegex.Match(line); + if (m.Success) + { + var attrs = ParseBlockAttributeContent(m.Groups[2].Value); + token = new Token(TokenType.IncludeDirective, line, lineNumber, new TokenMetadata + { + Path = m.Groups[1].Value, + NamedAttributes = attrs + }); + return true; + } + + m = ImageBlockRegex.Match(line); + if (m.Success) + { + var attrs = ParseInlineAttributes(m.Groups[2].Value); + token = new Token(TokenType.ImageBlock, line, lineNumber, new TokenMetadata + { + Path = m.Groups[1].Value, + Title = attrs.GetValueOrDefault("alt") ?? attrs.GetValueOrDefault("0"), + NamedAttributes = attrs + }); + return true; + } + + m = AdmonitionRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.AdmonitionParagraph, line, lineNumber, new TokenMetadata + { + BlockStyle = m.Groups[1].Value, + Content = m.Groups[2].Value + }); + return true; + } + + if (PageBreakRegex.IsMatch(line)) + { + token = new Token(TokenType.PageBreak, line, lineNumber); + return true; + } + + if (ThematicBreakRegex.IsMatch(line)) + { + token = new Token(TokenType.ThematicBreak, line, lineNumber); + return true; + } + + m = ListContinuationRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.ListContinuation, line, lineNumber); + return true; + } + + m = UnorderedListRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.ListItemUnordered, line, lineNumber, new TokenMetadata + { + Level = m.Groups[1].Value.Length, + Content = m.Groups[2].Value + }); + return true; + } + + m = OrderedListRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.ListItemOrdered, line, lineNumber, new TokenMetadata + { + Level = m.Groups[1].Value.Length, + Content = m.Groups[2].Value + }); + return true; + } + + m = CommentRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.Comment, line, lineNumber, new TokenMetadata + { + Content = m.Groups[1].Value + }); + return true; + } + + if (BlankRegex.IsMatch(line)) + { + token = new Token(TokenType.Blank, line, lineNumber); + return true; + } + + m = BlockAttributeRegex.Match(line); + if (m.Success && !BlockAnchorRegex.IsMatch(line)) + { + var content = m.Groups[1].Value; + var parsed = ParseBlockAttributeContent(content); + string? style = null; + string? language = null; + + var positional = content.Split(','); + if (positional.Length > 0) + { + var first = positional[0].Trim().Trim('"'); + if (!first.Contains('=')) + style = first; + } + if (positional.Length > 1 && style?.Equals("source", StringComparison.OrdinalIgnoreCase) == true) + { + var second = positional[1].Trim().Trim('"'); + if (!second.Contains('=')) + language = second; + } + + token = new Token(TokenType.BlockAttribute, line, lineNumber, new TokenMetadata + { + BlockStyle = style, + Language = language, + Content = content, + NamedAttributes = parsed + }); + return true; + } + + m = BlockTitleRegex.Match(line); + if (m.Success) + { + token = new Token(TokenType.BlockTitle, line, lineNumber, new TokenMetadata + { + Title = m.Groups[1].Value + }); + return true; + } + + m = DescriptionListRegex.Match(line); + if (m.Success) + { + var term = m.Groups[1].Value; + var separator = m.Groups[2].Value; + var desc = m.Groups[3].Value; + if (!term.Contains("://") && !term.StartsWith("http", StringComparison.OrdinalIgnoreCase)) + { + token = new Token(TokenType.DescriptionListItem, line, lineNumber, new TokenMetadata + { + Title = term, + Content = desc, + Level = separator.Length + }); + return true; + } + } + + return false; + } + + private static Dictionary ParseBlockAttributeContent(string content) + { + var result = new Dictionary(StringComparer.OrdinalIgnoreCase); + if (string.IsNullOrWhiteSpace(content)) + return result; + + var parts = SplitRespectingQuotes(content); + var positionalIndex = 0; + foreach (var part in parts) + { + var trimmed = part.Trim(); + var eqIndex = trimmed.IndexOf('='); + if (eqIndex > 0) + { + var key = trimmed[..eqIndex].Trim(); + var value = trimmed[(eqIndex + 1)..].Trim().Trim('"'); + result[key] = value; + } + else + { + result[positionalIndex.ToString(CultureInfo.InvariantCulture)] = trimmed.Trim('"'); + positionalIndex++; + } + } + return result; + } + + private static Dictionary ParseInlineAttributes(string content) + { + var result = new Dictionary(StringComparer.OrdinalIgnoreCase); + if (string.IsNullOrWhiteSpace(content)) + return result; + + var parts = SplitRespectingQuotes(content); + var positionalIndex = 0; + foreach (var part in parts) + { + var trimmed = part.Trim(); + var eqIndex = trimmed.IndexOf('='); + if (eqIndex > 0) + { + var key = trimmed[..eqIndex].Trim(); + var value = trimmed[(eqIndex + 1)..].Trim().Trim('"'); + result[key] = value; + } + else + { + if (positionalIndex == 0) + result["alt"] = trimmed.Trim('"'); + result[positionalIndex.ToString(CultureInfo.InvariantCulture)] = trimmed.Trim('"'); + positionalIndex++; + } + } + return result; + } + + private static List SplitRespectingQuotes(string input) + { + var parts = new List(); + var current = new System.Text.StringBuilder(); + var inQuotes = false; + + foreach (var c in input) + { + if (c == '"') + { + inQuotes = !inQuotes; + _ = current.Append(c); + } + else if (c == ',' && !inQuotes) + { + parts.Add(current.ToString()); + _ = current.Clear(); + } + else + { + _ = current.Append(c); + } + } + + if (current.Length > 0) + parts.Add(current.ToString()); + + return parts; + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs new file mode 100644 index 0000000000..2920809442 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs @@ -0,0 +1,1561 @@ +// 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 System.Globalization; +using System.Text.RegularExpressions; +using Elastic.LegacyDocs.Migration.Asciidoc.Ast; + +namespace Elastic.LegacyDocs.Migration.Asciidoc; + +public record AsciidocParserOptions +{ + public Dictionary Attributes { get; init; } = []; + public int MaxIncludeDepth { get; init; } = 64; + public Func? FileReader { get; init; } + public Action? OnDiagnostic { get; init; } +} + +public partial class AsciidocParser(AsciidocParserOptions options) +{ + private readonly Dictionary _attributes = new(options.Attributes, StringComparer.OrdinalIgnoreCase); + + /// + /// Returns the resolved attributes after parsing. Useful for extracting attribute definitions + /// from a shared attributes file to seed into subsequent parsers. + /// + public IReadOnlyDictionary ResolvedAttributes => _attributes; + + /// + /// Parses a shared AsciiDoc attributes file (`:name: value` definitions) with the given + /// seed attributes and returns the fully-resolved attribute map, excluding ProductNames keys. + /// + public static Dictionary LoadAttributeFile(string path, Dictionary seedAttributes) + { + if (!File.Exists(path)) + return []; + var content = File.ReadAllText(path); + var parser = new AsciidocParser(new AsciidocParserOptions { Attributes = seedAttributes }); + _ = parser.Parse(content, Path.GetDirectoryName(path) ?? ""); + return new Dictionary(parser._attributes, StringComparer.OrdinalIgnoreCase); + } + + private IReadOnlyList _tokens = []; + private int _pos; + private int _includeDepth; + private string _basePath = ""; + + public AsciidocDocument Parse(string filePath) + { + var content = ReadFile(filePath) ?? throw new FileNotFoundException($"File not found: {filePath}"); + return Parse(content, Path.GetDirectoryName(filePath) ?? ""); + } + + /// + /// Sets an attribute with eager expansion of its value (Asciidoctor semantics). + /// Product-name keys defined in are intentionally + /// kept unresolved so the emitter can emit them as docs-builder {{sub}} placeholders. + /// + private void SetAttribute(string name, string? value) + { + if (value is null) + { + _ = _attributes.Remove(name); + return; + } + // Product name subs stay unresolved so the emitter emits {{name}} for docs-builder substitution + if (SharedAttributes.ProductNames.ContainsKey(name)) + return; + // Eagerly expand attribute values at definition time (Asciidoctor semantics) + _attributes[name] = SubstituteAttributes(value); + } + + /// + /// Sets the base path and updates the docdir attribute, which is per-file in Asciidoctor. + /// + private void SetBasePath(string basePath) + { + _basePath = basePath; + _attributes["docdir"] = basePath; + } + + public AsciidocDocument Parse(string content, string basePath) + { + SetBasePath(basePath); + var rawTokens = AsciidocLexer.Tokenize(content); + var processed = ConditionalProcessor.Process(rawTokens, _attributes); + _tokens = processed; + _pos = 0; + + var doc = new AsciidocDocument(); + string? pendingId = null; + string? pendingTitle = null; + TokenMetadata? pendingBlockAttr = null; + + while (_pos < _tokens.Count) + { + var token = Current; + + switch (token.Type) + { + case TokenType.AttributeEntry: + SetAttribute(token.Metadata!.AttributeName!, token.Metadata.AttributeValue); + _pos++; + break; + + case TokenType.AttributeUnset: + _ = _attributes.Remove(token.Metadata!.AttributeName!); + _pos++; + break; + + case TokenType.BlockAnchor: + pendingId = token.Metadata!.Id; + _pos++; + break; + + case TokenType.BlockTitle: + pendingTitle = token.Metadata!.Title; + _pos++; + break; + + case TokenType.BlockAttribute: + pendingBlockAttr = token.Metadata; + _pos++; + break; + + case TokenType.SectionTitle: + if (doc.Title is null && token.Metadata!.Level == 1) + { + doc = doc with + { + Title = SubstituteAttributes(token.Metadata.Title!), + Id = pendingId, + Attributes = new(_attributes, StringComparer.OrdinalIgnoreCase) + }; + pendingId = null; + pendingTitle = null; + _pos++; + } + else + { + var section = ParseSection(pendingId, pendingTitle); + doc.Children.Add(section); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + } + break; + + case TokenType.Blank: + case TokenType.Comment: + _pos++; + break; + + case TokenType.IncludeDirective: + var included = ProcessInclude(token); + if (included != null) + doc.Children.AddRange(included); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + _pos++; + break; + + default: + var block = ParseBlock(pendingId, pendingTitle, pendingBlockAttr); + if (block != null) + doc.Children.Add(block); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + break; + } + } + + return doc with { Attributes = new(_attributes, StringComparer.OrdinalIgnoreCase) }; + } + + private Token Current => _tokens[_pos]; + + private SectionNode ParseSection(string? id, string? title) + { + var token = Current; + var level = token.Metadata!.Level!.Value; + var sectionTitle = SubstituteAttributes(title ?? token.Metadata.Title!); + var sectionId = id ?? ExtractInlineAnchor(sectionTitle); + _pos++; + + var children = new List(); + string? pendingId = null; + string? pendingTitle = null; + TokenMetadata? pendingBlockAttr = null; + var pendingStart = _pos; + + while (_pos < _tokens.Count) + { + var cur = Current; + + if (cur.Type == TokenType.SectionTitle && cur.Metadata!.Level!.Value <= level) + { + _pos = pendingStart; + break; + } + + switch (cur.Type) + { + case TokenType.AttributeEntry: + SetAttribute(cur.Metadata!.AttributeName!, cur.Metadata.AttributeValue); + _pos++; + pendingStart = _pos; + break; + + case TokenType.AttributeUnset: + _ = _attributes.Remove(cur.Metadata!.AttributeName!); + _pos++; + pendingStart = _pos; + break; + + case TokenType.BlockAnchor: + pendingId = cur.Metadata!.Id; + _pos++; + break; + + case TokenType.BlockTitle: + pendingTitle = cur.Metadata!.Title; + _pos++; + break; + + case TokenType.BlockAttribute: + pendingBlockAttr = cur.Metadata; + _pos++; + break; + + case TokenType.SectionTitle: + var childSection = ParseSection(pendingId, null); + children.Add(childSection); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + pendingStart = _pos; + break; + + case TokenType.Blank: + case TokenType.Comment: + _pos++; + break; + + case TokenType.IncludeDirective: + var included = ProcessInclude(cur); + if (included != null) + children.AddRange(included); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + _pos++; + pendingStart = _pos; + break; + + default: + var block = ParseBlock(pendingId, pendingTitle, pendingBlockAttr); + if (block != null) + children.Add(block); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + pendingStart = _pos; + break; + } + } + + return new SectionNode { Level = level, Title = sectionTitle, Id = sectionId, Children = children }; + } + + private IAsciidocNode? ParseBlock(string? id, string? title, TokenMetadata? blockAttr) + { + if (_pos >= _tokens.Count) + return null; + + var token = Current; + + var block = token.Type switch + { + TokenType.BlockDelimiter => ParseDelimitedBlock(blockAttr), + TokenType.ListItemUnordered => ParseUnorderedList(), + TokenType.ListItemOrdered => ParseOrderedList(), + TokenType.DescriptionListItem => ParseDescriptionList(), + TokenType.TableDelimiter => ParseTable(blockAttr), + TokenType.AdmonitionParagraph => ParseAdmonitionParagraph(), + TokenType.ImageBlock => ParseImageBlock(title), + TokenType.PageBreak => ParsePageBreak(), + TokenType.ThematicBreak => ParseThematicBreak(), + TokenType.Text when CalloutItemRegex().IsMatch(token.Raw) => ParseCalloutList(), + TokenType.Text => ParseParagraph(), + TokenType.IncludeDirective => ParseIncludeBlock(), + TokenType.ConditionalStart or TokenType.ConditionalEnd => SkipConditional(), + _ => SkipToken() + }; + + return id is not null && block is not null ? new AnchoredBlock(id, block) : block; + } + + private IAsciidocNode? ParseDelimitedBlock(TokenMetadata? blockAttr) + { + var token = Current; + var delimChar = token.Metadata?.DelimiterChar ?? "-"; + // Trim trailing whitespace from the raw delimiter so `-- ` matches `--` as its close + var openingDelim = token.Raw.TrimEnd(); + _pos++; + + var style = blockAttr?.BlockStyle?.ToLowerInvariant(); + + var contentLines = new List(); + var children = new List(); + + if (IsVerbatimDelimiter(delimChar, openingDelim)) + { + while (_pos < _tokens.Count) + { + var cur = Current; + if (cur.Type == TokenType.BlockDelimiter && IsMatchingClose(cur.Raw, openingDelim)) + { + _pos++; + break; + } + contentLines.Add(cur.Raw); + _pos++; + } + + // Resolve include-tagged:: directives embedded inside verbatim blocks + contentLines = ResolveVerbatimIncludes(contentLines); + } + else + { + var innerTokens = CollectDelimitedTokens(openingDelim); + children = ParseTokensAsBlocks(innerTokens); + } + + // Collect callout annotations that follow a code block (e.g. <1> First step). + // Skip any trailing comment lines (// TEST[...]) and one optional blank line; + // restore position if what follows is not callout markers. + var callouts = new List(); + if (delimChar is "-" && openingDelim.Length >= 4) + { + var savedPos = _pos; + while (_pos < _tokens.Count && Current.Type == TokenType.Comment) + _pos++; + if (_pos < _tokens.Count && Current.Type == TokenType.Blank) + _pos++; + if (_pos >= _tokens.Count || Current.Type != TokenType.Text || !CalloutItemRegex().IsMatch(Current.Raw)) + _pos = savedPos; // not callouts — restore so the normal token handling runs + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + var calloutMatch = CalloutItemRegex().Match(Current.Raw); + if (!calloutMatch.Success) + break; + if (int.TryParse(calloutMatch.Groups[1].Value, out var idx) && idx >= 1) + { + while (callouts.Count < idx) + callouts.Add(""); + var text = calloutMatch.Groups[2].Value; + _pos++; + // Collect any continuation lines (Text tokens without prefix) + while (_pos < _tokens.Count && Current.Type == TokenType.Text && !CalloutItemRegex().IsMatch(Current.Raw)) + { + text += " " + Current.Raw.Trim(); + _pos++; + } + callouts[idx - 1] = text; + continue; + } + _pos++; + } + } + + return delimChar switch + { + "-" when openingDelim.Length >= 4 || style == "source" => new CodeBlockNode + { + Language = blockAttr?.Language, + Source = string.Join('\n', contentLines), + Callouts = callouts + }, + "." => new LiteralBlockNode(string.Join('\n', contentLines)), + "=" when IsAdmonitionStyle(style) => new AdmonitionNode + { + Type = ParseAdmonitionType(style!), + Children = children + }, + "=" => new ExampleNode { Children = children }, + "*" => new SidebarNode { Children = children }, + "+" => new PassthroughNode(string.Join('\n', contentLines)), + "-" when openingDelim == "--" => style switch + { + "source" => new CodeBlockNode { Language = blockAttr?.Language, Source = string.Join('\n', contentLines) }, + _ when IsAdmonitionStyle(style) => new AdmonitionNode + { + Type = ParseAdmonitionType(style!), + Children = children.Count > 0 ? children : WrapAsBlocks(contentLines) + }, + "sidebar" => new SidebarNode { Children = children.Count > 0 ? children : WrapAsBlocks(contentLines) }, + _ => new OpenBlockNode { Children = children.Count > 0 ? children : WrapAsBlocks(contentLines) } + }, + "/" => null, + _ => new OpenBlockNode { Children = children.Count > 0 ? children : WrapAsBlocks(contentLines) } + }; + } + + [GeneratedRegex(@"^<(\d+)>\s+(.+)$")] + private static partial Regex CalloutItemRegex(); + + [GeneratedRegex(@"^include::([^\[]+)\[([^\]]*)\]\s*$")] + private static partial Regex TableIncludeRegex(); + + [GeneratedRegex(@"^include-tagged::(.+?)\[([^\]]*)\]\s*$")] + private static partial Regex IncludeTaggedInVerbatimRegex(); + + // Standard AsciiDoc tagged include inside a verbatim block: include::path[tag=name] + [GeneratedRegex(@"^include::(.+?)\[tag=([^\]]+)\]\s*$")] + private static partial Regex IncludeTaggedStandardInVerbatimRegex(); + + // Full-file include inside a verbatim block: include::path[] or include::path[indent=0] etc. + [GeneratedRegex(@"^include::(.+?)\[[^\]]*\]\s*$")] + private static partial Regex IncludeFullFileInVerbatimRegex(); + + // Conditional markers that can appear inside verbatim blocks (e.g. ifeval::[...]/endif::[]) + [GeneratedRegex(@"^(?:ifdef|ifndef|ifeval|endif)::[^\[]*\[.*?\]\s*$")] + private static partial Regex VerbatimConditionalRegex(); + + /// + /// Resolves include directives and strips stray conditional markers inside verbatim blocks. + /// Handles both the Elastic include-tagged::path[tag] extension and the standard + /// AsciiDoc include::path[tag=name] syntax with a tag qualifier. + /// + private List ResolveVerbatimIncludes(List lines) + { + // Fast path: nothing to do + if (!lines.Any(l => + l.Contains("include-tagged::", StringComparison.Ordinal) || + l.Contains("include::", StringComparison.Ordinal) || + l.Contains("ifeval::", StringComparison.Ordinal) || + l.Contains("ifdef::", StringComparison.Ordinal) || + l.Contains("ifndef::", StringComparison.Ordinal) || + l.Contains("endif::", StringComparison.Ordinal))) + return lines; + + var result = new List(lines.Count); + foreach (var line in lines) + { + var trimmed = line.TrimStart(); + + // Strip stray conditional markers (ifeval/ifdef/ifndef/endif) from verbatim content. + // The surrounding content is always kept since we can't evaluate conditions here. + if (VerbatimConditionalRegex().IsMatch(trimmed)) + continue; + + var taggedMatch = IncludeTaggedInVerbatimRegex().Match(trimmed); + if (taggedMatch.Success) + { + result.AddRange(ResolveTaggedInclude(taggedMatch.Groups[1].Value, taggedMatch.Groups[2].Value.Trim(), line)); + continue; + } + + var standardMatch = IncludeTaggedStandardInVerbatimRegex().Match(trimmed); + if (standardMatch.Success) + { + result.AddRange(ResolveTaggedInclude(standardMatch.Groups[1].Value, standardMatch.Groups[2].Value.Trim(), line)); + continue; + } + + var fullFileMatch = IncludeFullFileInVerbatimRegex().Match(trimmed); + if (fullFileMatch.Success) + { + result.AddRange(ResolveFullFileInclude(fullFileMatch.Groups[1].Value, line)); + continue; + } + + result.Add(line); + } + return result; + } + + private IEnumerable ResolveTaggedInclude(string rawPathToken, string tag, string originalLine) + { + var rawPath = SubstituteAttributes(rawPathToken); + var resolvedPath = Path.IsPathRooted(rawPath) + ? Path.GetFullPath(rawPath) + : Path.GetFullPath(Path.Combine(_basePath, rawPath)); + + var fileContent = ReadFile(resolvedPath); + if (fileContent is null) + { + options.OnDiagnostic?.Invoke($"include not resolved: {rawPath} (resolved to {resolvedPath})"); + return [originalLine]; + } + + return ExtractTaggedLines(fileContent, tag); + } + + private IEnumerable ResolveFullFileInclude(string rawPathToken, string originalLine) + { + var rawPath = SubstituteAttributes(rawPathToken); + var resolvedPath = Path.IsPathRooted(rawPath) + ? Path.GetFullPath(rawPath) + : Path.GetFullPath(Path.Combine(_basePath, rawPath)); + + var fileContent = ReadFile(resolvedPath); + if (fileContent is null) + { + options.OnDiagnostic?.Invoke($"include not resolved: {rawPath} (resolved to {resolvedPath})"); + return [originalLine]; + } + + return fileContent.TrimEnd('\n', '\r').Split('\n'); + } + + private static List ExtractTaggedLines(string content, string tag) + { + var lines = content.Split('\n'); + var result = new List(); + var inTag = false; + int? dedentWidth = null; + + var escapedTag = Regex.Escape(tag); + var startPattern = new Regex($@"tag::{escapedTag}\[\]"); + var endPattern = new Regex($@"end::{escapedTag}\[\]"); + + foreach (var line in lines) + { + var trimmed = line.TrimStart(); + if (!inTag && startPattern.IsMatch(trimmed)) + { + inTag = true; + dedentWidth = line.Length - trimmed.Length; + continue; + } + if (inTag && endPattern.IsMatch(trimmed)) + { + inTag = false; + continue; + } + if (!inTag) + continue; + + // Dedent by the leading whitespace of the tag:: line + result.Add(dedentWidth is > 0 && line.Length >= dedentWidth + ? line[dedentWidth.Value..] + : line); + } + return result; + } + + /// + /// Returns true when the opening delimiter's content should be collected verbatim (raw text lines). + /// Open blocks (--) are structural, not verbatim, even though their delimChar is -. + /// + private static bool IsVerbatimDelimiter(string delimChar, string openingDelim) => + delimChar is "-" or "." or "+" or "/" && openingDelim.Length >= 4; + + private static bool IsMatchingClose(string line, string openingDelim) + { + if (openingDelim.Length < 2) + return false; + + var delimChar = openingDelim[0]; + // Trim trailing whitespace so source bugs like `---- ` still close a `----` block + var trimmed = line.TrimEnd(); + // Require exact length so `--------` does not close a `----` block + return trimmed.Length == openingDelim.Length && trimmed.All(c => c == delimChar); + } + + private List CollectDelimitedTokens(string openingDelim) + { + var inner = new List(); + while (_pos < _tokens.Count) + { + var cur = Current; + if (cur.Type == TokenType.BlockDelimiter && IsMatchingClose(cur.Raw, openingDelim)) + { + _pos++; + break; + } + inner.Add(cur); + _pos++; + } + return inner; + } + + private List ParseTokensAsBlocks(List innerTokens) + { + var savedTokens = _tokens; + var savedPos = _pos; + _tokens = innerTokens; + _pos = 0; + + var blocks = new List(); + string? pendingId = null; + string? pendingTitle = null; + TokenMetadata? pendingBlockAttr = null; + + while (_pos < _tokens.Count) + { + var t = Current; + switch (t.Type) + { + case TokenType.BlockAnchor: + pendingId = t.Metadata!.Id; + _pos++; + break; + case TokenType.BlockTitle: + pendingTitle = t.Metadata!.Title; + _pos++; + break; + case TokenType.BlockAttribute: + pendingBlockAttr = t.Metadata; + _pos++; + break; + case TokenType.Blank: + case TokenType.Comment: + _pos++; + break; + case TokenType.AttributeEntry: + SetAttribute(t.Metadata!.AttributeName!, t.Metadata.AttributeValue); + _pos++; + break; + case TokenType.AttributeUnset: + _ = _attributes.Remove(t.Metadata!.AttributeName!); + _pos++; + break; + default: + var block = ParseBlock(pendingId, pendingTitle, pendingBlockAttr); + if (block != null) + blocks.Add(block); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + break; + } + } + + _tokens = savedTokens; + _pos = savedPos; + return blocks; + } + + private List WrapAsBlocks(List lines) + { + if (lines.Count == 0) + return []; + + var text = string.Join('\n', lines).Trim(); + if (string.IsNullOrEmpty(text)) + return []; + + return [new ParagraphNode { Inlines = ParseInlines(SubstituteAttributes(text)) }]; + } + + private IAsciidocNode ParseUnorderedList() + { + var list = new UnorderedListNode(); + while (_pos < _tokens.Count && Current.Type == TokenType.ListItemUnordered) + { + var item = ParseListItem(TokenType.ListItemUnordered); + list.Items.Add(item); + } + return list; + } + + private IAsciidocNode ParseOrderedList() + { + var list = new OrderedListNode(); + while (_pos < _tokens.Count && Current.Type == TokenType.ListItemOrdered) + { + var item = ParseListItem(TokenType.ListItemOrdered); + list.Items.Add(item); + } + return list; + } + + private ListItemNode ParseListItem(TokenType listType) + { + var token = Current; + var level = token.Metadata!.Level!.Value; + // Collect the first line and any trailing Text tokens together before parsing, + // so that multi-line xrefs (<>) are matched correctly. + var firstLineText = token.Metadata.Content!; + _pos++; + + var children = new List(); + List? inlines = null; + + while (_pos < _tokens.Count) + { + var cur = Current; + + if (inlines is null && cur.Type == TokenType.Text) + { + // Collect the first line + consecutive continuation text lines, then parse once + var textLines = new List { firstLineText }; + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + textLines.Add(Current.Raw); + _pos++; + } + inlines = ParseInlines(SubstituteAttributes(string.Join('\n', textLines))); + continue; + } + + inlines ??= ParseInlines(SubstituteAttributes(firstLineText)); + + if (cur.Type == TokenType.ListContinuation) + { + _pos++; + string? contId = null; + string? contTitle = null; + TokenMetadata? contBlockAttr = null; + + while (_pos < _tokens.Count) + { + var peek = Current; + if (peek.Type == TokenType.BlockAnchor) + { + contId = peek.Metadata!.Id; + _pos++; + } + else if (peek.Type == TokenType.BlockTitle) + { + contTitle = peek.Metadata!.Title; + _pos++; + } + else if (peek.Type == TokenType.BlockAttribute) + { + contBlockAttr = peek.Metadata; + _pos++; + } + else if (peek.Type == TokenType.Blank) + { + _pos++; + } + else + { + break; + } + } + + if (_pos < _tokens.Count) + { + var continued = ParseBlock(contId, contTitle, contBlockAttr); + if (continued != null) + children.Add(continued); + } + continue; + } + + if (cur.Type == listType && cur.Metadata!.Level!.Value > level) + { + var nested = listType == TokenType.ListItemUnordered + ? ParseUnorderedList() + : ParseOrderedList(); + children.Add(nested); + continue; + } + + if (cur.Type == TokenType.Text) + { + // Collect consecutive text lines and parse together so multi-line xrefs (<>) match + var textLines = new List(); + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + textLines.Add(Current.Raw); + _pos++; + } + inlines.AddRange(ParseInlines(SubstituteAttributes(string.Join('\n', textLines)))); + continue; + } + + break; + } + + inlines ??= ParseInlines(SubstituteAttributes(firstLineText)); + return new ListItemNode { Inlines = inlines, Children = children }; + } + + private IAsciidocNode ParseDescriptionList() + { + var list = new DescriptionListNode(); + while (_pos < _tokens.Count && Current.Type == TokenType.DescriptionListItem) + { + var token = Current; + var term = ParseInlines(SubstituteAttributes(token.Metadata!.Title!)); + var descText = token.Metadata.Content ?? ""; + _pos++; + + var description = new List(); + if (!string.IsNullOrWhiteSpace(descText)) + { + // If the inline description contains an unclosed <<, the xref spans to the next + // line(s) — join with continuation Text tokens until the xref is closed. + var openCount = descText.Split("<<").Length - 1; + var closeCount = descText.Split(">>").Length - 1; + while (openCount > closeCount && _pos < _tokens.Count && Current.Type == TokenType.Text) + { + descText += "\n" + Current.Raw; + closeCount = descText.Split(">>").Length - 1; + _pos++; + } + description.Add(new ParagraphNode { Inlines = ParseInlines(SubstituteAttributes(descText)) }); + } + + while (_pos < _tokens.Count) + { + var cur = Current; + if (cur.Type == TokenType.ListContinuation) + { + _pos++; + if (_pos < _tokens.Count) + { + var continued = ParseBlock(null, null, null); + if (continued != null) + description.Add(continued); + } + continue; + } + + if (cur.Type == TokenType.Text) + { + var lines = new List { cur.Raw }; + _pos++; + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + // Stop before a callout marker so ParseCalloutList can handle the run + if (CalloutItemRegex().IsMatch(Current.Raw)) + break; + lines.Add(Current.Raw); + _pos++; + } + description.Add(new ParagraphNode { Inlines = ParseInlines(SubstituteAttributes(string.Join('\n', lines))) }); + continue; + } + + if (cur.Type is TokenType.Blank) + { + _pos++; + break; + } + + break; + } + + list.Items.Add(new DescriptionListItemNode { Term = term, Description = description }); + } + return list; + } + + private IAsciidocNode ParseTable(TokenMetadata? blockAttr) + { + _pos++; + + var format = blockAttr?.NamedAttributes?.GetValueOrDefault("format")?.ToLowerInvariant(); + if (format is "dsv" or "csv" or "tsv") + return ParseSeparatedTable(blockAttr, format); + + var columns = ParseColumnSpecs(blockAttr); + var allRows = new List(); + var currentCells = new List(); + var firstBlankSeen = false; + + while (_pos < _tokens.Count) + { + var cur = Current; + + if (cur.Type == TokenType.TableDelimiter) + { + _pos++; + break; + } + + if (cur.Type == TokenType.Blank) + { + if (currentCells.Count > 0) + { + allRows.Add(BuildTableRow(currentCells)); + currentCells = []; + } + firstBlankSeen = true; + _pos++; + continue; + } + + if (cur.Type == TokenType.TableRow) + { + var cellContent = cur.Metadata?.Content ?? ""; + var cells = SplitTableCells(cellContent); + currentCells.AddRange(cells); + _pos++; + continue; + } + + if (cur.Type is TokenType.Text or TokenType.IncludeDirective) + { + // Inside tables the lexer produces Text tokens for include:: directives + var includeMatch = TableIncludeRegex().Match(cur.Raw); + if (includeMatch.Success) + { + // Flush any accumulated row, then inline the included table rows + if (currentCells.Count > 0) + { + allRows.Add(BuildTableRow(currentCells)); + currentCells = []; + } + var rawPath = includeMatch.Groups[1].Value; + var resolvedPath = rawPath.StartsWith("{docdir}", StringComparison.Ordinal) + ? rawPath.Replace("{docdir}", _basePath) + : Path.GetFullPath(Path.Combine(_basePath, rawPath)); + if (File.Exists(resolvedPath)) + { + foreach (var fileLine in File.ReadAllLines(resolvedPath)) + { + var trimmedLine = fileLine.Trim(); + if (trimmedLine.StartsWith('|')) + { + var cells = SplitTableCells(trimmedLine[1..]); + if (cells.Count > 0) + allRows.Add(BuildTableRow(cells)); + } + } + } + } + else if (currentCells.Count > 0) + { + currentCells[^1] += " " + cur.Raw.Trim(); + } + _pos++; + continue; + } + + _pos++; + } + + if (currentCells.Count > 0) + allRows.Add(BuildTableRow(currentCells)); + + var hasHeader = HasHeaderOption(blockAttr); + if (!hasHeader && allRows.Count > 1 && !firstBlankSeen) + hasHeader = false; + else if (!hasHeader && allRows.Count > 1) + hasHeader = true; + + List headerRows = hasHeader && allRows.Count > 0 ? [allRows[0]] : []; + var bodyRows = hasHeader && allRows.Count > 0 ? allRows[1..] : allRows; + + return new TableNode { Columns = columns, HeaderRows = headerRows, BodyRows = bodyRows }; + } + + private IAsciidocNode ParseSeparatedTable(TokenMetadata? blockAttr, string format) + { + var separator = format switch + { + "csv" => ',', + "tsv" => '\t', + _ => blockAttr?.NamedAttributes?.GetValueOrDefault("separator") is { Length: > 0 } sep ? sep[0] : ':' + }; + + var hasHeader = HasHeaderOption(blockAttr); + var rows = new List(); + + while (_pos < _tokens.Count) + { + var cur = Current; + + if (cur.Type == TokenType.TableDelimiter) + { + _pos++; + break; + } + + if (cur.Type == TokenType.Blank) + { + _pos++; + continue; + } + + var line = cur.Raw; + if (!string.IsNullOrWhiteSpace(line)) + { + var cells = line.Split(separator).Select(c => c.Trim()).ToList(); + rows.Add(BuildTableRow(cells)); + } + + _pos++; + } + + var columns = ParseColumnSpecs(blockAttr); + List headerRows = hasHeader && rows.Count > 0 ? [rows[0]] : []; + var bodyRows = hasHeader && rows.Count > 0 ? rows[1..] : rows; + + return new TableNode { Columns = columns, HeaderRows = headerRows, BodyRows = bodyRows }; + } + + private static bool HasHeaderOption(TokenMetadata? blockAttr) + { + if (blockAttr?.NamedAttributes?.TryGetValue("options", out var opts) == true + && opts.Contains("header", StringComparison.OrdinalIgnoreCase)) + return true; + + var content = blockAttr?.Content ?? blockAttr?.BlockStyle ?? ""; + return content.Contains("%header", StringComparison.OrdinalIgnoreCase); + } + + private static List ParseColumnSpecs(TokenMetadata? blockAttr) + { + var colsValue = blockAttr?.NamedAttributes?.GetValueOrDefault("cols"); + if (string.IsNullOrWhiteSpace(colsValue)) + return []; + + var specs = new List(); + var parts = colsValue.Split(','); + + foreach (var part in parts) + { + var trimmed = part.Trim(); + if (trimmed.EndsWith('*')) + { + var countStr = trimmed[..^1]; + var count = int.TryParse(countStr, out var c) ? c : 1; + for (var i = 0; i < count; i++) + specs.Add(new ColumnSpec()); + } + else + { + var spec = ParseSingleColumnSpec(trimmed); + specs.Add(spec); + } + } + + return specs; + } + + private static ColumnSpec ParseSingleColumnSpec(string spec) + { + var hAlign = ColumnHAlign.Left; + var vAlign = ColumnVAlign.Top; + int? width = null; + string? style = null; + + if (spec.StartsWith('<')) + hAlign = ColumnHAlign.Left; + else if (spec.StartsWith('^')) + hAlign = ColumnHAlign.Center; + else if (spec.StartsWith('>')) + hAlign = ColumnHAlign.Right; + + var digits = new string(spec.Where(char.IsDigit).ToArray()); + if (int.TryParse(digits, out var w)) + width = w; + + if (spec.EndsWith('a')) + style = "asciidoc"; + else if (spec.EndsWith('h')) + style = "header"; + + return new ColumnSpec { HAlign = hAlign, VAlign = vAlign, Width = width, Style = style }; + } + + private static List SplitTableCells(string content) + { + var cells = new List(); + var parts = content.Split('|'); + foreach (var p in parts) + { + var trimmed = p.Trim(); + if (!string.IsNullOrEmpty(trimmed) || cells.Count > 0) + cells.Add(trimmed); + } + return cells; + } + + private TableRowNode BuildTableRow(List cellTexts) + { + var cells = cellTexts + .Select(text => new TableCellNode + { + Content = [new ParagraphNode { Inlines = ParseInlines(SubstituteAttributes(text)) }] + }) + .ToList(); + return new TableRowNode { Cells = cells }; + } + + // Collects a run of callout description lines into an ordered list. + // Called when a Text token at block level matches the callout pattern. + private IAsciidocNode ParseCalloutList() + { + var items = new List(); + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + var calloutMatch = CalloutItemRegex().Match(Current.Raw); + if (!calloutMatch.Success) + break; + var text = calloutMatch.Groups[2].Value; + _pos++; + // Collect any continuation lines (Text tokens without prefix) + while (_pos < _tokens.Count && Current.Type == TokenType.Text && !CalloutItemRegex().IsMatch(Current.Raw)) + { + text += " " + Current.Raw.Trim(); + _pos++; + } + items.Add(new ListItemNode { Inlines = ParseInlines(SubstituteAttributes(text)), Children = [] }); + } + return new OrderedListNode { Items = items }; + } + + private IAsciidocNode ParseAdmonitionParagraph() + { + var token = Current; + var type = ParseAdmonitionType(token.Metadata!.BlockStyle!); + var contentParts = new List { token.Metadata.Content! }; + _pos++; + + // Collect continuation lines (non-blank Text tokens that follow the admonition header) + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + contentParts.Add(Current.Raw); + _pos++; + } + + var content = string.Join('\n', contentParts); + var paragraph = new ParagraphNode { Inlines = ParseInlines(SubstituteAttributes(content)) }; + return new AdmonitionNode { Type = type, Children = [paragraph] }; + } + + private IAsciidocNode ParseImageBlock(string? title) + { + var token = Current; + var path = SubstituteAttributes(token.Metadata!.Path!); + var alt = token.Metadata.Title is not null ? SubstituteAttributes(token.Metadata.Title) : null; + var resolvedTitle = title is not null ? SubstituteAttributes(title) : null; + _pos++; + + return new ImageNode { Path = path, Alt = alt, Title = resolvedTitle }; + } + + private IAsciidocNode ParsePageBreak() + { + _pos++; + return new PageBreakNode(); + } + + private IAsciidocNode ParseThematicBreak() + { + _pos++; + return new ThematicBreakNode(); + } + + private IAsciidocNode ParseParagraph() + { + var lines = new List(); + while (_pos < _tokens.Count && Current.Type == TokenType.Text) + { + // Stop before a callout marker so ParseCalloutList can handle the run + if (CalloutItemRegex().IsMatch(Current.Raw)) + break; + lines.Add(Current.Raw); + _pos++; + } + + var text = string.Join('\n', lines); + var inlines = ParseInlines(SubstituteAttributes(text)); + return new ParagraphNode { Inlines = inlines }; + } + + private IAsciidocNode? SkipConditional() + { + _pos++; + return null; + } + + private IAsciidocNode? SkipToken() + { + _pos++; + return null; + } + + private IAsciidocNode? ParseIncludeBlock() + { + var token = Current; + _pos++; + var included = ProcessInclude(token); + if (included is null or { Count: 0 }) + return null; + if (included.Count == 1) + return included[0]; + return new OpenBlockNode { Children = included }; + } + + private static bool IsAdmonitionStyle(string? style) => + style is "note" or "tip" or "warning" or "important" or "caution" or + "NOTE" or "TIP" or "WARNING" or "IMPORTANT" or "CAUTION"; + + private static AdmonitionType ParseAdmonitionType(string style) => + style.ToUpperInvariant() switch + { + "NOTE" => AdmonitionType.Note, + "TIP" => AdmonitionType.Tip, + "WARNING" => AdmonitionType.Warning, + "IMPORTANT" => AdmonitionType.Important, + "CAUTION" => AdmonitionType.Caution, + _ => AdmonitionType.Note + }; + + private static string? ExtractInlineAnchor(string title) + { + if (title.StartsWith("[[", StringComparison.Ordinal) && title.Contains("]]", StringComparison.Ordinal)) + { + var end = title.IndexOf("]]", StringComparison.Ordinal); + return title[2..end]; + } + return null; + } + + private List? ProcessInclude(Token token) + { + if (_includeDepth >= options.MaxIncludeDepth) + throw new InvalidOperationException($"Include depth exceeded maximum of {options.MaxIncludeDepth}"); + + var rawPath = SubstituteAttributes(token.Metadata!.Path!); + var resolvedPath = Path.IsPathRooted(rawPath) + ? Path.GetFullPath(rawPath) + : Path.GetFullPath(Path.Combine(_basePath, rawPath)); + var content = ReadFile(resolvedPath); + if (content is null) + { + options.OnDiagnostic?.Invoke($"Include not resolved: {rawPath} (resolved to {resolvedPath})"); + return null; + } + + var attrs = token.Metadata.NamedAttributes ?? []; + + content = ApplyIncludeFilters(content, attrs); + + if (attrs.TryGetValue("leveloffset", out var offsetStr) && int.TryParse(offsetStr, out var offset)) + content = ApplyLevelOffset(content, offset); + + _includeDepth++; + var savedTokens = _tokens; + var savedPos = _pos; + var savedBase = _basePath; + _ = _attributes.TryGetValue("docdir", out var savedDocDir); + + SetBasePath(Path.GetDirectoryName(resolvedPath) ?? _basePath); + var includeTokens = AsciidocLexer.Tokenize(content); + var processed = ConditionalProcessor.Process(includeTokens, _attributes); + _tokens = processed; + _pos = 0; + + var result = new List(); + string? pendingId = null; + string? pendingTitle = null; + TokenMetadata? pendingBlockAttr = null; + + while (_pos < _tokens.Count) + { + var cur = Current; + switch (cur.Type) + { + case TokenType.AttributeEntry: + SetAttribute(cur.Metadata!.AttributeName!, cur.Metadata.AttributeValue); + _pos++; + break; + case TokenType.AttributeUnset: + _ = _attributes.Remove(cur.Metadata!.AttributeName!); + _pos++; + break; + case TokenType.BlockAnchor: + pendingId = cur.Metadata!.Id; + _pos++; + break; + case TokenType.BlockTitle: + pendingTitle = cur.Metadata!.Title; + _pos++; + break; + case TokenType.BlockAttribute: + pendingBlockAttr = cur.Metadata; + _pos++; + break; + case TokenType.Blank: + case TokenType.Comment: + _pos++; + break; + case TokenType.SectionTitle: + var section = ParseSection(pendingId, null); + result.Add(section with { IsIncludeRoot = true }); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + break; + case TokenType.IncludeDirective: + var included = ProcessInclude(cur); + if (included != null) + result.AddRange(included); + _pos++; + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + break; + default: + var block = ParseBlock(pendingId, pendingTitle, pendingBlockAttr); + if (block != null) + result.Add(block); + pendingId = null; + pendingTitle = null; + pendingBlockAttr = null; + break; + } + } + + _tokens = savedTokens; + _pos = savedPos; + _basePath = savedBase; + if (savedDocDir is not null) + _attributes["docdir"] = savedDocDir; + else + _ = _attributes.Remove("docdir"); + _includeDepth--; + + return result; + } + + private static string ApplyIncludeFilters(string content, Dictionary attrs) + { + if (attrs.TryGetValue("lines", out var linesSpec)) + content = FilterByLines(content, linesSpec); + + if (attrs.TryGetValue("tag", out var tag)) + content = FilterByTags(content, [tag]); + else if (attrs.TryGetValue("tags", out var tags)) + content = FilterByTags(content, tags.Split(';')); + + return content; + } + + private static string FilterByLines(string content, string linesSpec) + { + var allLines = content.Split('\n'); + var result = new List(); + + foreach (var range in linesSpec.Split(';')) + { + var trimmed = range.Trim(); + if (trimmed.Contains("..", StringComparison.Ordinal)) + { + var parts = trimmed.Split(".."); + var start = int.TryParse(parts[0], out var s) ? s : 1; + var endStr = parts.Length > 1 ? parts[1] : ""; + var end = endStr == "-1" || string.IsNullOrEmpty(endStr) ? allLines.Length : int.TryParse(endStr, out var e) ? e : allLines.Length; + + for (var i = Math.Max(1, start); i <= Math.Min(end, allLines.Length); i++) + result.Add(allLines[i - 1]); + } + else if (int.TryParse(trimmed, out var lineNum) && lineNum >= 1 && lineNum <= allLines.Length) + { + result.Add(allLines[lineNum - 1]); + } + } + + return string.Join('\n', result); + } + + private static string FilterByTags(string content, string[] tagNames) + { + var lines = content.Split('\n'); + var result = new List(); + var activeTags = new HashSet(StringComparer.OrdinalIgnoreCase); + var targetTags = new HashSet(tagNames, StringComparer.OrdinalIgnoreCase); + + foreach (var line in lines) + { + var trimmed = line.TrimStart(); + + if (TagStartRegex().Match(trimmed) is { Success: true } startMatch) + { + var tagName = startMatch.Groups[1].Value; + if (targetTags.Contains(tagName)) + _ = activeTags.Add(tagName); + continue; + } + + if (TagEndRegex().Match(trimmed) is { Success: true } endMatch) + { + _ = activeTags.Remove(endMatch.Groups[1].Value); + continue; + } + + if (activeTags.Count > 0) + result.Add(line); + } + + return string.Join('\n', result); + } + + private static string ApplyLevelOffset(string content, int offset) + { + if (offset == 0) + return content; + + var lines = content.Split('\n'); + for (var i = 0; i < lines.Length; i++) + { + var line = lines[i]; + if (line.StartsWith('=')) + { + var match = LevelOffsetRegex().Match(line); + if (match.Success) + { + var currentLevel = match.Groups[1].Value.Length; + var newLevel = Math.Max(1, Math.Min(6, currentLevel + offset)); + lines[i] = new string('=', newLevel) + " " + match.Groups[2].Value; + } + } + } + return string.Join('\n', lines); + } + + [GeneratedRegex(@"^(={1,6})\s+(.+)$")] + private static partial Regex LevelOffsetRegex(); + + // Allow hyphens in tag names (e.g. tag::my-tag[]) and any comment prefix (// # --) + [GeneratedRegex(@"tag::([\w-]+)\[\]")] + private static partial Regex TagStartRegex(); + + [GeneratedRegex(@"end::([\w-]+)\[\]")] + private static partial Regex TagEndRegex(); + + private string? ReadFile(string path) + { + if (options.FileReader is not null) + { + // Normalize to Unix-style paths so test FileReader lambdas receive consistent + // forward-slash paths regardless of OS. On Windows, Path.GetFullPath turns + // "/base/foo.adoc" into "C:\base\foo.adoc"; strip the drive letter and flip slashes. + var normalized = path.Replace('\\', '/'); + if (normalized.Length >= 2 && normalized[1] == ':') + normalized = normalized[2..]; + return options.FileReader(normalized); + } + + return File.Exists(path) ? File.ReadAllText(path) : null; + } + + [GeneratedRegex( + @"link:([^\[]+)\[([^\]]*)\]|" + // groups 1,2: link + @"<<([^,>]+)(?:,([\s\S]+?))?>>>|" + // groups 3,4: triple-xref (allow newlines in text) + @"<<([^,>]+)(?:,([\s\S]+?))?>>" + "|" + // groups 5,6: xref (allow newlines in text) + @"image:([^\[]+)\[([^\]]*)\]|" + // groups 7,8: image + @"footnote:\[([^\]]*)\]|" + // group 9: footnote + @"pass:\[([^\]]*)\]|" + // group 10: pass:[] passthrough + @"\[([a-zA-Z][a-zA-Z0-9_-]*)\]#([^#]+)#|" + // groups 11,12: [role]#text# + @"\*\*([^\*<]+)\*\*|" + // group 13: unconstrained bold (no < prevents spanning xref markers) + @"\*([^\*<]+)\*|" + // group 14: constrained bold (no < prevents spanning xref markers) + @"_([^_<]+)_|" + // group 15: italic (no < prevents spanning xref markers) + @"(? "text" + @"\s*\+\s*$" // line-break (no capture) + )] + private static partial Regex InlineCombinedRegex(); + + [GeneratedRegex(@"\{([a-zA-Z0-9_-]+)\}")] + private static partial Regex InlineAttrRefRegex(); + + // Normalize `<<<>, text>>` (double `<<` source bug) → `<>` + [GeneratedRegex(@"<<<<([^,>]+)>>(,[^>]*)?>")] + private static partial Regex DoubleXrefRegex(); + + public List ParseInlines(string text) + { + if (string.IsNullOrEmpty(text)) + return []; + + // Normalize `<<<>, text>>` (double-nested xref source bug) to `<>` + if (text.Contains("<<<<", StringComparison.Ordinal)) + text = DoubleXrefRegex().Replace(text, "<<$1$2>>"); + + + var result = new List(); + var lastIndex = 0; + + foreach (Match match in InlineCombinedRegex().Matches(text)) + { + if (match.Index > lastIndex) + result.Add(new TextInline(text[lastIndex..match.Index])); + + if (match.Groups[1].Success) + result.Add(new InlineLinkNode(match.Groups[1].Value, NullIfEmpty(match.Groups[2].Value))); + else if (match.Groups[5].Success) + result.Add(new InlineCrossRefNode(match.Groups[5].Value, NullIfEmpty(NormalizeWhitespace(match.Groups[6].Value)))); + else if (match.Groups[3].Success) + result.Add(new InlineCrossRefNode(match.Groups[3].Value, NullIfEmpty(NormalizeWhitespace(match.Groups[4].Value)))); + else if (match.Groups[7].Success) + result.Add(new InlineImageNode(match.Groups[7].Value, NullIfEmpty(match.Groups[8].Value))); + else if (match.Groups[9].Success) + result.Add(new FootnoteInline(ParseInlines(match.Groups[9].Value))); + else if (match.Groups[10].Success) + result.Add(new PassthroughInline(match.Groups[10].Value)); + else if (match.Groups[11].Success) + result.Add(new RoleInline(match.Groups[11].Value, ParseInlines(match.Groups[12].Value))); + else if (match.Groups[13].Success) + result.Add(new BoldInline(ParseInlines(match.Groups[13].Value))); + else if (match.Groups[14].Success) + result.Add(new BoldInline(ParseInlines(match.Groups[14].Value))); + else if (match.Groups[15].Success) + result.Add(new ItalicInline(ParseInlines(match.Groups[15].Value))); + else if (match.Groups[16].Success) + result.Add(new MonoInline(match.Groups[16].Value)); + else if (match.Groups[17].Success) + result.Add(new SuperscriptInline(ParseInlines(match.Groups[17].Value))); + else if (match.Groups[18].Success) + result.Add(new SubscriptInline(ParseInlines(match.Groups[18].Value))); + else if (match.Groups[19].Success) + result.Add(new AttributeRefInline(match.Groups[19].Value)); + else if (match.Groups[20].Success) + result.Add(new InlineLinkNode(match.Groups[20].Value, NullIfEmpty(match.Groups[21].Value))); + else if (match.Groups[22].Success) + result.Add(new PassthroughInline(match.Groups[22].Value, Backticks: true)); + else if (match.Groups[23].Success) + result.Add(new TextInline($"\"{match.Groups[23].Value}\"")); + else if (match.Value.TrimEnd().EndsWith('+')) + result.Add(new LineBreakInline()); + + lastIndex = match.Index + match.Length; + } + + if (lastIndex < text.Length) + result.Add(new TextInline(text[lastIndex..])); + + return result; + } + + private string SubstituteAttributes(string text) + { + if (string.IsNullOrEmpty(text)) + return text; + + return InlineAttrRefRegex().Replace(text, match => + { + var name = match.Groups[1].Value; + return _attributes.TryGetValue(name, out var value) ? value : match.Value; + }); + } + + private static string? NullIfEmpty(string value) => + string.IsNullOrEmpty(value) ? null : value; + + // Collapse newlines and surrounding whitespace in captured inline text to a single space. + private static string NormalizeWhitespace(string value) => + string.IsNullOrEmpty(value) ? value : WhitespaceCollapseRegex().Replace(value.Trim(), " "); + + [GeneratedRegex(@"\s*\n\s*")] + private static partial Regex WhitespaceCollapseRegex(); +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AdmonitionNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AdmonitionNode.cs new file mode 100644 index 0000000000..88c7400e3a --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AdmonitionNode.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.LegacyDocs.Migration.Asciidoc.Ast; + +public record AdmonitionNode : IBlockNode +{ + public required AdmonitionType Type { get; init; } + public List Children { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AsciidocDocument.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AsciidocDocument.cs new file mode 100644 index 0000000000..baa9a36eaf --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/AsciidocDocument.cs @@ -0,0 +1,13 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record AsciidocDocument : IAsciidocNode +{ + public string? Title { get; init; } + public string? Id { get; init; } + public Dictionary Attributes { get; init; } = []; + public List Children { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/CodeBlockNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/CodeBlockNode.cs new file mode 100644 index 0000000000..8603e9540a --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/CodeBlockNode.cs @@ -0,0 +1,12 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record CodeBlockNode : IBlockNode +{ + public string? Language { get; init; } + public required string Source { get; init; } + public List Callouts { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ColumnSpec.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ColumnSpec.cs new file mode 100644 index 0000000000..b451680060 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ColumnSpec.cs @@ -0,0 +1,13 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record ColumnSpec +{ + public ColumnHAlign HAlign { get; init; } = ColumnHAlign.Left; + public ColumnVAlign VAlign { get; init; } = ColumnVAlign.Top; + public int? Width { get; init; } + public string? Style { get; init; } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListItemNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListItemNode.cs new file mode 100644 index 0000000000..4f0d64604b --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListItemNode.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.LegacyDocs.Migration.Asciidoc.Ast; + +public record DescriptionListItemNode : IBlockNode +{ + public List Term { get; init; } = []; + public List Description { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListNode.cs new file mode 100644 index 0000000000..0d22320de1 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/DescriptionListNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record DescriptionListNode : IBlockNode +{ + public List Items { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/Enums.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/Enums.cs new file mode 100644 index 0000000000..8b046a85c9 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/Enums.cs @@ -0,0 +1,28 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public enum AdmonitionType +{ + Note, + Tip, + Warning, + Important, + Caution +} + +public enum ColumnHAlign +{ + Left, + Center, + Right +} + +public enum ColumnVAlign +{ + Top, + Middle, + Bottom +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ExampleNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ExampleNode.cs new file mode 100644 index 0000000000..f70964fb21 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ExampleNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record ExampleNode : IBlockNode +{ + public List Children { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/IAsciidocNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/IAsciidocNode.cs new file mode 100644 index 0000000000..586e98bca5 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/IAsciidocNode.cs @@ -0,0 +1,13 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public interface IAsciidocNode; + +public interface IInlineNode; + +public interface IBlockNode : IAsciidocNode; + +public record AnchoredBlock(string Id, IAsciidocNode Inner) : IBlockNode; diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ImageNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ImageNode.cs new file mode 100644 index 0000000000..20a68c4fb4 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ImageNode.cs @@ -0,0 +1,14 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record ImageNode : IBlockNode +{ + public required string Path { get; init; } + public string? Alt { get; init; } + public string? Title { get; init; } + public string? Width { get; init; } + public string? Height { get; init; } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/InlineNodes.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/InlineNodes.cs new file mode 100644 index 0000000000..93863aa4e4 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/InlineNodes.cs @@ -0,0 +1,33 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record TextInline(string Text) : IInlineNode; + +public record BoldInline(List Children) : IInlineNode; + +public record ItalicInline(List Children) : IInlineNode; + +public record MonoInline(string Text) : IInlineNode; + +public record AttributeRefInline(string Name) : IInlineNode; + +public record InlineLinkNode(string Url, string? Text = null) : IInlineNode; + +public record InlineCrossRefNode(string Target, string? Text = null) : IInlineNode; + +public record InlineImageNode(string Path, string? Alt = null) : IInlineNode; + +public record FootnoteInline(List Content) : IInlineNode; + +public record SuperscriptInline(List Children) : IInlineNode; + +public record SubscriptInline(List Children) : IInlineNode; + +public record LineBreakInline : IInlineNode; + +public record PassthroughInline(string Content, bool Backticks = false) : IInlineNode; + +public record RoleInline(string Role, List Children) : IInlineNode; diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ListItemNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ListItemNode.cs new file mode 100644 index 0000000000..fbd0a6ca98 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ListItemNode.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.LegacyDocs.Migration.Asciidoc.Ast; + +public record ListItemNode : IBlockNode +{ + public List Inlines { get; init; } = []; + public List Children { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/LiteralBlockNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/LiteralBlockNode.cs new file mode 100644 index 0000000000..62c737ba4e --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/LiteralBlockNode.cs @@ -0,0 +1,7 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record LiteralBlockNode(string Content) : IBlockNode; diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OpenBlockNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OpenBlockNode.cs new file mode 100644 index 0000000000..cb580f19cc --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OpenBlockNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record OpenBlockNode : IBlockNode +{ + public List Children { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OrderedListNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OrderedListNode.cs new file mode 100644 index 0000000000..dd8b03171a --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/OrderedListNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record OrderedListNode : IBlockNode +{ + public List Items { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PageBreakNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PageBreakNode.cs new file mode 100644 index 0000000000..f9dda7e147 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PageBreakNode.cs @@ -0,0 +1,7 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record PageBreakNode : IBlockNode; diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ParagraphNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ParagraphNode.cs new file mode 100644 index 0000000000..22085066d0 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ParagraphNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record ParagraphNode : IBlockNode +{ + public List Inlines { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PassthroughNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PassthroughNode.cs new file mode 100644 index 0000000000..6c5c820201 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/PassthroughNode.cs @@ -0,0 +1,7 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record PassthroughNode(string Content) : IBlockNode; diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs new file mode 100644 index 0000000000..75dd1484e3 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs @@ -0,0 +1,15 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record SectionNode : IBlockNode +{ + public required int Level { get; init; } + public required string Title { get; init; } + public string? Id { get; init; } + public List Children { get; init; } = []; + /// True when this section was produced as the top-level result of a ProcessInclude call. + public bool IsIncludeRoot { get; init; } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SidebarNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SidebarNode.cs new file mode 100644 index 0000000000..e2c561b23c --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SidebarNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record SidebarNode : IBlockNode +{ + public List Children { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableCellNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableCellNode.cs new file mode 100644 index 0000000000..a572fa004b --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableCellNode.cs @@ -0,0 +1,12 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record TableCellNode : IBlockNode +{ + public List Content { get; init; } = []; + public int ColSpan { get; init; } = 1; + public int RowSpan { get; init; } = 1; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableNode.cs new file mode 100644 index 0000000000..fc8e75fc9e --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableNode.cs @@ -0,0 +1,12 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record TableNode : IBlockNode +{ + public List Columns { get; init; } = []; + public List HeaderRows { get; init; } = []; + public List BodyRows { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableRowNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableRowNode.cs new file mode 100644 index 0000000000..74323a8910 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/TableRowNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record TableRowNode : IBlockNode +{ + public List Cells { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ThematicBreakNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ThematicBreakNode.cs new file mode 100644 index 0000000000..6e1e8af81c --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/ThematicBreakNode.cs @@ -0,0 +1,7 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record ThematicBreakNode : IBlockNode; diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/UnorderedListNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/UnorderedListNode.cs new file mode 100644 index 0000000000..45035b3996 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/UnorderedListNode.cs @@ -0,0 +1,10 @@ +// 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.LegacyDocs.Migration.Asciidoc.Ast; + +public record UnorderedListNode : IBlockNode +{ + public List Items { get; init; } = []; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/ConditionalProcessor.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/ConditionalProcessor.cs new file mode 100644 index 0000000000..874c5dad72 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/ConditionalProcessor.cs @@ -0,0 +1,153 @@ +// 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 System.Text.RegularExpressions; + +namespace Elastic.LegacyDocs.Migration.Asciidoc; + +public static partial class ConditionalProcessor +{ + public static IReadOnlyList Process(IReadOnlyList tokens, IReadOnlyDictionary attributes) + { + var result = new List(); + var conditionStack = new Stack(); + + foreach (var token in tokens) + { + if (token.Type == TokenType.ConditionalStart) + { + var directive = token.Metadata!.BlockStyle!; + var condition = token.Metadata.Condition!; + var inlineContent = token.Metadata.Content; + + // ifeval::[expr] puts its expression inside the brackets (Content/group 3), + // not before them (Condition/group 2 = empty). It is always block-level. + var isIfeval = directive.Equals("ifeval", StringComparison.OrdinalIgnoreCase); + var conditionExpr = isIfeval ? (inlineContent ?? "") : condition; + var isTrue = EvaluateCondition(directive, conditionExpr, attributes); + + if (!isIfeval && !string.IsNullOrEmpty(inlineContent)) + { + if (IsIncluding(conditionStack) && isTrue) + result.Add(new Token(TokenType.Text, inlineContent, token.LineNumber)); + } + else + { + conditionStack.Push(isTrue); + } + continue; + } + + if (token.Type == TokenType.ConditionalEnd) + { + if (conditionStack.Count > 0) + _ = conditionStack.Pop(); + continue; + } + + if (IsIncluding(conditionStack)) + result.Add(token); + } + + return result; + } + + private static bool IsIncluding(Stack stack) + { + foreach (var condition in stack) + { + if (!condition) + return false; + } + return true; + } + + private static bool EvaluateCondition(string directive, string condition, IReadOnlyDictionary attributes) => + directive.ToLowerInvariant() switch + { + "ifdef" => EvaluateIfdef(condition, attributes), + "ifndef" => EvaluateIfndef(condition, attributes), + "ifeval" => EvaluateIfeval(condition, attributes), + _ => true + }; + + private static bool EvaluateIfdef(string condition, IReadOnlyDictionary attributes) + { + if (condition.Contains('+')) + return condition.Split('+').All(attr => attributes.ContainsKey(attr.Trim())); + + if (condition.Contains(',')) + return condition.Split(',').Any(attr => attributes.ContainsKey(attr.Trim())); + + return attributes.ContainsKey(condition.Trim()); + } + + private static bool EvaluateIfndef(string condition, IReadOnlyDictionary attributes) + { + if (condition.Contains('+')) + return condition.Split('+').All(attr => !attributes.ContainsKey(attr.Trim())); + + if (condition.Contains(',')) + return condition.Split(',').Any(attr => !attributes.ContainsKey(attr.Trim())); + + return !attributes.ContainsKey(condition.Trim()); + } + + private static bool EvaluateIfeval(string condition, IReadOnlyDictionary attributes) + { + var resolved = SubstituteAttributes(condition, attributes); + var match = IfevalRegex().Match(resolved); + if (!match.Success) + return false; + + var left = UnquoteValue(match.Groups[1].Value.Trim()); + var op = match.Groups[2].Value.Trim(); + var right = UnquoteValue(match.Groups[3].Value.Trim()); + + if (double.TryParse(left, out var leftNum) && double.TryParse(right, out var rightNum)) + { + return op switch + { + "==" => Math.Abs(leftNum - rightNum) < 0.0001, + "!=" => Math.Abs(leftNum - rightNum) >= 0.0001, + "<" => leftNum < rightNum, + ">" => leftNum > rightNum, + "<=" => leftNum <= rightNum, + ">=" => leftNum >= rightNum, + _ => false + }; + } + + return op switch + { + "==" => string.Equals(left, right, StringComparison.Ordinal), + "!=" => !string.Equals(left, right, StringComparison.Ordinal), + "<" => string.Compare(left, right, StringComparison.Ordinal) < 0, + ">" => string.Compare(left, right, StringComparison.Ordinal) > 0, + "<=" => string.Compare(left, right, StringComparison.Ordinal) <= 0, + ">=" => string.Compare(left, right, StringComparison.Ordinal) >= 0, + _ => false + }; + } + + private static string SubstituteAttributes(string text, IReadOnlyDictionary attributes) => + AttrRefRegex().Replace(text, match => + { + var name = match.Groups[1].Value; + return attributes.TryGetValue(name, out var value) ? value : match.Value; + }); + + private static string UnquoteValue(string value) + { + if (value.Length >= 2 && value[0] == '"' && value[^1] == '"') + return value[1..^1]; + return value; + } + + [GeneratedRegex(@"\{([a-zA-Z0-9_-]+)\}")] + private static partial Regex AttrRefRegex(); + + [GeneratedRegex(@"(.+?)\s*(==|!=|<=|>=|<|>)\s*(.+)")] + private static partial Regex IfevalRegex(); +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs new file mode 100644 index 0000000000..db2222b717 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs @@ -0,0 +1,624 @@ +// 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 System.Text; +using System.Text.RegularExpressions; +using Elastic.LegacyDocs.Migration.Asciidoc.Ast; + +namespace Elastic.LegacyDocs.Migration.Asciidoc; + +public record MarkdownEmitterOptions +{ + public string ImagePathPrefix { get; init; } = "images/"; + public string? BookPrefix { get; init; } + public string? Version { get; init; } + public Dictionary AnchorToSlugMap { get; init; } = []; + public Dictionary AnchorToTitleMap { get; init; } = []; + public string? PageSlug { get; init; } +} + +public static partial class GuideUrlRewriter +{ + private const string GuidePrefix = "https://www.elastic.co/guide/"; + + [GeneratedRegex(@"^https://www\.elastic\.co/guide/(.+?)(?:\.html)?(?:#(.+))?$")] + private static partial Regex GuideUrlRegex(); + + public static string? TryRewriteToInternal(string url) + { + if (!url.StartsWith(GuidePrefix, StringComparison.OrdinalIgnoreCase)) + return null; + + var match = GuideUrlRegex().Match(url); + if (!match.Success) + return null; + + var path = match.Groups[1].Value.TrimEnd('/'); + var fragment = match.Groups[2].Success ? $"#{match.Groups[2].Value}" : ""; + + if (path.EndsWith("/index", StringComparison.Ordinal)) + return $"/{path}.md{fragment}"; + + return $"/{path}.md{fragment}"; + } +} + +public partial class MarkdownEmitter(MarkdownEmitterOptions options) +{ + private StringBuilder _sb = new(); + private int _footnoteCounter; + private readonly List<(int Index, string Content)> _footnotes = []; + + public void UpdateAnchorMap(Dictionary slugMap, Dictionary titleMap) => + options = options with { AnchorToSlugMap = slugMap, AnchorToTitleMap = titleMap }; + + public void UpdatePageSlug(string slug) => + options = options with { PageSlug = slug }; + + public string Emit(AsciidocDocument document) + { + Reset(); + + if (document.Title is not null) + { + if (document.Id is not null) + { + WriteLine($"$$${document.Id}$$$"); + WriteLine(); + } + WriteLine($"# {SubstituteTitleXrefs(SubstituteTitleAttrs(document.Title))}"); + WriteLine(); + } + + EmitChildren(document.Children); + AppendFootnotes(); + + return Finalize(); + } + + public string Emit(IAsciidocNode node) + { + Reset(); + EmitNode(node); + AppendFootnotes(); + return Finalize(); + } + + public string EmitInlines(IReadOnlyList inlines) + { + Reset(); + foreach (var inline in inlines) + EmitInline(inline); + return _sb.ToString(); + } + + private void Reset() + { + _sb = new StringBuilder(); + _footnoteCounter = 0; + _footnotes.Clear(); + } + + private string Finalize() => _sb.ToString().TrimEnd() + "\n"; + + private void Write(string value) => _ = _sb.Append(value); + + private void Write(char value) => _ = _sb.Append(value); + + private void WriteLine() => _ = _sb.AppendLine(); + + private void WriteLine(string value) => _ = _sb.AppendLine(value); + + private string CaptureOutput(Action action) + { + var saved = _sb; + _sb = new StringBuilder(); + action(); + var result = _sb.ToString(); + _sb = saved; + return result; + } + + private void EmitChildren(IReadOnlyList children) + { + foreach (var child in children) + EmitNode(child); + } + + private void EmitNode(IAsciidocNode node) + { + switch (node) + { + case SectionNode section: + EmitSection(section); + break; + case ParagraphNode paragraph: + EmitParagraph(paragraph); + break; + case CodeBlockNode codeBlock: + EmitCodeBlock(codeBlock); + break; + case LiteralBlockNode literal: + EmitLiteralBlock(literal); + break; + case AdmonitionNode admonition: + EmitDirective(MapAdmonitionType(admonition.Type), null, admonition.Children); + break; + case UnorderedListNode ul: + EmitUnorderedList(ul, indent: 0); + WriteLine(); + break; + case OrderedListNode ol: + EmitOrderedList(ol, indent: 0); + WriteLine(); + break; + case DescriptionListNode dl: + EmitDescriptionList(dl); + break; + case TableNode table: + EmitTable(table); + break; + case ImageNode image: + EmitBlockImage(image); + break; + case SidebarNode sidebar: + EmitDirective("admonition", "Sidebar", sidebar.Children); + break; + case ExampleNode example: + EmitDirective("admonition", "Example", example.Children); + break; + case OpenBlockNode open: + EmitChildren(open.Children); + break; + case PassthroughNode passthrough: + // is an Elastic AsciiDoc extension for abbreviated nav titles — discard. + if (!TitleAbbrevRegex().IsMatch(passthrough.Content.Trim())) + { + WriteLine(passthrough.Content); + WriteLine(); + } + break; + case AnchoredBlock anchored: + WriteLine($"$$${anchored.Id}$$$"); + WriteLine(); + EmitNode(anchored.Inner); + break; + case ThematicBreakNode: + case PageBreakNode: + WriteLine("---"); + WriteLine(); + break; + } + } + + private void EmitSection(SectionNode section) + { + var hashes = new string('#', section.Level + 1); + if (section.Level == 0 && section.Id is not null) + { + WriteLine($"$$${section.Id}$$$"); + WriteLine(); + WriteLine($"# {SubstituteTitleXrefs(SubstituteTitleAttrs(section.Title))}"); + } + else + { + var anchor = section.Id is not null ? $" [#{section.Id}]" : ""; + WriteLine($"{hashes} {SubstituteTitleXrefs(SubstituteTitleAttrs(section.Title))}{anchor}"); + } + WriteLine(); + + EmitChildren(section.Children); + } + + [GeneratedRegex(@"^.*\s*$", RegexOptions.Singleline)] + private static partial Regex TitleAbbrevRegex(); + + private void EmitParagraph(ParagraphNode paragraph) + { + // is an Elastic AsciiDoc extension for abbreviated nav titles — discard. + if (paragraph.Inlines is [TextInline { Text: var raw }] && TitleAbbrevRegex().IsMatch(raw)) + return; + + foreach (var inline in paragraph.Inlines) + EmitInline(inline); + WriteLine(); + WriteLine(); + } + + private void EmitCodeBlock(CodeBlockNode codeBlock) + { + var lang = codeBlock.Language ?? ""; + WriteLine($"```{lang}"); + Write(codeBlock.Source.TrimEnd()); + WriteLine(); + WriteLine("```"); + WriteLine(); + + if (codeBlock.Callouts.Count <= 0) + return; + + for (var i = 0; i < codeBlock.Callouts.Count; i++) + WriteLine($"{i + 1}. {SubstituteTitleXrefs(SubstituteTitleAttrs(codeBlock.Callouts[i]))}"); + WriteLine(); + } + + private void EmitLiteralBlock(LiteralBlockNode literal) + { + foreach (var line in literal.Content.Split('\n')) + WriteLine($" {line}"); + WriteLine(); + } + + private static string MapAdmonitionType(AdmonitionType type) => + type switch + { + AdmonitionType.Caution => "warning", + _ => type.ToString().ToLowerInvariant() + }; + + private void EmitDirective(string name, string? argument, IReadOnlyList children) + { + var header = argument is not null ? $":::{{{name}}} {argument}" : $":::{{{name}}}"; + WriteLine(header); + EmitChildren(children); + WriteLine(":::"); + WriteLine(); + } + + private void EmitUnorderedList(UnorderedListNode list, int indent) + { + foreach (var item in list.Items) + EmitListItem(item, "- ", indent); + } + + private void EmitOrderedList(OrderedListNode list, int indent) + { + foreach (var item in list.Items) + EmitListItem(item, "1. ", indent); + } + + private void EmitListItem(ListItemNode item, string marker, int indent) + { + var prefix = new string(' ', indent); + Write($"{prefix}{marker}"); + + foreach (var inline in item.Inlines) + EmitInline(inline); + WriteLine(); + + if (item.Children.Count <= 0) + return; + + var continuationIndent = indent + marker.Length; + foreach (var child in item.Children) + { + switch (child) + { + case UnorderedListNode nestedUl: + EmitUnorderedList(nestedUl, continuationIndent); + break; + case OrderedListNode nestedOl: + EmitOrderedList(nestedOl, continuationIndent); + break; + default: + EmitIndentedBlock(child, continuationIndent); + break; + } + } + } + + private void EmitIndentedBlock(IAsciidocNode node, int indent) + { + var content = CaptureOutput(() => EmitNode(node)); + var continuationPrefix = new string(' ', indent); + foreach (var line in content.TrimEnd().Split('\n')) + WriteLine(string.IsNullOrWhiteSpace(line) ? "" : $"{continuationPrefix}{line}"); + WriteLine(); + } + + private void EmitDescriptionList(DescriptionListNode list) + { + foreach (var item in list.Items) + { + foreach (var inline in item.Term) + EmitInline(inline); + WriteLine(); + + var content = CaptureOutput(() => + { + foreach (var descNode in item.Description) + EmitNode(descNode); + }).TrimEnd(); + + var lines = content.Split('\n'); + for (var i = 0; i < lines.Length; i++) + { + var linePrefix = i == 0 ? ": " : " "; + if (string.IsNullOrWhiteSpace(lines[i])) + WriteLine(); + else + WriteLine($"{linePrefix}{lines[i]}"); + } + WriteLine(); + } + } + + private void EmitTable(TableNode table) + { + if (IsComplexTable(table)) + EmitListTable(table); + else + EmitPipeTable(table); + } + + private static bool IsComplexTable(TableNode table) => + table.HeaderRows + .Concat(table.BodyRows) + .SelectMany(r => r.Cells) + .Any(c => c.ColSpan > 1 || c.RowSpan > 1 || c.Content.Count > 1 + || (c.Content.Count == 1 && c.Content[0] is not ParagraphNode)); + + private void EmitPipeTable(TableNode table) + { + var colCount = ResolveColumnCount(table); + + if (table.HeaderRows.Count > 0) + { + foreach (var row in table.HeaderRows) + EmitPipeRow(row); + } + else + { + Write('|'); + for (var i = 0; i < colCount; i++) + Write(" |"); + WriteLine(); + } + + Write('|'); + for (var i = 0; i < colCount; i++) + Write("---|"); + WriteLine(); + + foreach (var row in table.BodyRows) + EmitPipeRow(row); + + WriteLine(); + } + + private void EmitPipeRow(TableRowNode row) + { + Write('|'); + foreach (var cell in row.Cells) + { + Write(' '); + EmitCellContent(cell); + Write(" |"); + } + WriteLine(); + } + + private void EmitListTable(TableNode table) + { + WriteLine(":::{list-table}"); + if (table.HeaderRows.Count > 0) + WriteLine($":header-rows: {table.HeaderRows.Count}"); + WriteLine(); + + foreach (var row in table.HeaderRows.Concat(table.BodyRows)) + { + for (var i = 0; i < row.Cells.Count; i++) + { + Write(i == 0 ? "* - " : " - "); + EmitCellContent(row.Cells[i]); + WriteLine(); + } + } + + WriteLine(":::"); + WriteLine(); + } + + private void EmitCellContent(TableCellNode cell) + { + if (cell.Content.Count == 0) + return; + + if (cell.Content is [ParagraphNode para]) + { + foreach (var inline in para.Inlines) + EmitInline(inline); + return; + } + + var content = CaptureOutput(() => + { + foreach (var node in cell.Content) + EmitNode(node); + }); + Write(content.TrimEnd().Replace("\n", " ")); + } + + private static int ResolveColumnCount(TableNode table) + { + if (table.Columns.Count > 0) + return table.Columns.Count; + if (table.HeaderRows.Count > 0) + return table.HeaderRows[0].Cells.Count; + if (table.BodyRows.Count > 0) + return table.BodyRows[0].Cells.Count; + return 0; + } + + private void EmitBlockImage(ImageNode image) + { + var alt = image.Alt ?? ""; + var path = image.Path.StartsWith(options.ImagePathPrefix, StringComparison.OrdinalIgnoreCase) + ? image.Path + : $"{options.ImagePathPrefix}{image.Path}"; + WriteLine($"![{alt}]({path})"); + WriteLine(); + } + + private void EmitInline(IInlineNode inline) + { + switch (inline) + { + case TextInline text: + Write(text.Text); + break; + case BoldInline bold: + Write("**"); + EmitInlineChildren(bold.Children); + Write("**"); + break; + case ItalicInline italic: + Write('*'); + EmitInlineChildren(italic.Children); + Write('*'); + break; + case MonoInline mono: + Write($"`{mono.Text}`"); + break; + case AttributeRefInline attrRef: + // Product-name subs are intentional docs-builder {{sub}} placeholders (defined in docset.yml) + if (SharedAttributes.ProductNames.ContainsKey(attrRef.Name)) + Write($"{{{{{attrRef.Name}}}}}"); + else + Write($"{{{attrRef.Name}}}"); + break; + case InlineLinkNode link: + EmitLink(link); + break; + case InlineCrossRefNode xref: + EmitCrossRef(xref); + break; + case InlineImageNode img: + Write($"![{SubstituteTitleAttrs(img.Alt ?? "")}]({img.Path})"); + break; + case FootnoteInline footnote: + EmitFootnote(footnote); + break; + case SuperscriptInline sup: + Write(""); + EmitInlineChildren(sup.Children); + Write(""); + break; + case SubscriptInline sub: + Write(""); + EmitInlineChildren(sub.Children); + Write(""); + break; + case PassthroughInline passthrough: + if (passthrough.Backticks) + Write($"`{passthrough.Content}`"); + else + Write(passthrough.Content); + break; + case RoleInline role: + EmitInlineChildren(role.Children); + break; + case LineBreakInline: + Write('\\'); + WriteLine(); + break; + } + } + + private void EmitInlineChildren(List children) + { + foreach (var child in children) + EmitInline(child); + } + + private void EmitLink(InlineLinkNode link) + { + var rewritten = GuideUrlRewriter.TryRewriteToInternal(link.Url); + var url = rewritten ?? link.Url; + + if (link.Text is not null) + Write($"[{SubstituteTitleAttrs(link.Text)}]({url})"); + else + Write($"<{url}>"); + } + + private void EmitCrossRef(InlineCrossRefNode xref) + { + var displayText = xref.Text is not null + ? SubstituteTitleAttrs(xref.Text) + : options.AnchorToTitleMap.TryGetValue(xref.Target, out var title) ? SubstituteTitleAttrs(title) : xref.Target; + var text = displayText; + + if (!xref.Target.Contains('/') && !xref.Target.Contains("::")) + { + if (options.AnchorToSlugMap.TryGetValue(xref.Target, out var slug)) + { + // Same-page anchor: link to fragment only + if (slug == options.PageSlug) + Write($"[{text}](#{xref.Target})"); + else + Write($"[{text}]({slug}.md#{xref.Target})"); + return; + } + + Write($"[{text}](#{xref.Target})"); + return; + } + + var prefix = options.BookPrefix ?? ""; + var version = options.Version ?? "current"; + var guideUrl = $"https://www.elastic.co/guide/{prefix}/{version}/{xref.Target}.html"; + var rewritten = GuideUrlRewriter.TryRewriteToInternal(guideUrl); + Write($"[{text}]({rewritten ?? guideUrl})"); + } + + private void EmitFootnote(FootnoteInline footnote) + { + _footnoteCounter++; + var index = _footnoteCounter; + Write($"[^{index}]"); + + var content = CaptureOutput(() => + { + foreach (var child in footnote.Content) + EmitInline(child); + }); + _footnotes.Add((index, content)); + } + + private void AppendFootnotes() + { + if (_footnotes.Count == 0) + return; + + WriteLine(); + foreach (var (index, content) in _footnotes) + WriteLine($"[^{index}]: {content}"); + } + + [GeneratedRegex(@"\{([a-z][a-z0-9_-]*)\}")] + private static partial Regex AttrRefRegex(); + + [GeneratedRegex(@"<<([^,>\n]+)(?:,([^>\n]+))?>>")] + private static partial Regex TitleXrefRegex(); + + // Replaces {name} → {{name}} for product-name subs in raw title strings (which + // bypass ParseInlines and never hit the AttributeRefInline emission path). + private static string SubstituteTitleAttrs(string title) => + AttrRefRegex().Replace(title, m => + SharedAttributes.ProductNames.ContainsKey(m.Groups[1].Value) + ? $"{{{{{m.Groups[1].Value}}}}}" + : m.Value); + + // Replaces <> and <> xrefs in raw title strings. + private string SubstituteTitleXrefs(string title) => + TitleXrefRegex().Replace(title, m => + { + var anchor = m.Groups[1].Value.Trim(); + var text = m.Groups[2].Success ? m.Groups[2].Value.Trim() : anchor; + if (options.AnchorToSlugMap.TryGetValue(anchor, out var slug)) + return slug == options.PageSlug ? $"[{text}](#{anchor})" : $"[{text}]({slug}.md#{anchor})"; + return $"[{text}](#{anchor})"; + }); +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs new file mode 100644 index 0000000000..dd2311765d --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs @@ -0,0 +1,192 @@ +// 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 System.Text.RegularExpressions; +using Elastic.LegacyDocs.Migration.Asciidoc.Ast; +using Slugify; + +namespace Elastic.LegacyDocs.Migration.Asciidoc; + +public record PageOutput(string Slug, string Title, string MarkdownContent); + +public static partial class PageChunker +{ + private static readonly SlugHelper SlugHelper = new(); + + [GeneratedRegex(@"^(.*)\s*$", RegexOptions.Singleline)] + private static partial Regex TitleAbbrevRegex(); + + public static IReadOnlyList Chunk(AsciidocDocument document, int chunkLevel, MarkdownEmitter emitter) + { + if (chunkLevel <= 0) + { + emitter.UpdatePageSlug("index"); + return [new PageOutput("index", document.Title ?? "Index", emitter.Emit(document))]; + } + + var (slugMap, titleMap) = BuildAnchorMaps(document.Children, chunkLevel); + emitter.UpdateAnchorMap(slugMap, titleMap); + + var (pages, remaining) = ExtractPages(document.Children, chunkLevel, emitter); + + var indexDoc = document with { Children = remaining.ToList() }; + emitter.UpdatePageSlug("index"); + var indexContent = emitter.Emit(indexDoc); + var indexPage = new PageOutput("index", document.Title ?? "Index", indexContent); + + return [indexPage, .. pages]; + } + + private static (Dictionary SlugMap, Dictionary TitleMap) BuildAnchorMaps( + IReadOnlyList children, int chunkLevel) + { + var slugMap = new Dictionary(StringComparer.OrdinalIgnoreCase); + var titleMap = new Dictionary(StringComparer.OrdinalIgnoreCase); + CollectAnchors(children, chunkLevel, slugMap, titleMap); + return (slugMap, titleMap); + } + + private static void CollectAnchors( + IReadOnlyList children, int chunkLevel, + Dictionary slugMap, Dictionary titleMap) + { + foreach (var child in children) + { + // Recurse transparently into open blocks — they may contain sections or anchored blocks + if (child is OpenBlockNode open) + { + CollectAnchors(open.Children, chunkLevel, slugMap, titleMap); + continue; + } + + if (child is not SectionNode section) + continue; + + // Non-include-root Level-0 sections are transparent book-root wrappers + if (section.Level == 0 && !section.IsIncludeRoot) + { + CollectAnchors(section.Children, chunkLevel, slugMap, titleMap); + continue; + } + + // Include roots and sections within chunk depth each become a page + if (section.IsIncludeRoot || section.Level <= chunkLevel) + { + var slug = section.Id ?? GenerateSlug(section.Title); + if (section.Id is not null) + { + slugMap[section.Id] = slug; + titleMap[section.Id] = ExtractDisplayTitle(section); + } + + CollectChildAnchors(section.Children, slug, slugMap, titleMap); + CollectAnchors(section.Children, chunkLevel, slugMap, titleMap); + } + else + { + // Inline section deeper than chunkLevel — recurse for nested IsIncludeRoot sections + CollectAnchors(section.Children, chunkLevel, slugMap, titleMap); + } + } + } + + // Extracts the display title for a section: uses if present, otherwise the section title. + private static string ExtractDisplayTitle(SectionNode section) + { + foreach (var child in section.Children) + { + if (child is not PassthroughNode passthrough) + continue; + var m = TitleAbbrevRegex().Match(passthrough.Content.Trim()); + if (m.Success) + return m.Groups[1].Value; + } + return section.Title; + } + + private static void CollectChildAnchors( + IReadOnlyList children, string parentSlug, + Dictionary slugMap, Dictionary titleMap) + { + foreach (var child in children) + { + if (child is SectionNode sub && sub.Id is not null) + { + slugMap[sub.Id] = parentSlug; + titleMap[sub.Id] = ExtractDisplayTitle(sub); + CollectChildAnchors(sub.Children, parentSlug, slugMap, titleMap); + } + else if (child is AnchoredBlock anchored) + { + slugMap[anchored.Id] = parentSlug; + } + } + } + + private static (List Pages, List Remaining) ExtractPages( + IReadOnlyList children, + int chunkLevel, + MarkdownEmitter emitter + ) + { + var pages = new List(); + var remaining = new List(); + + foreach (var child in children) + { + // Recurse transparently into open blocks so nested sections are chunked correctly + if (child is OpenBlockNode open) + { + var (innerPages, innerRemaining) = ExtractPages(open.Children, chunkLevel, emitter); + pages.AddRange(innerPages); + if (innerRemaining.Count > 0) + remaining.Add(open with { Children = innerRemaining.ToList() }); + continue; + } + + if (child is not SectionNode section) + { + remaining.Add(child); + continue; + } + + // Non-include-root Level-0 sections are transparent book-root wrappers + if (section.Level == 0 && !section.IsIncludeRoot) + { + var (innerPages, innerRemaining) = ExtractPages(section.Children, chunkLevel, emitter); + pages.AddRange(innerPages); + remaining.Add(section with { Children = innerRemaining.ToList() }); + continue; + } + + // Inline sections above the chunk depth stay in the parent page, but their + // children may still contain IsIncludeRoot sections that must be extracted. + if (section.Level > chunkLevel && !section.IsIncludeRoot) + { + var (innerPages, innerRemaining) = ExtractPages(section.Children, chunkLevel, emitter); + pages.AddRange(innerPages); + remaining.Add(section with { Children = innerRemaining.ToList() }); + continue; + } + + var (subPages, sectionRemaining) = ExtractPages(section.Children, chunkLevel, emitter); + + var trimmedSection = section with { Children = sectionRemaining.ToList(), Level = 0 }; + var slug = section.Id ?? GenerateSlug(section.Title); + emitter.UpdatePageSlug(slug); + var content = emitter.Emit(trimmedSection); + + pages.Add(new PageOutput(slug, section.Title, content)); + pages.AddRange(subPages); + } + + return (pages, remaining); + } + + private static string GenerateSlug(string title) + { + var slug = SlugHelper.GenerateSlug(title); + return string.IsNullOrEmpty(slug) ? "section" : slug; + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/BranchRefConverter.cs b/src/authoring/Elastic.LegacyDocs.Migration/BranchRefConverter.cs new file mode 100644 index 0000000000..3304748d41 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/BranchRefConverter.cs @@ -0,0 +1,112 @@ +// 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 YamlDotNet.Core; +using YamlDotNet.Core.Events; +using YamlDotNet.Serialization; + +namespace Elastic.LegacyDocs.Migration; + +/// Handles mixed-type branch sequences: plain strings and alias dicts like {alias: branch}. +public class BranchRefListConverter : IYamlTypeConverter +{ + public bool Accepts(Type type) => type == typeof(List); + + public object? ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeserializer) + { + var list = new List(); + + if (!parser.TryConsume(out _)) + return list; + + while (!parser.TryConsume(out _)) + { + if (parser.TryConsume(out var scalar)) + { + list.Add(new BranchRef(scalar.Value)); + } + else if (parser.TryConsume(out _)) + { + // {alias: branch} — first key-value pair wins + var key = parser.Consume(); + var value = parser.Consume(); + list.Add(new BranchRef(Name: value.Value, Alias: key.Value)); + + // Consume remaining pairs (shouldn't exist but be safe) + while (!parser.TryConsume(out _)) + { + _ = parser.Consume(); + _ = parser.Consume(); + } + } + } + + return list; + } + + public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializer serializer) + { + if (value is not List list) + return; + + emitter.Emit(new SequenceStart(null, null, false, SequenceStyle.Block)); + + foreach (var branch in list) + { + if (branch.Alias is not null) + { + emitter.Emit(new MappingStart(null, null, false, MappingStyle.Flow)); + emitter.Emit(new Scalar(branch.Alias)); + emitter.Emit(new Scalar(branch.Name)); + emitter.Emit(new MappingEnd()); + } + else + { + emitter.Emit(new Scalar(branch.Name)); + } + } + + emitter.Emit(new SequenceEnd()); + } +} + +/// Handles a single scalar or mapping node. +public class BranchRefConverter : IYamlTypeConverter +{ + public bool Accepts(Type type) => type == typeof(BranchRef); + + public object? ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeserializer) + { + if (parser.TryConsume(out var scalar)) + return new BranchRef(scalar.Value); + + if (parser.TryConsume(out _)) + { + var key = parser.Consume(); + var value = parser.Consume(); + _ = parser.Consume(); + return new BranchRef(Name: value.Value, Alias: key.Value); + } + + throw new YamlException("Expected scalar or mapping for BranchRef"); + } + + public void WriteYaml(IEmitter emitter, object? value, Type type, ObjectSerializer serializer) + { + if (value is not BranchRef branch) + return; + + if (branch.Alias is not null) + { + emitter.Emit(new MappingStart(null, null, false, MappingStyle.Flow)); + emitter.Emit(new Scalar(branch.Alias)); + emitter.Emit(new Scalar(branch.Name)); + emitter.Emit(new MappingEnd()); + } + else + { + emitter.Emit(new Scalar(branch.Name)); + } + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Elastic.LegacyDocs.Migration.csproj b/src/authoring/Elastic.LegacyDocs.Migration/Elastic.LegacyDocs.Migration.csproj new file mode 100644 index 0000000000..e9f26ad0b9 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/Elastic.LegacyDocs.Migration.csproj @@ -0,0 +1,16 @@ + + + + net10.0 + enable + enable + + + + + + + + + + diff --git a/src/authoring/Elastic.LegacyDocs.Migration/LatestDocsetGenerator.cs b/src/authoring/Elastic.LegacyDocs.Migration/LatestDocsetGenerator.cs new file mode 100644 index 0000000000..f05c4ab7e7 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/LatestDocsetGenerator.cs @@ -0,0 +1,113 @@ +// 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.LegacyDocs.Migration.Asciidoc; +using Microsoft.Extensions.Logging; +using Slugify; + +namespace Elastic.LegacyDocs.Migration; + +public record LatestGeneratorOptions +{ + public required string OutputDirectory { get; init; } + public string? BookFilter { get; init; } + public required SourceRepoManager RepoManager { get; init; } +} + +public class LatestDocsetGenerator(ILogger logger) +{ + private static readonly SlugHelper SlugHelper = new(); + + public async Task GenerateAsync(LegacyConf conf, LatestGeneratorOptions options, CancellationToken ct = default) + { + var books = conf.Contents + .SelectMany(c => c.Sections) + .Where(b => options.BookFilter is null || b.Prefix == options.BookFilter) + .ToList(); + + logger.LogInformation("Processing {BookCount} books in latest mode", books.Count); + + foreach (var book in books) + { + ct.ThrowIfCancellationRequested(); + + if (string.IsNullOrEmpty(book.Current)) + { + logger.LogWarning("No current version for {BookPrefix} — skipping", book.Prefix); + continue; + } + + await ProcessBook(book, options, ct); + } + + logger.LogInformation("Latest generation complete"); + } + + private async Task ProcessBook(LegacyBook book, LatestGeneratorOptions options, CancellationToken ct) + { + var currentBranch = book.Branches.FirstOrDefault(b => b.VersionLabel == book.Current) + ?? new BranchRef(book.Current); + + var sources = await options.RepoManager.ResolveSourcesAsync(book, currentBranch, ct); + if (sources.Count == 0) + { + logger.LogWarning("No sources resolved for {Prefix}", book.Prefix); + return; + } + + var primarySource = sources[0]; + var indexPath = Path.Combine(primarySource.LocalPath, book.Index); + if (!File.Exists(indexPath)) + { + logger.LogWarning("Index file not found: {IndexPath}", indexPath); + return; + } + + var content = await File.ReadAllTextAsync(indexPath, ct); + var basePath = Path.GetDirectoryName(indexPath) ?? primarySource.LocalPath; + var parserOptions = new AsciidocParserOptions + { + Attributes = new Dictionary + { + ["branch"] = book.Current, + ["doc-tests-src"] = primarySource.LocalPath + } + }; + var parser = new AsciidocParser(parserOptions); + var document = parser.Parse(content, basePath); + + var emitterOptions = new MarkdownEmitterOptions + { + BookPrefix = book.Prefix, + Version = book.Current + }; + var emitter = new MarkdownEmitter(emitterOptions); + var pages = PageChunker.Chunk(document, book.Chunk, emitter); + + if (pages.Count == 0) + { + logger.LogWarning("No pages generated for {Prefix}", book.Prefix); + return; + } + + var repoName = primarySource.RepoName; + var docsDir = Path.Combine(options.OutputDirectory, repoName, "docs"); + _ = Directory.CreateDirectory(docsDir); + + var fileEntries = new List(); + foreach (var page in pages) + { + var filename = $"{page.Slug}.md"; + await File.WriteAllTextAsync(Path.Combine(docsDir, filename), page.MarkdownContent, ct); + fileEntries.Add(new TocEntry { File = filename }); + } + + var projectName = SlugHelper.GenerateSlug(book.Title); + YamlWriter.WriteDocsetYaml(Path.Combine(docsDir, "docset.yml"), projectName, ["."]); + YamlWriter.WriteTocYaml(Path.Combine(docsDir, "toc.yml"), fileEntries); + + logger.LogInformation("Wrote {PageCount} pages for {RepoName}/docs (project: {Project})", + pages.Count, repoName, projectName); + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/LegacyConf.cs b/src/authoring/Elastic.LegacyDocs.Migration/LegacyConf.cs new file mode 100644 index 0000000000..ebc1eaa478 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/LegacyConf.cs @@ -0,0 +1,53 @@ +// 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.LegacyDocs.Migration; + +public record LegacyConf +{ + public Dictionary Repos { get; init; } = []; + public List Contents { get; init; } = []; +} + +public record LegacyCategory +{ + public string Title { get; init; } = ""; + public List Sections { get; init; } = []; +} + +public record LegacyBook +{ + public string Title { get; init; } = ""; + public string Prefix { get; init; } = ""; + public string BaseDir { get; init; } = ""; + public string Index { get; init; } = ""; + public string Current { get; init; } = ""; + public List Branches { get; init; } = []; + public List Live { get; init; } = []; + public int Chunk { get; init; } = 1; + public string? Tags { get; init; } + public string? Subject { get; init; } + public List Sources { get; init; } = []; + /// Sub-groups within a book entry. Used during conf.yaml parsing only; flattened before use. + public List Sections { get; init; } = []; +} + +public record LegacySource +{ + public string Repo { get; init; } = ""; + public string Path { get; init; } = ""; + public string? Prefix { get; init; } + public bool Private { get; init; } + public List ExcludeBranches { get; init; } = []; + public Dictionary MapBranches { get; init; } = []; +} + +public record BranchRef(string Name, string? Alias = null) +{ + /// Version label used in output paths and URLs. + public string VersionLabel => Alias ?? Name; + + /// Actual git branch to clone. + public string GitBranch => Name; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/LegacyConfParser.cs b/src/authoring/Elastic.LegacyDocs.Migration/LegacyConfParser.cs new file mode 100644 index 0000000000..9687257045 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/LegacyConfParser.cs @@ -0,0 +1,70 @@ +// 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 YamlDotNet.Serialization; +using YamlDotNet.Serialization.NamingConventions; + +namespace Elastic.LegacyDocs.Migration; + +public static class LegacyConfParser +{ + private static readonly IDeserializer RawDeserializer = new DeserializerBuilder().Build(); + + private static readonly ISerializer RoundTripSerializer = new SerializerBuilder() + .DisableAliases() + .Build(); + + private static readonly IDeserializer TypedDeserializer = new DeserializerBuilder() + .WithNamingConvention(UnderscoredNamingConvention.Instance) + .WithTypeConverter(new BranchRefListConverter()) + .WithTypeConverter(new BranchRefConverter()) + .IgnoreUnmatchedProperties() + .Build(); + + public static LegacyConf Parse(string yaml) + { + var raw = RawDeserializer.Deserialize(yaml); + var resolved = RoundTripSerializer.Serialize(raw); + var conf = TypedDeserializer.Deserialize(resolved) ?? new LegacyConf(); + return Flatten(conf); + } + + private static LegacyConf Flatten(LegacyConf conf) + { + var flatCategories = conf.Contents + .Select(c => c with { Sections = FlattenBooks(c.Sections, "") }) + .ToList(); + return conf with { Contents = flatCategories }; + } + + /// + /// Recursively flattens nested sub-group entries (those with sections but no sources) + /// into leaf records, accumulating the base_dir prefix as we descend. + /// + private static List FlattenBooks(List books, string parentBaseDir) + { + var result = new List(); + foreach (var book in books) + { + var dir = parentBaseDir.Length > 0 && book.BaseDir.Length > 0 + ? $"{parentBaseDir}/{book.BaseDir}" + : parentBaseDir.Length > 0 + ? parentBaseDir + : book.BaseDir; + + if (book.Sections.Count > 0) + { + result.AddRange(FlattenBooks(book.Sections, dir)); + } + else + { + var prefix = dir.Length > 0 && !book.Prefix.StartsWith(dir, StringComparison.Ordinal) + ? $"{dir}/{book.Prefix}" + : book.Prefix; + result.Add(book with { Prefix = prefix }); + } + } + return result; + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/SharedAttributes.cs b/src/authoring/Elastic.LegacyDocs.Migration/SharedAttributes.cs new file mode 100644 index 0000000000..9b22ca0730 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/SharedAttributes.cs @@ -0,0 +1,170 @@ +// 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.LegacyDocs.Migration; + +/// +/// Well-known AsciiDoc attributes from elastic/docs shared/attributes.asciidoc +/// that map to simple display strings (not URLs). +/// These are emitted as subs in the generated docset.yml. +/// +public static class SharedAttributes +{ + public static readonly Dictionary ProductNames = new(StringComparer.OrdinalIgnoreCase) + { + // Cloud + ["ecloud"] = "Elastic Cloud", + ["ess"] = "Elasticsearch Service", + ["ech"] = "Elastic Cloud Hosted", + ["ece"] = "Elastic Cloud Enterprise", + ["eck"] = "Elastic Cloud on Kubernetes", + ["esf"] = "Elastic Serverless Forwarder", + ["serverless-full"] = "Elastic Cloud Serverless", + ["serverless-short"] = "Serverless", + ["es-serverless"] = "Elasticsearch Serverless", + ["obs-serverless"] = "Elastic Observability Serverless", + ["sec-serverless"] = "Elastic Security Serverless", + + // Core products + ["es"] = "Elasticsearch", + ["kib"] = "Kibana", + ["ls"] = "Logstash", + ["beats"] = "Beats", + ["stack"] = "Elastic Stack", + ["xpack"] = "X-Pack", + ["es-sql"] = "Elasticsearch SQL", + ["esql"] = "ES|QL", + + // Beats + ["auditbeat"] = "Auditbeat", + ["filebeat"] = "Filebeat", + ["heartbeat"] = "Heartbeat", + ["metricbeat"] = "Metricbeat", + ["packetbeat"] = "Packetbeat", + ["winlogbeat"] = "Winlogbeat", + ["functionbeat"] = "Functionbeat", + ["journalbeat"] = "Journalbeat", + + // Agents and ingest + ["agent"] = "Elastic Agent", + ["agents"] = "Elastic Agents", + ["fleet"] = "Fleet", + ["fleet-server"] = "Fleet Server", + ["integrations-server"] = "Integrations Server", + ["integrations"] = "Integrations", + + // Enterprise Search + ["ents"] = "Enterprise Search", + ["crawler"] = "Enterprise Search web crawler", + + // Observability + ["observability"] = "Observability", + + // Security + ["elastic-sec"] = "Elastic Security", + ["elastic-defend"] = "Elastic Defend", + ["elastic-endpoint"] = "Elastic Endpoint", + ["endpoint-sec"] = "Endpoint Security", + + // ML + ["ml"] = "machine learning", + ["ml-cap"] = "Machine learning", + ["ml-init"] = "ML", + ["nlp"] = "natural language processing", + ["nlp-cap"] = "Natural language processing", + + // Features + ["security"] = "X-Pack security", + ["security-features"] = "security features", + ["monitor-features"] = "monitoring features", + ["ml-features"] = "machine learning features", + ["alert-features"] = "alerting features", + ["report-features"] = "reporting features", + ["graph-features"] = "graph analytics features", + ["watcher"] = "Watcher", + ["monitoring"] = "X-Pack monitoring", + ["reporting"] = "X-Pack reporting", + ["graph"] = "X-Pack graph", + + // Abbreviations + ["ccr"] = "cross-cluster replication", + ["ccr-cap"] = "Cross-cluster replication", + ["ccr-init"] = "CCR", + ["ccs"] = "cross-cluster search", + ["ccs-cap"] = "Cross-cluster search", + ["ccs-init"] = "CCS", + ["ilm"] = "index lifecycle management", + ["ilm-cap"] = "Index lifecycle management", + ["ilm-init"] = "ILM", + ["slm"] = "snapshot lifecycle management", + ["slm-cap"] = "Snapshot lifecycle management", + ["slm-init"] = "SLM", + ["rollup"] = "rollup", + ["rollup-cap"] = "Rollup", + ["transform"] = "transform", + ["transform-cap"] = "Transform", + ["transforms"] = "transforms", + ["transforms-cap"] = "Transforms", + ["dfeed"] = "datafeed", + ["dfeeds"] = "datafeeds", + ["anomaly-detect"] = "anomaly detection", + ["anomaly-detect-cap"] = "Anomaly detection", + ["infer"] = "inference", + ["infer-cap"] = "Inference", + ["search-snaps"] = "searchable snapshots", + ["search-snaps-cap"] = "Searchable snapshots", + + // Data views + ["data-source"] = "data view", + ["data-sources"] = "data views", + ["data-source-cap"] = "Data view", + ["data-sources-cap"] = "Data views", + + // Kibana apps + ["apm-app"] = "APM app", + ["uptime-app"] = "Uptime app", + ["synthetics-app"] = "Synthetics app", + ["logs-app"] = "Logs app", + ["metrics-app"] = "Metrics app", + ["infrastructure-app"] = "Infrastructure app", + ["security-app"] = "Elastic Security app", + ["ml-app"] = "Machine Learning", + ["dev-tools-app"] = "Dev Tools", + ["stack-manage-app"] = "Stack Management", + ["stack-monitor-app"] = "Stack Monitoring", + ["maps-app"] = "Maps", + ["data-views-app"] = "Data Views", + + // APM agents + ["apm-agent"] = "APM agent", + ["apm-go-agent"] = "Elastic APM Go agent", + ["apm-java-agent"] = "Elastic APM Java agent", + ["apm-dotnet-agent"] = "Elastic APM .NET agent", + ["apm-node-agent"] = "Elastic APM Node.js agent", + ["apm-php-agent"] = "Elastic APM PHP agent", + ["apm-py-agent"] = "Elastic APM Python agent", + ["apm-ruby-agent"] = "Elastic APM Ruby agent", + ["apm-rum-agent"] = "Elastic APM Real User Monitoring (RUM) JavaScript agent", + + // Misc + ["k8s"] = "Kubernetes", + ["aws"] = "AWS", + ["esh"] = "ES-Hadoop", + ["searchprofiler"] = "Search Profiler", + ["data-viz"] = "Data Visualizer", + ["feat-imp"] = "feature importance", + ["feat-imp-cap"] = "Feature importance", + + // Connectors + ["sn"] = "ServiceNow", + ["sn-itsm"] = "ServiceNow ITSM", + ["sn-itom"] = "ServiceNow ITOM", + ["sn-sir"] = "ServiceNow SecOps", + ["jira"] = "Jira", + ["swimlane"] = "Swimlane", + ["opsgenie"] = "Opsgenie", + ["bedrock"] = "Amazon Bedrock", + ["gemini"] = "Google Gemini", + }; +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/SourceRepoManager.cs b/src/authoring/Elastic.LegacyDocs.Migration/SourceRepoManager.cs new file mode 100644 index 0000000000..eb34619a0b --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/SourceRepoManager.cs @@ -0,0 +1,256 @@ +// 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 System.Collections.Concurrent; +using Microsoft.Extensions.Logging; +using ProcNet; + +namespace Elastic.LegacyDocs.Migration; + +public record SourceRepoOptions +{ + public required string ReposDirectory { get; init; } + public Dictionary RepoUrls { get; init; } = []; + public Dictionary> SparsePaths { get; init; } = []; +} + +public record ResolvedSource +{ + public string RepoName { get; init; } = ""; + public string GitBranch { get; init; } = ""; + public string DocsPath { get; init; } = ""; + public string? Prefix { get; init; } + public required string LocalPath { get; init; } +} + +public class SourceRepoManager(SourceRepoOptions options, ILogger logger) +{ + private readonly ConcurrentDictionary _resolvedPaths = []; + private readonly ConcurrentDictionary _bareClones = []; + + /// Collects all declared source paths per repo from the conf.yaml book definitions. + public static Dictionary> CollectSparsePaths(LegacyConf conf) + { + var result = new Dictionary>(StringComparer.OrdinalIgnoreCase); + + foreach (var book in conf.Contents.SelectMany(c => c.Sections)) + { + foreach (var source in book.Sources) + { + if (!result.TryGetValue(source.Repo, out var paths)) + { + paths = [with(StringComparer.OrdinalIgnoreCase)]; + result[source.Repo] = paths; + } + + var normalized = NormalizeSparsePath(source.Path); + if (normalized is not null) + _ = paths.Add(normalized); + } + } + + return result; + } + + public async Task> ResolveSourcesAsync( + LegacyBook book, BranchRef version, CancellationToken ct = default) + { + var results = new List(); + var versionLabel = version.VersionLabel; + var defaultGitBranch = version.GitBranch; + + foreach (var source in book.Sources) + { + if (IsExcluded(source, versionLabel)) + continue; + + var gitBranch = ResolveBranch(source, versionLabel, defaultGitBranch); + + try + { + var localPath = await EnsureWorktreeAsync(source.Repo, gitBranch, ct); + results.Add(new ResolvedSource + { + RepoName = source.Repo, + GitBranch = gitBranch, + DocsPath = source.Path, + Prefix = source.Prefix, + LocalPath = localPath + }); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + logger.LogWarning("Skipping {Repo}@{Branch}: {Message}", source.Repo, gitBranch, ex.Message); + } + } + + return results; + } + + public void CleanAll() + { + if (!Directory.Exists(options.ReposDirectory)) + return; + + logger.LogInformation("Cleaning repos directory: {ReposDir}", options.ReposDirectory); + Directory.Delete(options.ReposDirectory, recursive: true); + _resolvedPaths.Clear(); + _bareClones.Clear(); + } + + private static bool IsExcluded(LegacySource source, string versionLabel) => + source.ExcludeBranches.Any(b => b.VersionLabel == versionLabel); + + private static string ResolveBranch(LegacySource source, string versionLabel, string defaultGitBranch) => + source.MapBranches.TryGetValue(versionLabel, out var mapped) ? mapped : defaultGitBranch; + + private string BareClonePath(string repoName) => + Path.Combine(options.ReposDirectory, $"{repoName}.git"); + + private string WorktreePath(string repoName, string gitBranch) => + Path.Combine(options.ReposDirectory, repoName, gitBranch); + + private async Task EnsureBareCloneAsync(string repoName, CancellationToken ct) + { + if (_bareClones.ContainsKey(repoName)) + return; + + var barePath = BareClonePath(repoName); + if (Directory.Exists(barePath)) + { + _bareClones[repoName] = true; + return; + } + + if (!options.RepoUrls.TryGetValue(repoName, out var url)) + throw new InvalidOperationException($"Unknown repo: {repoName}"); + + logger.LogInformation("Cloning bare {Repo}...", repoName); + + _ = Directory.CreateDirectory(options.ReposDirectory); + await ExecGitAsync(ct, "clone", "--bare", "--filter=blob:none", url, barePath); + + _bareClones[repoName] = true; + logger.LogInformation("Cloned bare {Repo}", repoName); + } + + private async Task EnsureWorktreeAsync(string repoName, string gitBranch, CancellationToken ct) + { + var key = $"{repoName}/{gitBranch}"; + + if (_resolvedPaths.TryGetValue(key, out var existing)) + return existing; + + var worktreePath = WorktreePath(repoName, gitBranch); + + if (Directory.Exists(worktreePath)) + { + _resolvedPaths[key] = worktreePath; + return worktreePath; + } + + await EnsureBareCloneAsync(repoName, ct); + + var barePath = BareClonePath(repoName); + + var resolvedBranch = await ResolveBranchAsync(barePath, gitBranch, ct); + + logger.LogInformation("Creating worktree {Repo}@{Branch}...", repoName, resolvedBranch); + _ = Directory.CreateDirectory(Path.GetDirectoryName(worktreePath)!); + await ExecGitInAsync(barePath, allowFailure: false, ct, "worktree", "add", "--detach", worktreePath, resolvedBranch, "--no-checkout"); + + await ApplySparseCheckoutAsync(repoName, worktreePath, ct); + + await ExecGitInAsync(worktreePath, allowFailure: true, ct, "checkout"); + + _resolvedPaths[key] = worktreePath; + logger.LogInformation("Ready {Repo}@{Branch}", repoName, gitBranch); + return worktreePath; + } + + private async Task ApplySparseCheckoutAsync(string repoName, string worktreePath, CancellationToken ct) + { + if (!options.SparsePaths.TryGetValue(repoName, out var paths) || paths.Count == 0) + return; + + logger.LogInformation("Sparse checkout {Repo}: {Paths}", repoName, string.Join(", ", paths)); + + await ExecGitInAsync(worktreePath, allowFailure: false, ct, "sparse-checkout", "init", "--cone"); + await ExecGitInAsync(worktreePath, allowFailure: false, ct, ["sparse-checkout", "set", .. paths]); + } + + private async Task ResolveBranchAsync(string barePath, string gitBranch, CancellationToken ct) + { + string[] candidates = [gitBranch, "master", "main"]; + + foreach (var branch in candidates) + { + var existsLocally = await TryExecGitInAsync(barePath, ct, "rev-parse", "--verify", branch); + if (existsLocally) + return branch; + } + + foreach (var branch in candidates) + { + logger.LogInformation("Fetching {Branch}...", branch); + var fetched = await TryExecGitInAsync(barePath, ct, "fetch", "origin", $"+{branch}:refs/heads/{branch}", "--depth", "1"); + if (fetched) + return branch; + } + + throw new InvalidOperationException($"No branch found for {gitBranch} (also tried master, main) in {barePath}"); + } + + private static async Task TryExecGitInAsync(string workingDirectory, CancellationToken ct, params string[] args) + { + var arguments = new ExecArguments("git", args) + { + WorkingDirectory = workingDirectory, + ValidExitCodeClassifier = _ => true + }; + var exitCode = await Proc.ExecAsync(arguments, ct); + return exitCode == 0; + } + + private static async Task ExecGitAsync(CancellationToken ct, params string[] args) + { + var arguments = new ExecArguments("git", args) + { + ValidExitCodeClassifier = _ => true + }; + var exitCode = await Proc.ExecAsync(arguments, ct); + if (exitCode != 0) + throw new InvalidOperationException($"git {args[0]} failed with exit code {exitCode}"); + } + + private static async Task ExecGitInAsync(string workingDirectory, bool allowFailure, CancellationToken ct, params string[] args) + { + var arguments = new ExecArguments("git", args) + { + WorkingDirectory = workingDirectory, + ValidExitCodeClassifier = _ => true + }; + var exitCode = await Proc.ExecAsync(arguments, ct); + if (exitCode != 0 && !allowFailure) + throw new InvalidOperationException( + $"git {args[0]} failed with exit code {exitCode} in {workingDirectory}"); + } + + /// Extracts the top-level directory from a source path for sparse checkout. + internal static string? NormalizeSparsePath(string sourcePath) + { + var trimmed = sourcePath.Trim().TrimStart('/').TrimEnd('/'); + if (string.IsNullOrEmpty(trimmed)) + return null; + + if (trimmed.Contains('*') || trimmed.StartsWith(":(glob)", StringComparison.Ordinal)) + return null; + + if (!trimmed.Contains('/')) + return trimmed; + + var firstSlash = trimmed.IndexOf('/'); + return trimmed[..firstSlash]; + } +} diff --git a/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs b/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs new file mode 100644 index 0000000000..0c276e8373 --- /dev/null +++ b/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs @@ -0,0 +1,54 @@ +// 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 System.Text; + +namespace Elastic.LegacyDocs.Migration; + +public record TocEntry +{ + public string? File { get; init; } + public string? Folder { get; init; } + public string? Toc { get; init; } +} + +public static class YamlWriter +{ + public static void WriteDocsetYaml(string path, string project, List tocRefs) + { + var sb = new StringBuilder(); + _ = sb.Append("project: ").Append(project).Append('\n'); + _ = sb.Append("toc:\n"); + foreach (var tocRef in tocRefs) + _ = sb.Append(" - toc: ").Append(tocRef).Append('\n'); + + EnsureDirectoryAndWrite(path, sb.ToString()); + } + + public static void WriteTocYaml(string path, List entries) + { + var sb = new StringBuilder(); + _ = sb.Append("toc:\n"); + foreach (var entry in entries) + { + if (entry.File is not null) + _ = sb.Append(" - file: ").Append(entry.File).Append('\n'); + else if (entry.Folder is not null) + _ = sb.Append(" - folder: ").Append(entry.Folder).Append('\n'); + else if (entry.Toc is not null) + _ = sb.Append(" - toc: ").Append(entry.Toc).Append('\n'); + } + + EnsureDirectoryAndWrite(path, sb.ToString()); + } + + private static void EnsureDirectoryAndWrite(string path, string content) + { + var directory = Path.GetDirectoryName(path); + if (directory is not null) + _ = Directory.CreateDirectory(directory); + + File.WriteAllText(path, content); + } +} diff --git a/src/tooling/adoc-compare/Program.cs b/src/tooling/adoc-compare/Program.cs new file mode 100644 index 0000000000..a462b13e24 --- /dev/null +++ b/src/tooling/adoc-compare/Program.cs @@ -0,0 +1,21 @@ +// 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.LegacyDocs.Migration.Asciidoc; + +var inputFile = args.Length > 0 ? args[0] : "test.adoc"; +var opts = new AsciidocParserOptions +{ + FileReader = path => File.Exists(path) ? File.ReadAllText(path) : null, + Attributes = new Dictionary + { + ["my-product"] = "Elasticsearch", + ["version"] = "8.16", + ["enterprise-only"] = "" + } +}; +var parser = new AsciidocParser(opts); +var doc = parser.Parse(inputFile); +var emitter = new MarkdownEmitter(new MarkdownEmitterOptions()); +Console.Write(emitter.Emit(doc)); diff --git a/src/tooling/adoc-compare/adoc-compare.csproj b/src/tooling/adoc-compare/adoc-compare.csproj new file mode 100644 index 0000000000..453fad727d --- /dev/null +++ b/src/tooling/adoc-compare/adoc-compare.csproj @@ -0,0 +1,10 @@ + + + Exe + net10.0 + enable + + + + + diff --git a/src/tooling/docs-builder/Commands/ServeCommand.cs b/src/tooling/docs-builder/Commands/ServeCommand.cs index 9c4b759957..515c839abd 100644 --- a/src/tooling/docs-builder/Commands/ServeCommand.cs +++ b/src/tooling/docs-builder/Commands/ServeCommand.cs @@ -21,11 +21,12 @@ internal sealed class ServeCommand(ILoggerFactory logFactory, IConfigurationCont /// -p, Documentation source directory. Defaults to the cwd/docs folder. /// Port to serve the documentation. Default: 3000 /// Special flag for dotnet watch optimizations during development + /// Disable the diagnostics HUD and background validation builds [CommandName("serve")] - public async Task Serve(GlobalCliOptions _, [Existing, ExpandUserProfile, RejectSymbolicLinks] DirectoryInfo? path = null, int port = 3000, bool watch = false, CancellationToken ct = default) + public async Task Serve(GlobalCliOptions _, [Existing, ExpandUserProfile, RejectSymbolicLinks] DirectoryInfo? path = null, int port = 3000, bool watch = false, bool noHud = false, CancellationToken ct = default) { - var host = new DocumentationWebHost(logFactory, path?.FullName, port, configurationContext, watch); + var host = new DocumentationWebHost(logFactory, path?.FullName, port, configurationContext, watch, noHud); await host.RunAsync(ct); _logger.LogInformation("Find your documentation at http://localhost:{Port}/{Path}", port, host.GeneratorState.Generator.DocumentationSet.FirstInterestingUrl.TrimStart('/') diff --git a/src/tooling/docs-builder/Http/DocumentationWebHost.cs b/src/tooling/docs-builder/Http/DocumentationWebHost.cs index 2dee21bcc7..43b9c869f9 100644 --- a/src/tooling/docs-builder/Http/DocumentationWebHost.cs +++ b/src/tooling/docs-builder/Http/DocumentationWebHost.cs @@ -47,7 +47,8 @@ public DocumentationWebHost(ILoggerFactory logFactory, string? path, int port, IConfigurationContext configurationContext, - bool isWatchBuild + bool isWatchBuild, + bool noHud = false ) { var builder = WebApplication.CreateSlimBuilder(); @@ -77,10 +78,8 @@ bool isWatchBuild CanonicalBaseUrl = new Uri(hostUrl), }; - // Enable diagnostics panel in serve mode - Context.Configuration.Features.DiagnosticsPanelEnabled = true; + Context.Configuration.Features.DiagnosticsPanelEnabled = !noHud; - // Create InMemoryBuildState for background validation builds InMemoryBuildState = new InMemoryBuildState(logFactory, configurationContext); GeneratorState = new ReloadableGeneratorState(logFactory, Context.DocumentationSourceDirectory, Context.OutputDirectory, Context, isWatchBuild); @@ -95,7 +94,7 @@ bool isWatchBuild .Configure(o => o.ShutdownTimeout = TimeSpan.FromSeconds(3)) .AddSingleton(_ => GeneratorState) .AddSingleton(_ => InMemoryBuildState) - .AddHostedService(sp => new ReloadGeneratorService(GeneratorState, InMemoryBuildState, logFactory.CreateLogger())); + .AddHostedService(sp => new ReloadGeneratorService(GeneratorState, InMemoryBuildState, noHud, logFactory.CreateLogger())); if (IsDotNetWatchBuild()) _ = builder.Services.AddHostedService(); @@ -308,12 +307,16 @@ private static async Task ServeDocumentationFile(ReloadableGeneratorSta slug = slug.Replace('/', Path.DirectorySeparatorChar); slug = slug.TrimEnd('/'); - var s = Path.GetExtension(slug) == string.Empty ? Path.Join(slug, "index.md") : slug; + // Path.GetExtension treats version segments like "8.19" as having extension ".19". + // Only treat the slug as a bare file path when the extension is a known document type. + var slugExt = Path.GetExtension(slug); + var hasKnownExtension = slugExt is ".md" or ".html" or ".json" or ".js" or ".css" or ".svg" or ".png" or ".jpg" or ".jpeg" or ".gif" or ".ico" or ".webp"; + var s = !hasKnownExtension ? Path.Join(slug, "index.md") : slug; var fp = new FilePath(s, generator.DocumentationSet.SourceDirectory); if (!generator.DocumentationSet.Files.TryGetValue(fp, out var documentationFile)) { - s = Path.GetExtension(slug) == string.Empty ? slug + ".md" : s.Replace($"{Path.DirectorySeparatorChar}index.md", ".md"); + s = !hasKnownExtension ? slug + ".md" : s.Replace($"{Path.DirectorySeparatorChar}index.md", ".md"); fp = new FilePath(s, generator.DocumentationSet.SourceDirectory); if (!generator.DocumentationSet.Files.TryGetValue(fp, out documentationFile)) { diff --git a/src/tooling/docs-builder/Http/ReloadGeneratorService.cs b/src/tooling/docs-builder/Http/ReloadGeneratorService.cs index 1097b5723e..4571640296 100644 --- a/src/tooling/docs-builder/Http/ReloadGeneratorService.cs +++ b/src/tooling/docs-builder/Http/ReloadGeneratorService.cs @@ -26,6 +26,7 @@ public static void UpdateApplication(Type[]? _) => Task.Run(async () => public sealed class ReloadGeneratorService( ReloadableGeneratorState reloadableGenerator, InMemoryBuildState inMemoryBuildState, + bool noHud, ILogger logger ) : IHostedService, IDisposable { @@ -52,10 +53,13 @@ public async Task StartAsync(Cancel cancellationToken) var sourcePath = ReloadableGenerator.Generator.Context.DocumentationCheckoutDirectory.FullName; await ReloadableGenerator.ReloadAsync(cancellationToken); - // Start the build loop; only shutdownCt (Ctrl+C / app exit) can cancel a running build. - // File-edit triggers enqueue via ScheduleBuild and never interrupt the current build. - _backgroundBuildTask = InMemoryBuildState.RunAsync(_serviceCts.Token); - InMemoryBuildState.ScheduleBuild(sourcePath); + if (!noHud) + { + // Start the build loop; only shutdownCt (Ctrl+C / app exit) can cancel a running build. + // File-edit triggers enqueue via ScheduleBuild and never interrupt the current build. + _backgroundBuildTask = InMemoryBuildState.RunAsync(_serviceCts.Token); + InMemoryBuildState.ScheduleBuild(sourcePath); + } var directory = ReloadableGenerator.Generator.Context.DocumentationCheckoutDirectory.FullName; Logger.LogInformation("Start file watch on: {Directory}", directory); @@ -99,10 +103,13 @@ private void Reload(bool reloadConfiguration = false) Logger.LogInformation("Reload complete!"); _ = LiveReloadMiddleware.RefreshWebSocketRequest(); - // Schedule a validation build after every reload — both content edits and structural changes. - // The build loop coalesces rapid triggers: a new request while a build runs queues one more. - var sourcePath = ReloadableGenerator.Generator.Context.DocumentationCheckoutDirectory.FullName; - InMemoryBuildState.ScheduleBuild(sourcePath); + if (!noHud) + { + // Schedule a validation build after every reload — both content edits and structural changes. + // The build loop coalesces rapid triggers: a new request while a build runs queues one more. + var sourcePath = ReloadableGenerator.Generator.Context.DocumentationCheckoutDirectory.FullName; + InMemoryBuildState.ScheduleBuild(sourcePath); + } }, token); } diff --git a/src/tooling/docs-migrate/CloneCommand.cs b/src/tooling/docs-migrate/CloneCommand.cs new file mode 100644 index 0000000000..c3c0bf1a9f --- /dev/null +++ b/src/tooling/docs-migrate/CloneCommand.cs @@ -0,0 +1,86 @@ +// 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.LegacyDocs.Migration; +using Microsoft.Extensions.Logging; + +namespace Documentation.Migrate; + +internal sealed class CloneCommand(ILoggerFactory logFactory) +{ + private readonly ILogger _logger = logFactory.CreateLogger(); + + /// Clone source repos needed for the selected books and versions. + /// Working directory for migration artifacts + /// Number of top major versions to include (default 1) + /// Max minor versions per major to include (default all) + /// Process all versions + /// Minimum major version to process + /// Filter to books whose prefix starts with this value + /// Delete all cloned repos and start fresh + /// Cancellation token + public async Task Clone( + string? workDir = null, + int majors = 1, + int? minors = null, + bool all = false, + int? minVersion = null, + string? book = null, + bool clean = false, + CancellationToken ct = default + ) + { + var dir = SharedOptions.ResolveWorkDir(workDir); + var conf = await SharedOptions.LoadConfAsync(dir, ct); + + var opts = new FilterOptions(majors, all, minVersion, book, minors); + // Save without Book — book filter is a per-run override, not a persistent setting + SharedOptions.SaveFilterOptions(dir, opts with { Book = null }); + + var books = SharedOptions.FilterBooks(conf, opts.Book); + + var reposDir = Path.Combine(dir, "repos"); + var sparsePaths = SourceRepoManager.CollectSparsePaths(conf); + var repoOptions = new SourceRepoOptions { ReposDirectory = reposDir, RepoUrls = conf.Repos, SparsePaths = sparsePaths }; + var repoManager = new SourceRepoManager(repoOptions, _logger); + + if (clean) + { + repoManager.CleanAll(); + _logger.LogInformation("Cleaned repos directory"); + return 0; + } + + var clonedBranches = new HashSet(StringComparer.OrdinalIgnoreCase); + var clonedRepos = new HashSet(StringComparer.OrdinalIgnoreCase); + + foreach (var b in books) + { + var versions = SharedOptions.FilterVersions(b, opts.Majors, opts.All, opts.MinVersion, opts.Minors); + foreach (var version in versions) + { + ct.ThrowIfCancellationRequested(); + + try + { + var sources = await repoManager.ResolveSourcesAsync(b, version, ct); + foreach (var source in sources) + { + _ = clonedRepos.Add(source.RepoName); + _ = clonedBranches.Add($"{source.RepoName}/{source.GitBranch}"); + } + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + _logger.LogWarning("Failed to clone for {Prefix} {Version}: {Message}", + b.Prefix, version.VersionLabel, ex.Message); + } + } + } + + _logger.LogInformation("Cloned {RepoCount} repos, {BranchCount} worktrees", + clonedRepos.Count, clonedBranches.Count); + return 0; + } +} diff --git a/src/tooling/docs-migrate/ConvertCommand.cs b/src/tooling/docs-migrate/ConvertCommand.cs new file mode 100644 index 0000000000..77a8d7328e --- /dev/null +++ b/src/tooling/docs-migrate/ConvertCommand.cs @@ -0,0 +1,274 @@ +// 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 System.Text; +using Elastic.LegacyDocs.Migration; +using Elastic.LegacyDocs.Migration.Asciidoc; +using Microsoft.Extensions.Logging; + +namespace Documentation.Migrate; + +internal sealed class ConvertCommand(ILoggerFactory logFactory) +{ + private readonly ILogger _logger = logFactory.CreateLogger(); + + /// Convert AsciiDoc books to Markdown docsets. + /// Working directory for migration artifacts + /// Override: number of top major versions to include + /// Override: max minor versions per major to include + /// Override: process all versions + /// Override: minimum major version to process + /// Override: filter to books whose prefix starts with this value + /// Cancellation token + public async Task Convert( + string? workDir = null, + int? majors = null, + int? minors = null, + bool? all = null, + int? minVersion = null, + string? book = null, + CancellationToken ct = default + ) + { + var dir = SharedOptions.ResolveWorkDir(workDir); + var conf = await SharedOptions.LoadConfAsync(dir, ct); + + var opts = SharedOptions.ResolveFilterOptions(dir, majors, all, minVersion, book, minors); + _logger.LogInformation( + "Filter: majors={Majors}, minors={Minors}, all={All}, minVersion={MinVersion}, book={Book}", + opts.Majors, opts.Minors.HasValue ? opts.Minors.Value.ToString(System.Globalization.CultureInfo.InvariantCulture) : "all", + opts.All, opts.MinVersion ?? (object)"any", opts.Book ?? "all"); + + var books = SharedOptions.FilterBooks(conf, opts.Book); + + var reposDir = Path.Combine(dir, "repos"); + var outputDir = Path.Combine(Directory.GetCurrentDirectory(), ".artifacts", "migrated"); + + var sparsePaths = SourceRepoManager.CollectSparsePaths(conf); + var repoOptions = new SourceRepoOptions { ReposDirectory = reposDir, RepoUrls = conf.Repos, SparsePaths = sparsePaths }; + var repoManager = new SourceRepoManager(repoOptions, logFactory.CreateLogger()); + + var convertedBooks = new Dictionary>(); + var tocRefs = new List(); + + foreach (var b in books) + { + ct.ThrowIfCancellationRequested(); + + var versions = SharedOptions.FilterVersions(b, opts.Majors, opts.All, opts.MinVersion, opts.Minors); + if (versions.Count == 0) + { + _logger.LogWarning("No versions to process for {BookPrefix}", b.Prefix); + continue; + } + + _logger.LogInformation("Book {Prefix}: {Count} versions to process", b.Prefix, versions.Count); + + var prefixDir = Path.Combine(outputDir, b.Prefix); + var versionEntries = new List(); + var convertedVersions = new List(); + + foreach (var version in versions) + { + ct.ThrowIfCancellationRequested(); + + var versionLabel = version.VersionLabel; + try + { + var pages = await ProcessBookVersion(b, version, repoManager, dir, ct); + if (pages.Count == 0) + continue; + + var versionDir = Path.Combine(prefixDir, versionLabel); + _ = Directory.CreateDirectory(versionDir); + + var fileEntries = await WritePages(pages, versionDir, ct); + YamlWriter.WriteTocYaml(Path.Combine(versionDir, "toc.yml"), fileEntries); + versionEntries.Add(new TocEntry { Toc = versionLabel }); + convertedVersions.Add(versionLabel); + + _logger.LogInformation("Wrote {PageCount} pages for {Prefix}/{Version}", + pages.Count, b.Prefix, versionLabel); + } + catch (Exception ex) when (ex is not OperationCanceledException) + { + _logger.LogError(ex, "Failed to process {Prefix}/{Version}", b.Prefix, versionLabel); + } + } + + if (versionEntries.Count == 0) + continue; + + tocRefs.Add(b.Prefix); + convertedBooks[b.Prefix] = convertedVersions; + + YamlWriter.WriteTocYaml(Path.Combine(prefixDir, "toc.yml"), [ + new TocEntry { File = "index.md" }, + ..versionEntries + ]); + + WriteBookVersionIndex(prefixDir, b, convertedVersions); + } + + if (tocRefs.Count > 0) + { + WriteGuideOverview(outputDir, conf, convertedBooks); + WriteRootDocsetYaml(outputDir, tocRefs); + } + + _logger.LogInformation("Conversion complete: {BookCount} books written to {OutputDir}", tocRefs.Count, outputDir); + return 0; + } + + private async Task> ProcessBookVersion( + LegacyBook book, BranchRef version, SourceRepoManager repoManager, string workDir, CancellationToken ct) + { + var versionLabel = version.VersionLabel; + var sources = await repoManager.ResolveSourcesAsync(book, version, ct); + if (sources.Count == 0) + { + _logger.LogWarning("No sources resolved for {Prefix} version {Version}", book.Prefix, versionLabel); + return []; + } + + var primarySource = sources[0]; + var indexPath = Path.Combine(primarySource.LocalPath, book.Index); + if (!File.Exists(indexPath)) + { + _logger.LogWarning("Index file not found: {IndexPath}", indexPath); + return []; + } + + var content = await File.ReadAllTextAsync(indexPath, ct); + var basePath = Path.GetDirectoryName(indexPath) ?? primarySource.LocalPath; + + // Seed branch-aware attributes first, then path attributes that may reference {branch} + var docsRoot = Path.Combine(workDir, "docs-repo"); + var seedAttributes = new Dictionary + { + ["branch"] = versionLabel, + ["source_branch"] = versionLabel, + ["doc-tests-src"] = primarySource.LocalPath, + // Path-based attributes used in include:: directives across the guide + ["docs-root"] = docsRoot, + ["asciidoc-dir"] = docsRoot, + }; + + foreach (var source in sources) + seedAttributes[$"{source.RepoName}-root"] = source.LocalPath; + + // Pre-load shared/attributes.asciidoc so feature/product name attributes like + // {transform}, {ilm-init}, {anomaly-detect} etc. are resolved during conversion. + var sharedAttrsPath = Path.Combine(docsRoot, "shared", "attributes.asciidoc"); + var attributes = AsciidocParser.LoadAttributeFile(sharedAttrsPath, seedAttributes); + + // Merge seed attributes back (they take precedence over shared attrs) + foreach (var (k, v) in seedAttributes) + attributes[k] = v; + + var parserOptions = new AsciidocParserOptions + { + Attributes = attributes, + OnDiagnostic = msg => _logger.LogDebug("Parser: {Message}", msg) + }; + var parser = new AsciidocParser(parserOptions); + var document = parser.Parse(content, basePath); + + var emitterOptions = new MarkdownEmitterOptions + { + BookPrefix = book.Prefix, + Version = versionLabel + }; + var emitter = new MarkdownEmitter(emitterOptions); + + // conf.yaml chunk: N means "chunk at N levels below the document root (= title)". + // The AST levels match directly: == is Level 1, === is Level 2, etc. + return PageChunker.Chunk(document, book.Chunk, emitter); + } + + private static async Task> WritePages( + IReadOnlyList pages, string directory, CancellationToken ct) + { + var entries = new List(); + foreach (var page in pages) + { + var filename = $"{page.Slug}.md"; + await File.WriteAllTextAsync(Path.Combine(directory, filename), page.MarkdownContent, ct); + entries.Add(new TocEntry { File = filename }); + } + return entries; + } + + private static void WriteBookVersionIndex(string prefixDir, LegacyBook book, List versions) + { + var sb = new StringBuilder(); + _ = sb.Append("# ").Append(book.Title).AppendLine(" — All Versions"); + _ = sb.AppendLine(); + _ = sb.AppendLine("| Version | Status |"); + _ = sb.AppendLine("|---|---|"); + + foreach (var v in versions) + { + var status = v == book.Current ? "current" : ""; + _ = sb.Append("| [").Append(v).Append("](").Append(v).Append("/index.md) | ").Append(status).AppendLine(" |"); + } + + File.WriteAllText(Path.Combine(prefixDir, "index.md"), sb.ToString()); + } + + private static void WriteGuideOverview( + string outputDir, LegacyConf conf, Dictionary> convertedBooks) + { + var sb = new StringBuilder(); + _ = sb.AppendLine("# Elastic Docs"); + _ = sb.AppendLine(); + + foreach (var category in conf.Contents) + { + var categoryBooks = category.Sections + .Where(b => convertedBooks.ContainsKey(b.Prefix)) + .ToList(); + + if (categoryBooks.Count == 0) + continue; + + _ = sb.Append("## ").AppendLine(category.Title); + + foreach (var b in categoryBooks) + { + var versions = convertedBooks[b.Prefix]; + var current = !string.IsNullOrEmpty(b.Current) && versions.Contains(b.Current) + ? b.Current + : versions[0]; + _ = sb.Append("- [").Append(b.Title).Append(" [").Append(current).Append("]](") + .Append(b.Prefix).Append('/').Append(current).Append("/index.md) — [other versions](") + .Append(b.Prefix).AppendLine("/index.md)"); + } + + _ = sb.AppendLine(); + } + + File.WriteAllText(Path.Combine(outputDir, "index.md"), sb.ToString()); + } + + private static void WriteRootDocsetYaml(string outputDir, List tocRefs) + { + var sb = new StringBuilder(); + _ = sb.AppendLine("project: elastic-guide-archive"); + _ = sb.AppendLine("features:"); + _ = sb.AppendLine(" guide-nav: true"); + + _ = sb.AppendLine("subs:"); + foreach (var (key, value) in SharedAttributes.ProductNames.OrderBy(kv => kv.Key, StringComparer.OrdinalIgnoreCase)) + _ = sb.Append(" ").Append(key).Append(": \"").Append(value.Replace("\"", "\\\"")).AppendLine("\""); + + _ = sb.AppendLine("toc:"); + _ = sb.AppendLine(" - file: index.md"); + + foreach (var prefix in tocRefs) + _ = sb.Append(" - toc: ").AppendLine(prefix); + + File.WriteAllText(Path.Combine(outputDir, "docset.yml"), sb.ToString()); + } +} diff --git a/src/tooling/docs-migrate/InitCommand.cs b/src/tooling/docs-migrate/InitCommand.cs new file mode 100644 index 0000000000..3a359cfa33 --- /dev/null +++ b/src/tooling/docs-migrate/InitCommand.cs @@ -0,0 +1,59 @@ +// 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.LegacyDocs.Migration; +using ProcNet; + +namespace Documentation.Migrate; + +internal sealed class InitCommand +{ + /// Clone the legacy docs repo and extract conf.yaml. + /// Working directory for migration artifacts + /// Re-clone even if conf.yaml already exists + /// Cancellation token + public async Task Init(string? workDir = null, bool force = false, CancellationToken ct = default) + { + var dir = SharedOptions.ResolveWorkDir(workDir); + var confPath = Path.Combine(dir, "conf.yaml"); + + if (File.Exists(confPath) && !force) + { + Console.WriteLine($"conf.yaml already exists at {confPath} (use --force to overwrite)"); + return 0; + } + + _ = Directory.CreateDirectory(dir); + + var docsRepoDir = Path.Combine(dir, "docs-repo"); + if (Directory.Exists(docsRepoDir)) + Directory.Delete(docsRepoDir, recursive: true); + + Console.WriteLine("Cloning elastic/docs (shallow)..."); + var arguments = new ExecArguments("git", ["clone", "--depth", "1", "https://github.com/elastic/docs.git", docsRepoDir]); + var exitCode = await Proc.ExecAsync(arguments, ct); + if (exitCode != 0) + { + Console.Error.WriteLine($"git clone failed with exit code {exitCode}"); + return 1; + } + + var sourceConf = Path.Combine(docsRepoDir, "conf.yaml"); + if (!File.Exists(sourceConf)) + { + Console.Error.WriteLine($"conf.yaml not found in cloned docs repo at {sourceConf}"); + return 1; + } + + File.Copy(sourceConf, confPath, overwrite: true); + Console.WriteLine($"Copied conf.yaml to {confPath}"); + + var yaml = await File.ReadAllTextAsync(confPath, ct); + var conf = LegacyConfParser.Parse(yaml); + var bookCount = conf.Contents.SelectMany(c => c.Sections).Count(); + Console.WriteLine($"Parsed conf.yaml: {bookCount} books across {conf.Contents.Count} categories"); + + return 0; + } +} diff --git a/src/tooling/docs-migrate/ListCommand.cs b/src/tooling/docs-migrate/ListCommand.cs new file mode 100644 index 0000000000..e57940283a --- /dev/null +++ b/src/tooling/docs-migrate/ListCommand.cs @@ -0,0 +1,41 @@ +// 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 Documentation.Migrate; + +internal sealed class ListCommand +{ + /// List all books from conf.yaml grouped by category. + /// Working directory for migration artifacts + /// Cancellation token + public async Task List(string? workDir = null, CancellationToken ct = default) + { + var dir = SharedOptions.ResolveWorkDir(workDir); + var conf = await SharedOptions.LoadConfAsync(dir, ct); + + foreach (var category in conf.Contents) + { + Console.WriteLine(); + Console.WriteLine($"== {category.Title} =="); + Console.WriteLine(); + + foreach (var book in category.Sections) + { + var versions = book.Branches; + var min = versions.Count > 0 ? versions[^1].VersionLabel : "—"; + var max = versions.Count > 0 ? versions[0].VersionLabel : "—"; + var current = !string.IsNullOrEmpty(book.Current) ? book.Current : "—"; + + Console.WriteLine( + $" {book.Prefix,-45} {book.Title,-40} {current,8} (current) [{min} .. {max}] {versions.Count} versions" + ); + } + } + + var totalBooks = conf.Contents.SelectMany(c => c.Sections).Count(); + Console.WriteLine(); + Console.WriteLine($"Total: {totalBooks} books across {conf.Contents.Count} categories"); + return 0; + } +} diff --git a/src/tooling/docs-migrate/Program.cs b/src/tooling/docs-migrate/Program.cs new file mode 100644 index 0000000000..47b7fe8398 --- /dev/null +++ b/src/tooling/docs-migrate/Program.cs @@ -0,0 +1,22 @@ +// 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 Documentation.Migrate; +using Microsoft.Extensions.Hosting; +using Nullean.Argh.Hosting; + +var builder = Host.CreateApplicationBuilder(args); + +builder.Services.AddArgh(args, app => +{ + _ = app.UseCliDescription("docs-migrate — convert Elastic legacy AsciiDoc books to docs-builder Markdown."); + _ = app.Map(); + _ = app.Map(); + _ = app.Map(); + _ = app.Map(); + _ = app.Map(); +}); + +using var host = builder.Build(); +await host.RunAsync(); diff --git a/src/tooling/docs-migrate/ServeCommand.cs b/src/tooling/docs-migrate/ServeCommand.cs new file mode 100644 index 0000000000..ca511d075c --- /dev/null +++ b/src/tooling/docs-migrate/ServeCommand.cs @@ -0,0 +1,37 @@ +// 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 ProcNet; + +namespace Documentation.Migrate; + +internal sealed class ServeCommand +{ + /// Serve the converted output using docs-builder. + /// Port to serve on (default 3000) + /// Cancellation token + public async Task Serve(int port = 3001, CancellationToken ct = default) + { + var outputDir = Path.Combine(Directory.GetCurrentDirectory(), ".artifacts", "migrated"); + + if (!Directory.Exists(outputDir)) + { + Console.Error.WriteLine($"Output directory not found at {outputDir}. Run 'docs-migrate convert' first."); + return 1; + } + + string[] args = ["run", "--project", "src/tooling/docs-builder", "--", "serve", "--path", outputDir, "--port", $"{port}", "--no-hud"]; + Console.WriteLine($"dotnet {string.Join(' ', args)}"); + + var arguments = new ExecArguments("dotnet", args); + try + { + return await Proc.ExecAsync(arguments, ct); + } + catch (OperationCanceledException) + { + return 0; + } + } +} diff --git a/src/tooling/docs-migrate/SharedOptions.cs b/src/tooling/docs-migrate/SharedOptions.cs new file mode 100644 index 0000000000..c2b046d8a4 --- /dev/null +++ b/src/tooling/docs-migrate/SharedOptions.cs @@ -0,0 +1,151 @@ +// 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 System.Text.Json; +using Elastic.LegacyDocs.Migration; + +namespace Documentation.Migrate; + +internal sealed record FilterOptions(int Majors = 1, bool All = false, int? MinVersion = null, string? Book = null, int? Minors = null); + +internal static class SharedOptions +{ + private const string CloneOptionsFile = ".clone-options.json"; + + private static readonly JsonSerializerOptions JsonOptions = new() + { + WriteIndented = true, + PropertyNamingPolicy = JsonNamingPolicy.CamelCase + }; + + public static readonly DirectoryInfo DefaultWorkDir = ResolveDefaultWorkDir(); + + public static string ResolveWorkDir(string? workDir) => + workDir ?? DefaultWorkDir.FullName; + + private static DirectoryInfo ResolveDefaultWorkDir() + { + var localAppData = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData); + // Docker/CI containers often have no XDG_DATA_HOME or HOME set, causing + // LocalApplicationData to return "". Fall back to the system temp directory. + if (string.IsNullOrEmpty(localAppData)) + localAppData = Path.GetTempPath(); + return new DirectoryInfo(Path.Join(localAppData, "elastic", "docs-migrate")); + } + + public static async Task LoadConfAsync(string workDir, CancellationToken ct) + { + var confPath = Path.Combine(workDir, "conf.yaml"); + if (!File.Exists(confPath)) + throw new FileNotFoundException($"conf.yaml not found at {confPath}. Run 'docs-migrate init' first."); + + var yaml = await File.ReadAllTextAsync(confPath, ct); + var conf = LegacyConfParser.Parse(yaml); + + if (!conf.Repos.ContainsKey("docs")) + conf.Repos["docs"] = "https://github.com/elastic/docs.git"; + + return conf; + } + + public static void SaveFilterOptions(string workDir, FilterOptions opts) + { + var path = Path.Combine(workDir, CloneOptionsFile); + File.WriteAllText(path, JsonSerializer.Serialize(opts, JsonOptions)); + } + + public static FilterOptions LoadFilterOptions(string workDir) + { + var path = Path.Combine(workDir, CloneOptionsFile); + if (!File.Exists(path)) + return new FilterOptions(); + + var json = File.ReadAllText(path); + return JsonSerializer.Deserialize(json, JsonOptions) ?? new FilterOptions(); + } + + public static FilterOptions ResolveFilterOptions( + string workDir, int? majors, bool? all, int? minVersion, string? book, int? minors) + { + var saved = LoadFilterOptions(workDir); + + return new FilterOptions( + Majors: majors ?? saved.Majors, + All: all ?? saved.All, + MinVersion: minVersion ?? saved.MinVersion, + Book: book, + Minors: minors ?? saved.Minors + ); + } + + public static List FilterBooks(LegacyConf conf, string? bookFilter) => + conf.Contents + .SelectMany(c => c.Sections) + .Where(b => bookFilter is null || b.Prefix.StartsWith(bookFilter, StringComparison.OrdinalIgnoreCase)) + .ToList(); + + public static List FilterVersions(LegacyBook book, int majors, bool all, int? minVersion, int? minors = null) + { + var branches = book.Branches.ToList(); + + if (minVersion is not null) + branches = branches + .Where(b => TryParseMajorMinor(b.VersionLabel) is var p && p.HasValue && p.Value.Major >= minVersion) + .ToList(); + + if (all) + return EnsureCurrent(book, SortDescending(branches)); + + var selected = new HashSet(StringComparer.OrdinalIgnoreCase); + + var grouped = branches + .Select(b => (Branch: b, Parsed: TryParseMajorMinor(b.VersionLabel))) + .Where(x => x.Parsed.HasValue) + .GroupBy(x => x.Parsed!.Value.Major) + .OrderByDescending(g => g.Key) + .Take(majors); + + foreach (var group in grouped) + { + var minorsSorted = group.OrderByDescending(x => x.Parsed!.Value.Minor); + var limited = minors is not null ? minorsSorted.Take(minors.Value) : minorsSorted; + foreach (var (branch, _) in limited) + _ = selected.Add(branch.VersionLabel); + } + + var result = branches.Where(b => selected.Contains(b.VersionLabel)).ToList(); + return EnsureCurrent(book, SortDescending(result)); + } + + private static List EnsureCurrent(LegacyBook book, List versions) + { + if (string.IsNullOrEmpty(book.Current)) + return versions; + + if (versions.Any(v => v.VersionLabel == book.Current)) + return versions; + + var currentBranch = book.Branches.FirstOrDefault(b => b.VersionLabel == book.Current) + ?? new BranchRef(book.Current); + + versions.Insert(0, currentBranch); + return versions; + } + + private static List SortDescending(IEnumerable branches) => + branches + .Select(b => (Branch: b, Parsed: TryParseMajorMinor(b.VersionLabel))) + .OrderByDescending(x => x.Parsed?.Major ?? 0) + .ThenByDescending(x => x.Parsed?.Minor ?? 0) + .Select(x => x.Branch) + .ToList(); + + private static (int Major, int Minor)? TryParseMajorMinor(string version) + { + var parts = version.Split('.'); + if (parts.Length >= 2 && int.TryParse(parts[0], out var major) && int.TryParse(parts[1], out var minor)) + return (major, minor); + return null; + } +} diff --git a/src/tooling/docs-migrate/docs-migrate.csproj b/src/tooling/docs-migrate/docs-migrate.csproj new file mode 100644 index 0000000000..0650fdf4a8 --- /dev/null +++ b/src/tooling/docs-migrate/docs-migrate.csproj @@ -0,0 +1,24 @@ + + + + net10.0 + Exe + docs-migrate + Documentation.Migrate + enable + enable + + + + + + + + + + + + + + + diff --git a/tests/Elastic.LegacyDocs.Migration.Tests/Elastic.LegacyDocs.Migration.Tests.csproj b/tests/Elastic.LegacyDocs.Migration.Tests/Elastic.LegacyDocs.Migration.Tests.csproj new file mode 100644 index 0000000000..296e63cc88 --- /dev/null +++ b/tests/Elastic.LegacyDocs.Migration.Tests/Elastic.LegacyDocs.Migration.Tests.csproj @@ -0,0 +1,11 @@ + + + + net10.0 + + + + + + + diff --git a/tests/Elastic.LegacyDocs.Migration.Tests/EmitterTests.cs b/tests/Elastic.LegacyDocs.Migration.Tests/EmitterTests.cs new file mode 100644 index 0000000000..66ba5804b4 --- /dev/null +++ b/tests/Elastic.LegacyDocs.Migration.Tests/EmitterTests.cs @@ -0,0 +1,307 @@ +// 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 AwesomeAssertions; +using Elastic.LegacyDocs.Migration.Asciidoc; + +namespace Elastic.LegacyDocs.Migration.Tests; + +public class EmitterTests +{ + private static string Emit(string asciidoc, Dictionary? attrs = null) + { + var parser = new AsciidocParser(new AsciidocParserOptions { Attributes = attrs ?? [] }); + var doc = parser.Parse(asciidoc, ""); + return new MarkdownEmitter(new MarkdownEmitterOptions()).Emit(doc); + } + + // ── Step 4: attribute emission ──────────────────────────────────────────── + + [Fact] + public void UndefinedAttribute_EmittedAsSingleBraces_NotDouble() + { + var md = Emit("= T\n\n{undefined-attr} text\n"); + // Should be {undefined-attr}, NOT {{undefined-attr}} + md.Should().Contain("{undefined-attr}"); + md.Should().NotContain("{{undefined-attr}}"); + } + + [Fact] + public void ProductNameAttribute_EmittedAsDoubleBraces() + { + // {es} is a ProductNames key — should remain {{es}} for docs-builder substitution + var md = Emit("= T\n\n{es} cluster\n"); + md.Should().Contain("{{es}}"); + } + + [Fact] + public void DefinedAttribute_IsSubstituted_NotEmittedAsRef() + { + var md = Emit("= T\n\n:myattr: hello world\n\n{myattr}\n"); + md.Should().Contain("hello world"); + md.Should().NotContain("{myattr}"); + } + + // ── Step 5: callout list in output ─────────────────────────────────────── + + [Fact] + public void CodeBlock_WithCallouts_EmitsOrderedList() + { + var md = Emit("= T\n\n[source,python]\n----\nfoo() # <1>\nbar() # <2>\n----\n<1> Call foo\n<2> Call bar\n"); + md.Should().Contain("1. Call foo"); + md.Should().Contain("2. Call bar"); + } + + // ── Step 7: xref with > in text ────────────────────────────────────────── + + [Fact] + public void CrossRef_Simple_IsEmittedCorrectly() + { + var md = Emit("= T\n\nSee <>.\n"); + md.Should().NotContain("<<"); + md.Should().Contain("[my-anchor](#my-anchor)"); + } + + [Fact] + public void CrossRef_WithText_IsEmittedCorrectly() + { + var md = Emit("= T\n\nSee <>.\n"); + md.Should().NotContain("<<"); + md.Should().Contain("[Click here](#my-anchor)"); + } + + [Fact] + public void CrossRef_WithBacktickInText_IsEmittedCorrectly() + { + var md = Emit("= T\n\nfilters like <> to normalise.\n"); + md.Should().NotContain("<<"); + md.Should().Contain("[`lowercase`]"); + } + + [Fact] + public void CrossRef_InMultiLineParagraph_WithBacktick_IsEmittedCorrectly() + { + // Multi-line paragraph where xref with backtick in text is on one line + var asciidoc = "= T\n\nIt can be combined\nwith token filters like <> to\nnormalise the analysed terms.\n"; + var md = Emit(asciidoc); + md.Should().NotContain("<<"); + md.Should().Contain("[`lowercase`]"); + } + + [Fact] + public void CrossRef_AfterDLItemWithBlankLineSeparator_IsEmittedCorrectly() + { + // Description list where term is followed by blank line, then description paragraph containing xref + var asciidoc = "= T\n\n<>::\n\nIt can be combined with token filters like <> to\nnormalise the analysed terms.\n"; + var md = Emit(asciidoc); + md.Should().NotContain("<<"); + md.Should().Contain("[`lowercase`]"); + } + + [Fact] + public void CrossRef_InMultiLineParagraph_WithCurlyQuotes_IsEmittedCorrectly() + { + // Paragraph using AsciiDoc curly-quotes ``...'' before the xref line + var asciidoc = "= T\n\nIn order to use scrolling, the initial search request should specify the\n`scroll` parameter in the query string, which tells Elasticsearch how long it\nshould keep the ``search context'' alive (see <>), eg `?scroll=1m`.\n"; + var md = Emit(asciidoc); + md.Should().NotContain("<<"); + md.Should().Contain("[scroll-search-context]"); + } + + [Fact] + public void CrossRef_InOrderedListItem_WithBacktickText_IsEmittedCorrectly() + { + // Ordered list item with xref that has backtick-wrapped text (space after comma) + var md = Emit("= T\n\n. Define a runtime field using the <> queries.\n"); + md.Should().NotContain("<<"); + md.Should().Contain("[`term`]"); + } + + [Fact] + public void CrossRef_InOrderedListItem_WithPrecedingCode_IsEmittedCorrectly() + { + // Ordered list item where a `code` span precedes the xref + var md = Emit("= T\n\n. A type of `lookup` that uses the <> query.\n"); + md.Should().NotContain("<<"); + md.Should().Contain("[`term`]"); + } + + [Fact] + public void CrossRef_WithAsteriskInLinkText_IsEmittedCorrectly() + { + // Bold marker * between text and xref text must not consume the << + var md = Emit("= T\n\nSemantic*text field can be target of <>.\n"); + md.Should().NotContain("<<"); + md.Should().Contain("[copy*to fields]"); + } + + [Fact] + public void CrossRef_WithAngleBracketInText_IsEmittedCorrectly() + { + // < b>> — text contains a literal > + var md = Emit("= T\n\nSee < 7.0>>\n"); + md.Should().Contain("[version > 7.0]"); + } + + // ── Passthrough inline (constrained +..+) ───────────────────────────────── + + [Fact] + public void PassthroughInline_BasicCase_EmitsCodeSpan() + { + var md = Emit("= T\n\nDefaults to +max(1, 10)+.\n"); + md.Should().Contain("`max(1, 10)`"); + } + + [Fact] + public void PassthroughInline_VersionSuffix_NotTreatedAsPassthrough() + { + // "8.0+" is a version indicator, NOT a passthrough delimiter — must not swallow following text + var md = Emit("= T\n\nES 8.0+ does not (see <>). ES 8.0+ returns error.\n"); + md.Should().NotContain("<>"); + md.Should().Contain("[removal-of-types](#removal-of-types)"); + md.Should().Contain("8.0+"); + } + + // ── Verbatim include resolution (Step 6) ────────────────────────────────── + + [Fact] + public void VerbatimBlock_StandardTaggedInclude_IsResolved() + { + // include::path[tag=name] inside a code block should be expanded + var fileSystem = new Dictionary + { + ["/specs/string.csv-spec"] = "# tag::my-example[]\nrow1\nrow2\n# end::my-example[]\n" + }; + var parser = new AsciidocParser(new AsciidocParserOptions + { + Attributes = new Dictionary { ["specs"] = "/specs" }, + FileReader = p => fileSystem.TryGetValue(p, out var c) ? c : null + }); + var doc = parser.Parse("= T\n\n[source,esql]\n----\ninclude::{specs}/string.csv-spec[tag=my-example]\n----\n", ""); + var md = new MarkdownEmitter(new MarkdownEmitterOptions()).Emit(doc); + md.Should().Contain("row1"); + md.Should().Contain("row2"); + md.Should().NotContain("include::"); + } + + [Fact] + public void VerbatimBlock_IfevalConditionMarkers_AreStripped() + { + // ifeval/endif markers inside verbatim blocks should be stripped; content is kept + var adoc = "= T\n\n----\n{\nifeval::[\"{trust}\"==\"api-key\"]\n \"credentials\": \"secret\",\nendif::[]\n}\n----\n"; + var md = Emit(adoc); + md.Should().NotContain("ifeval::"); + md.Should().NotContain("endif::"); + md.Should().Contain("\"credentials\": \"secret\","); + } + + // ── Conditional blocks (ifeval) ──────────────────────────────────────────── + + [Fact] + public void Ifeval_FalseCondition_ExcludesContent() + { + // ifeval::[expr] — condition false, block content must be excluded + var adoc = "= T\n\nBefore.\n\nifeval::[\"{stack}\"==\"something-else\"]\nHidden text.\nendif::[]\n\nAfter.\n"; + var md = Emit(adoc, new Dictionary { ["stack"] = "elastic" }); + md.Should().Contain("Before."); + md.Should().Contain("After."); + md.Should().NotContain("Hidden text."); + } + + [Fact] + public void Ifeval_TrueCondition_IncludesContent() + { + // ifeval::[expr] — condition true, block content must be included + var adoc = "= T\n\nBefore.\n\nifeval::[\"{stack}\"==\"elastic\"]\nVisible text.\nendif::[]\n\nAfter.\n"; + var md = Emit(adoc, new Dictionary { ["stack"] = "elastic" }); + md.Should().Contain("Before."); + md.Should().Contain("After."); + md.Should().Contain("Visible text."); + } + + [Fact] + public void CodeBlock_TrailingSpaceOnClosingDelimiter_StillClosesBlock() + { + // Source files sometimes have `---- ` (with trailing space) as the closing delimiter. + // The lexer must treat this as a valid closing delimiter. + var adoc = "= T\n\n[source,json]\n----\n{\"hello\":\"world\"}\n---- \n\n==== Next section\n"; + var md = Emit(adoc); + md.Should().Contain("```json"); + md.Should().Contain(/*lang=json,strict*/ "{\"hello\":\"world\"}"); + // If the block closes, Next section becomes a real heading; if not, it's inside code block + md.Should().NotContain("==== Next section"); // raw AsciiDoc must not appear + } + + [Fact] + public void Ifeval_ContentAfterBlock_NotLeaked_WhenConditionFalse() + { + // Regression: ConditionalProcessor was not pushing to the stack for ifeval, + // causing all content after the ifeval block to leak through unconditionally. + var adoc = "= T\n\nifeval::[\"{trust}\"==\"api-key\"]\nSecret\nendif::[]\n\nPublic paragraph.\n"; + var md = Emit(adoc, new Dictionary { ["trust"] = "cert" }); + md.Should().NotContain("Secret"); + md.Should().Contain("Public paragraph."); + } + + // ── Long dash delimiter (50 dashes) ────────────────────────────────────── + + [Fact] + public void CodeBlock_LongDashDelimiter_IsTreatedAsCodeFence() + { + // Watcher 2.4 docs use 50-dash lines as code block delimiters (valid AsciiDoc: 4+ dashes). + var adoc = "= T\n\n[source,js]\n--------------------------------------------------\n\"input\": {}\n--------------------------------------------------\n\nNormal paragraph.\n"; + var md = Emit(adoc); + md.Should().Contain("```"); + md.Should().Contain("\"input\": {}"); + md.Should().NotContain("--------------------------------------------------"); + md.Should().Contain("Normal paragraph."); + } + + [Fact] + public void CodeBlock_LongDashDelimiter_InNestedSection_IsTreatedAsCodeFence() + { + // Watcher 2.4 docs: code blocks with 50-dash delimiters inside nested sections (== > === > ====). + var adoc = string.Join("\n", + "= Doc", + "", + "[[top]]", + "== Level1", + "", + "[[sec2]]", + "=== Level2", + "", + "[[sec3]]", + "==== Level3", + "", + "Some text:", + "", + "[source,js]", + "--------------------------------------------------", + "\"key\": \"value\"", + "--------------------------------------------------", + "", + "Normal paragraph.", + ""); + var md = Emit(adoc); + md.Should().Contain("```"); + md.Should().Contain("\"key\": \"value\""); + md.Should().NotContain("--------------------------------------------------"); + md.Should().Contain("Normal paragraph."); + } + + // ── Open block delimiter trailing whitespace ─────────────────────────────── + + [Fact] + public void OpenBlock_TrailingSpaceOnOpeningDelimiter_StillClosesBlock() + { + // Source files can have `-- ` (trailing spaces) as the opening `--` delimiter. + // The parser must not leave the block unclosed because openingDelim = "-- " ≠ "--". + var adoc = "= T\n\n.Requirements\n[sidebar]\n-- \n* req one\n--\n\nNormal paragraph.\n"; + var md = Emit(adoc); + md.Should().Contain("req one"); + md.Should().Contain("Normal paragraph."); + // The trailing `--` must NOT appear raw in the output + md.Should().NotContain("\n--\n"); + } +} diff --git a/tests/Elastic.LegacyDocs.Migration.Tests/LexerTests.cs b/tests/Elastic.LegacyDocs.Migration.Tests/LexerTests.cs new file mode 100644 index 0000000000..31ce8d9795 --- /dev/null +++ b/tests/Elastic.LegacyDocs.Migration.Tests/LexerTests.cs @@ -0,0 +1,47 @@ +// 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 AwesomeAssertions; +using Elastic.LegacyDocs.Migration.Asciidoc; + +namespace Elastic.LegacyDocs.Migration.Tests; + +public class LexerTests +{ + [Fact] + public void OpenBlock_DashDash_IsNotVerbatim() + { + var tokens = AsciidocLexer.Tokenize("--\nSome content\n--"); + var delimiters = tokens.Where(t => t.Type == TokenType.BlockDelimiter).ToList(); + + delimiters.Should().HaveCount(2); + // Both are regular (non-verbatim) block delimiters + var text = tokens.Where(t => t.Type == TokenType.Text).ToList(); + text.Should().HaveCount(1); + text[0].Raw.Should().Be("Some content"); + } + + [Fact] + public void VerbatimBlock_FourDashes_IsVerbatim() + { + var tokens = AsciidocLexer.Tokenize("----\n<1> callout marker\n----"); + var text = tokens.Where(t => t.Type == TokenType.Text).ToList(); + + // Content inside ---- block is raw text (verbatim) + text.Should().HaveCount(1); + text[0].Raw.Should().Be("<1> callout marker"); + } + + [Fact] + public void ClosingDelimiter_RequiresExactLength() + { + // A longer closing delimiter should NOT close the block + var content = "----\nfoo\n--------\nbar\n----"; + var tokens = AsciidocLexer.Tokenize(content); + var textTokens = tokens.Where(t => t.Type == TokenType.Text).ToList(); + + // "foo", "--------" (not a valid close), and "bar" should all be Text inside the block + textTokens.Should().HaveCount(3); + } +} diff --git a/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs b/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs new file mode 100644 index 0000000000..66831c57db --- /dev/null +++ b/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs @@ -0,0 +1,373 @@ +// 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 AwesomeAssertions; +using Elastic.LegacyDocs.Migration.Asciidoc; +using Elastic.LegacyDocs.Migration.Asciidoc.Ast; + +namespace Elastic.LegacyDocs.Migration.Tests; + +public class ParserTests +{ + /// + /// Parse without a section title — children go directly into doc.Children. + /// Note: in this codebase, `== Title` (Level 1) sets doc.Title and makes subsequent + /// content direct doc.Children; `= Title` (Level 0) creates a Level-0 SectionNode wrapper. + /// + private static AsciidocDocument Parse(string content, Dictionary? attrs = null) => + new AsciidocParser(new AsciidocParserOptions { Attributes = attrs ?? [] }) + .Parse(content, ""); + + /// Recursively finds the first node of type T in the document tree. + private static T? FindFirst(IEnumerable nodes) where T : class + { + foreach (var node in nodes) + { + if (node is T found) + return found; + if (node is SectionNode s) + { var r = FindFirst(s.Children); if (r is not null) return r; } + if (node is OpenBlockNode o) + { var r = FindFirst(o.Children); if (r is not null) return r; } + if (node is AdmonitionNode a) + { var r = FindFirst(a.Children); if (r is not null) return r; } + } + return null; + } + + private static T? FindFirst(AsciidocDocument doc) where T : class => + FindFirst(doc.Children); + + // ── Step 1: -- open blocks ──────────────────────────────────────────────── + + [Fact] + public void OpenBlock_DashDash_ProducesOpenBlockNode() + { + // No section title — direct doc.Children + var doc = Parse("--\nSome content\n--\n"); + var block = FindFirst(doc); + block.Should().NotBeNull(); + block.Children.Should().HaveCountGreaterThan(0); + } + + [Fact] + public void OpenBlock_NoteStyle_ProducesAdmonitionNode() + { + var doc = Parse("[NOTE]\n--\nNote content here.\n--\n"); + var admonition = FindFirst(doc); + admonition.Should().NotBeNull(); + admonition.Type.Should().Be(AdmonitionType.Note); + } + + [Fact] + public void VerbatimBlock_FourDashes_ProducesCodeBlockNode() + { + var doc = Parse("[source,yaml]\n----\nfoo: bar\n----\n"); + var code = FindFirst(doc); + code.Should().NotBeNull(); + code.Source.Should().Be("foo: bar"); + code.Language.Should().Be("yaml"); + } + + [Fact] + public void OpenBlock_And_VerbatimBlock_AreDifferentNodeTypes() + { + // -- open block should NOT produce a CodeBlockNode + var openDoc = Parse("--\ncontent\n--\n"); + FindFirst(openDoc).Should().BeNull(); + FindFirst(openDoc).Should().NotBeNull(); + + // ---- verbatim block should NOT produce an OpenBlockNode + var codeDoc = Parse("----\ncontent\n----\n"); + FindFirst(codeDoc).Should().BeNull(); + FindFirst(codeDoc).Should().NotBeNull(); + } + + // ── Step 3: Attribute resolution ───────────────────────────────────────── + + [Fact] + public void SetAttribute_EagerlyExpandsValues() + { + // :branch: 8.19 + // :ref: https://example.com/{branch} + // After eager expansion, {ref} should be the fully resolved URL + var content = ":branch: 8.19\n:ref: https://example.com/{branch}\n\nSee {ref}/setup.html\n"; + var doc = Parse(content); + doc.Attributes.TryGetValue("ref", out var refValue).Should().BeTrue(); + refValue.Should().Be("https://example.com/8.19"); + } + + [Fact] + public void SetAttribute_ProductNameKeys_AreNotStored() + { + // ProductNames keys should stay unresolved so the emitter emits {{es}} not "Elasticsearch" + var content = ":es: Elasticsearch Override\n\n{es}\n"; + var doc = Parse(content); + // The parser skips storing ProductNames keys, so {es} remains unresolved → AttributeRefInline + var para = doc.Children.OfType().FirstOrDefault(); + para.Should().NotBeNull(); + var attrRef = para.Inlines.OfType().FirstOrDefault(); + attrRef.Should().NotBeNull(); + attrRef.Name.Should().Be("es"); + } + + [Fact] + public void AttributeResolution_SeedAttributes_AreAvailable() + { + var attrs = new Dictionary + { + ["branch"] = "8.19", + ["docs-root"] = "/work/docs-repo" + }; + var content = "Branch is {branch}\n"; + var parser = new AsciidocParser(new AsciidocParserOptions { Attributes = attrs }); + var doc = parser.Parse(content, ""); + var para = doc.Children.OfType().FirstOrDefault(); + var text = para?.Inlines.OfType().FirstOrDefault(); + text?.Text.Should().Contain("8.19"); + } + + // ── Step 5: Callouts ───────────────────────────────────────────────────── + + [Fact] + public void CodeBlock_Callouts_AreCollected() + { + var content = "[source,java]\n----\nfoo(); // <1>\nbar(); // <2>\n----\n<1> First callout\n<2> Second callout\n"; + var doc = Parse(content); + var code = FindFirst(doc); + code.Should().NotBeNull(); + code.Callouts.Should().HaveCount(2); + code.Callouts[0].Should().Be("First callout"); + code.Callouts[1].Should().Be("Second callout"); + } + + [Fact] + public void CodeBlock_CalloutsOutOfOrder_AreNormalized() + { + // Callout markers appear in document order by number + var content = "----\nfoo <2>\nbar <1>\n----\n<1> Bar annotation\n<2> Foo annotation\n"; + var doc = Parse(content); + var code = FindFirst(doc); + code.Should().NotBeNull(); + code.Callouts.Should().HaveCount(2); + code.Callouts[0].Should().Be("Bar annotation"); + code.Callouts[1].Should().Be("Foo annotation"); + } + + // ── Step 7: Multi-line admonitions ─────────────────────────────────────── + + [Fact] + public void AdmonitionParagraph_MultiLine_CollectsAllContent() + { + var content = "NOTE: First line\nSecond line\nThird line\n\nNext paragraph\n"; + var doc = Parse(content); + var admonition = doc.Children.OfType().FirstOrDefault(); + admonition.Should().NotBeNull(); + // All three lines should be inside the admonition's paragraph + var para = admonition.Children.OfType().FirstOrDefault(); + para.Should().NotBeNull(); + var allText = string.Join("", para.Inlines.Select(i => i switch + { + TextInline t => t.Text, + _ => "" + })); + allText.Should().Contain("First line"); + allText.Should().Contain("Second line"); + allText.Should().Contain("Third line"); + } + + // ── Lexer: trailing whitespace on delimiter ─────────────────────────────── + + [Fact] + public void Lexer_VerbatimBlock_TrailingSpaceOnClosingDelimiter_ClosesBlock() + { + var input = "[source,json]\n----\n{\"k\":\"v\"}\n---- \n\nsome text\n"; + var tokens = AsciidocLexer.Tokenize(input); + // The `---- ` line must be a closing BlockDelimiter, not Text + var textTokens = tokens.Where(t => t.Type == TokenType.Text).Select(t => t.Raw).ToList(); + textTokens.Should().NotContain("---- "); // closing delim must NOT appear as Text + // The JSON content should appear as Text + textTokens.Should().Contain(/*lang=json,strict*/ "{\"k\":\"v\"}"); + } + + // ── Step 2: include:: dispatch in ParseBlock ────────────────────────────── + + [Fact] + public void IncludeDirective_InsideDelimitedBlock_IsResolvedWhenFileExists() + { + var files = new Dictionary + { + ["/base/inner.adoc"] = "included content" + }; + var content = "[NOTE]\n====\ninclude::inner.adoc[]\n====\n"; + var parser = new AsciidocParser(new AsciidocParserOptions + { + FileReader = path => files.TryGetValue(path, out var c) ? c : null + }); + var doc = parser.Parse(content, "/base"); + var admonition = doc.Children.OfType().FirstOrDefault(); + admonition.Should().NotBeNull(); + admonition.Children.Should().HaveCountGreaterThan(0); + } + + [Fact] + public void Parse_file_starting_with_level1_section_promotes_it_to_doc_title() + { + // When a file starts with a == section (Level 1 in AST), Parse() treats it as doc.Title. + // The === subsections become top-level doc.Children (not nested under a SectionNode). + // ProcessInclude uses a different loop that does NOT promote == to doc.Title — it creates + // a SectionNode — so included files behave correctly during chunking. + const string source = """ + == The search API + + Some intro text. + + [discrete] + [[run-an-es-search]] + === Run a search + + Run search content. + + [discrete] + [[common-search-options]] + === Common search options + + Common options content. + """; + + var parser = new AsciidocParser(new AsciidocParserOptions()); + var doc = parser.Parse(source, "."); + + // The == section becomes the document title, not a SectionNode child + doc.Title.Should().Be("The search API"); + + // The === subsections appear at the top level (they're children of the document, not the == section) + var sectionChildren = doc.Children.OfType().ToList(); + sectionChildren.Should().HaveCount(2); + sectionChildren[0].Level.Should().Be(2); + sectionChildren[0].Title.Should().Be("Run a search"); + sectionChildren[1].Level.Should().Be(2); + sectionChildren[1].Title.Should().Be("Common search options"); + } + + [Fact] + public void ChunkLevel2_keeps_level3_within_level2_page() + { + const string source = """ + = Book Title + + [[search-your-data]] + == The search API + + Some intro text. + + [discrete] + [[run-an-es-search]] + === Run a search + + Run search content. + + [discrete] + [[common-search-options]] + === Common search options + + Common options content. + """; + + var parser = new AsciidocParser(new AsciidocParserOptions()); + var doc = parser.Parse(source, "."); + + var emitter = new MarkdownEmitter(new MarkdownEmitterOptions { BookPrefix = "test", Version = "1.0" }); + // chunkLevel=1 matches conf.yaml chunk:1 — extracts == (Level 1) sections, keeps === within them + var pages = PageChunker.Chunk(doc, chunkLevel: 1, emitter); + + // Should produce: index + 1 page for "The search API" + pages.Should().HaveCount(2); + var searchApiPage = pages.First(p => p.Slug == "search-your-data"); + searchApiPage.MarkdownContent.Should().Contain("Run a search"); + searchApiPage.MarkdownContent.Should().Contain("Common search options"); + } + + [Fact] + public void IncludeChain_EachIncludedFile_BecomesASeparatePage() + { + // Mirrors the elastic.co search-your-data structure: + // - index.adoc includes search-your-data.adoc (= level, chunk boundary) + // - search-your-data.adoc has inline discrete === section (stays in its page) + // - search-your-data.adoc includes search-api.adoc (== level, chunk boundary) + // - search-api.adoc includes sort-results.adoc (=== level, still chunk boundary) + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Elasticsearch Guide + + include::search-your-data.adoc[] + """, + ["/base/search-your-data.adoc"] = """ + [[search-with-elasticsearch]] + = Search your data + + Intro paragraph. + + [discrete] + === Run a search + + Inline section content. + + include::search-api.adoc[] + """, + ["/base/search-api.adoc"] = """ + [[search-your-data-api]] + == The search API + + API intro. + + [discrete] + === API Run a search + + Inline API section. + + include::sort-results.adoc[] + """, + ["/base/sort-results.adoc"] = """ + [[sort-results]] + === Sort search results + + Sort content. + """, + }; + + var parser = new AsciidocParser(new AsciidocParserOptions + { + FileReader = path => files.TryGetValue(path, out var c) ? c : null + }); + var doc = parser.Parse(files["/base/index.adoc"], "/base"); + var emitter = new MarkdownEmitter(new MarkdownEmitterOptions { BookPrefix = "test", Version = "1.0" }); + var pages = PageChunker.Chunk(doc, chunkLevel: 1, emitter); + + var slugs = pages.Select(p => p.Slug).ToList(); + + // index (from = Elasticsearch Guide root) + slugs.Should().Contain("index"); + + // = Search your data → its own page + slugs.Should().Contain("search-with-elasticsearch"); + var searchYourData = pages.First(p => p.Slug == "search-with-elasticsearch"); + searchYourData.MarkdownContent.Should().Contain("Intro paragraph"); + searchYourData.MarkdownContent.Should().Contain("Run a search"); // inline section stays + searchYourData.MarkdownContent.Should().NotContain("The search API"); // NOT merged into this page + + // == The search API → its own page + slugs.Should().Contain("search-your-data-api"); + var theSearchApi = pages.First(p => p.Slug == "search-your-data-api"); + theSearchApi.MarkdownContent.Should().Contain("API intro"); + theSearchApi.MarkdownContent.Should().Contain("API Run a search"); // inline stays + theSearchApi.MarkdownContent.Should().NotContain("Sort search results"); // NOT merged + + // === Sort search results → its own page (included file, even though === level) + slugs.Should().Contain("sort-results"); + var sortResults = pages.First(p => p.Slug == "sort-results"); + sortResults.MarkdownContent.Should().Contain("Sort content"); + } +} From 269b660a795dda482d9f041108e309e5444647ac Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Fri, 14 Aug 2026 12:36:46 +0200 Subject: [PATCH 09/11] Add navigation islands: guide-nav toc chunking with IsDiscrete, NestSectionsByLevel, HeadingLevelBase (#3833) - PageChunker: tree-shaped PageOutput with child pages, slug dedup, IsDiscrete support, AutoId replacing Slugify.Core - AsciidocParser: IsDiscrete flag for [discrete]/[float] sections; NestSectionsByLevel post-processes flat include results - MarkdownEmitter: HeadingLevelBase rebases heading levels per page root; LF-only newlines - YamlWriter: Island and Children on TocEntry; nested toc entries with island: true - ConvertCommand: Island=true per version toc entry; WritePages recursion into child pages; navigation_title frontmatter; island: true per book in docset.yml - FeatureFlags: GuideNavEnabled property - Paths/GitResolveFileSystem: DEBUG escape hatch for .slnx root; .artifacts in allowed hidden folders - docs-migrate ServeCommand: use Paths.WorkingDirectoryRoot instead of CWD - docs-migrate.csproj: add Elastic.Documentation.Tooling project reference - docs-builder ServeCommand: remove unused System.IO.Abstractions using - ChunkerTests: 391-line test suite for new chunker behaviour Co-authored-by: Claude Sonnet 4.6 --- .../Builder/FeatureFlags.cs | 12 +- .../FileSystems/GitResolveFileSystem.cs | 13 +- src/Elastic.Documentation.Tooling/Paths.cs | 10 + .../Asciidoc/AsciidocParser.cs | 78 +++- .../Asciidoc/Ast/SectionNode.cs | 9 +- .../Asciidoc/MarkdownEmitter.cs | 16 +- .../Asciidoc/PageChunker.cs | 358 ++++++++++------ .../YamlWriter.cs | 30 +- .../docs-builder/Commands/ServeCommand.cs | 1 - src/tooling/docs-migrate/ConvertCommand.cs | 20 +- src/tooling/docs-migrate/ServeCommand.cs | 8 +- src/tooling/docs-migrate/docs-migrate.csproj | 1 + .../ChunkerTests.cs | 391 ++++++++++++++++++ .../ParserTests.cs | 28 +- 14 files changed, 813 insertions(+), 162 deletions(-) create mode 100644 tests/Elastic.LegacyDocs.Migration.Tests/ChunkerTests.cs diff --git a/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs b/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs index ed7b7de9c8..0f74def7fc 100644 --- a/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs +++ b/src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs @@ -52,18 +52,18 @@ public bool DiagnosticsPanelEnabled set => _featureFlags["diagnostics-panel"] = value; } - public bool NavigationPreviewEnabled - { - get => IsEnabled("navigation-preview"); - set => _featureFlags["navigation-preview"] = value; - } - public bool GuideNavEnabled { get => IsEnabled("guide-nav"); set => _featureFlags["guide-nav"] = value; } + public bool NavigationPreviewEnabled + { + get => IsEnabled("navigation-preview"); + set => _featureFlags["navigation-preview"] = value; + } + private bool IsEnabled(string key) { var envKey = $"FEATURE_{key.ToUpperInvariant().Replace('-', '_')}"; diff --git a/src/Elastic.Documentation.Tooling/FileSystems/GitResolveFileSystem.cs b/src/Elastic.Documentation.Tooling/FileSystems/GitResolveFileSystem.cs index 4769ffdee9..23280e2ab9 100644 --- a/src/Elastic.Documentation.Tooling/FileSystems/GitResolveFileSystem.cs +++ b/src/Elastic.Documentation.Tooling/FileSystems/GitResolveFileSystem.cs @@ -45,6 +45,17 @@ private static ScopedFileSystemOptions BuildOptions( for (var i = 0; i < maxParents; i++) root = root.Parent ?? root; +#if DEBUG + // anchor may come from a ScopedFileSystem (e.g. DocsetScanFileSystem scoped to + // .artifacts/migrated) whose scope blocks upward traversal. Use the real filesystem + // to call FindGitRoot so the DEBUG .slnx escape hatch in that method can actually fire. + var realFs = new FileSystem(); + var realStart = realFs.DirectoryInfo.New(anchor.FullName); + var gitRoot = Configuration.Paths.FindGitRoot(realStart, maxParents: 20); + if (gitRoot is not null) + root = anchor.FileSystem.DirectoryInfo.New(gitRoot.FullName); +#endif + // ScopedFileSystem normalises scope roots via TrimEnd(separator). On Unix, "/" trimmed is "". // An empty scope root makes every path fail the IsWithinRoot check, so guard against it: // if the computed root IS the filesystem root, fall back to the anchor itself. @@ -64,7 +75,7 @@ private static ScopedFileSystemOptions BuildOptions( return new ScopedFileSystemOptions([.. roots]) { - AllowedHiddenFolderNames = new HashSet(StringComparer.OrdinalIgnoreCase) { ".git" }, + AllowedHiddenFolderNames = new HashSet(StringComparer.OrdinalIgnoreCase) { ".git", ".artifacts" }, AllowedHiddenFileNames = new HashSet(StringComparer.OrdinalIgnoreCase) { ".git" } }; } diff --git a/src/Elastic.Documentation.Tooling/Paths.cs b/src/Elastic.Documentation.Tooling/Paths.cs index fb3be94d69..2a19407cb6 100644 --- a/src/Elastic.Documentation.Tooling/Paths.cs +++ b/src/Elastic.Documentation.Tooling/Paths.cs @@ -72,7 +72,17 @@ public static class Paths return null; } if (depth >= maxParents) + { +#if DEBUG + // In DEBUG we keep walking so the acceptance check above can fire for a .git + // that has an adjacent .slnx (solution root). Cap at a sane depth to avoid + // walking the entire filesystem on pathological inputs. + if (depth > 20) + return null; +#else return null; +#endif + } depth++; directory = directory.Parent; } diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs index 2920809442..1b14a007a8 100644 --- a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/AsciidocParser.cs @@ -138,7 +138,7 @@ public AsciidocDocument Parse(string content, string basePath) } else { - var section = ParseSection(pendingId, pendingTitle); + var section = ParseSection(pendingId, pendingTitle, pendingBlockAttr); doc.Children.Add(section); pendingId = null; pendingTitle = null; @@ -177,12 +177,14 @@ public AsciidocDocument Parse(string content, string basePath) private Token Current => _tokens[_pos]; - private SectionNode ParseSection(string? id, string? title) + private SectionNode ParseSection(string? id, string? title, TokenMetadata? blockAttr = null) { var token = Current; var level = token.Metadata!.Level!.Value; var sectionTitle = SubstituteAttributes(title ?? token.Metadata.Title!); var sectionId = id ?? ExtractInlineAnchor(sectionTitle); + var isDiscrete = string.Equals(blockAttr?.BlockStyle, "discrete", StringComparison.OrdinalIgnoreCase) + || string.Equals(blockAttr?.BlockStyle, "float", StringComparison.OrdinalIgnoreCase); _pos++; var children = new List(); @@ -231,7 +233,7 @@ private SectionNode ParseSection(string? id, string? title) break; case TokenType.SectionTitle: - var childSection = ParseSection(pendingId, null); + var childSection = ParseSection(pendingId, null, pendingBlockAttr); children.Add(childSection); pendingId = null; pendingTitle = null; @@ -267,7 +269,7 @@ private SectionNode ParseSection(string? id, string? title) } } - return new SectionNode { Level = level, Title = sectionTitle, Id = sectionId, Children = children }; + return new SectionNode { Level = level, Title = sectionTitle, Id = sectionId, Children = children, IsDiscrete = isDiscrete }; } private IAsciidocNode? ParseBlock(string? id, string? title, TokenMetadata? blockAttr) @@ -1285,7 +1287,7 @@ private static AdmonitionType ParseAdmonitionType(string style) => _pos++; break; case TokenType.SectionTitle: - var section = ParseSection(pendingId, null); + var section = ParseSection(pendingId, null, pendingBlockAttr); result.Add(section with { IsIncludeRoot = true }); pendingId = null; pendingTitle = null; @@ -1320,6 +1322,72 @@ private static AdmonitionType ParseAdmonitionType(string style) => _ = _attributes.Remove("docdir"); _includeDepth--; + // Re-nest sections by heading level: a section at level N that follows a section at + // level < N in the flat result list becomes a child of that ancestor, replicating + // AsciiDoc's natural hierarchical nesting (e.g. migration/index.asciidoc includes a + // Level-0 intro file followed by Level-1 version files — those version sections should + // be children of the Level-0 section, not top-level siblings). + return NestSectionsByLevel(result); + } + + private static List NestSectionsByLevel(List nodes) + { + // Fast path: no section can be nested under another (all same level or no L0 present). + var hasNestableStructure = false; + var firstSectionLevel = int.MaxValue; + foreach (var n in nodes) + { + if (n is not SectionNode s) + continue; + if (s.Level < firstSectionLevel) + firstSectionLevel = s.Level; + else if (s.Level > firstSectionLevel) + { + hasNestableStructure = true; + break; + } + } + if (!hasNestableStructure) + return nodes; + + // Stack entries: the original section node + extra children accumulated from later siblings. + var stack = new List<(SectionNode Section, List Extra)>(); + var result = new List(); + + void AddToContext(IAsciidocNode node) + { + if (stack.Count > 0) + stack[^1].Extra.Add(node); + else + result.Add(node); + } + + IAsciidocNode CloseTop() + { + var (sec, extra) = stack[^1]; + stack.RemoveAt(stack.Count - 1); + return extra.Count == 0 ? sec : sec with { Children = [.. sec.Children, .. extra] }; + } + + foreach (var node in nodes) + { + if (node is SectionNode section) + { + // Close any open sections that are at the same level or deeper. + while (stack.Count > 0 && stack[^1].Section.Level >= section.Level) + AddToContext(CloseTop()); + stack.Add((section, [])); + } + else + { + AddToContext(node); + } + } + + // Drain remaining open sections. + while (stack.Count > 0) + AddToContext(CloseTop()); + return result; } diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs index 75dd1484e3..a9ca2d7920 100644 --- a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/Ast/SectionNode.cs @@ -10,6 +10,13 @@ public record SectionNode : IBlockNode public required string Title { get; init; } public string? Id { get; init; } public List Children { get; init; } = []; - /// True when this section was produced as the top-level result of a ProcessInclude call. + /// True when this section has a [discrete] or [float] block attribute — never becomes its own page. + public bool IsDiscrete { get; init; } + /// + /// True when this section was the top-level result of a ProcessInclude call. + /// Used only for Level-0 sections: a Level-0 section that is NOT an include-root is + /// the transparent book-root wrapper (becomes the index page); one that IS an include-root + /// is a standalone part/book and becomes its own page. + /// public bool IsIncludeRoot { get; init; } } diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs index db2222b717..87e0b8ea4b 100644 --- a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/MarkdownEmitter.cs @@ -16,6 +16,8 @@ public record MarkdownEmitterOptions public Dictionary AnchorToSlugMap { get; init; } = []; public Dictionary AnchorToTitleMap { get; init; } = []; public string? PageSlug { get; init; } + /// AST level of the page root; child headings are rebased relative to it. + public int HeadingLevelBase { get; init; } } public static partial class GuideUrlRewriter @@ -56,6 +58,9 @@ public void UpdateAnchorMap(Dictionary slugMap, Dictionary options = options with { PageSlug = slug }; + public void UpdateHeadingBase(int level) => + options = options with { HeadingLevelBase = level }; + public string Emit(AsciidocDocument document) { Reset(); @@ -106,9 +111,9 @@ private void Reset() private void Write(char value) => _ = _sb.Append(value); - private void WriteLine() => _ = _sb.AppendLine(); + private void WriteLine() => _ = _sb.Append('\n'); - private void WriteLine(string value) => _ = _sb.AppendLine(value); + private void WriteLine(string value) => _ = _sb.Append(value).Append('\n'); private string CaptureOutput(Action action) { @@ -194,8 +199,11 @@ private void EmitNode(IAsciidocNode node) private void EmitSection(SectionNode section) { - var hashes = new string('#', section.Level + 1); - if (section.Level == 0 && section.Id is not null) + // Clamp to 0: inline sections at a level lower than the page root (e.g. a discrete L1 + // section inside a L2 page) are rendered as H1 rather than negative-hash counts. + var effective = Math.Max(0, section.Level - options.HeadingLevelBase); + var hashes = new string('#', effective + 1); + if (effective == 0 && section.Id is not null) { WriteLine($"$$${section.Id}$$$"); WriteLine(); diff --git a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs index dd2311765d..b0078d6346 100644 --- a/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs +++ b/src/authoring/Elastic.LegacyDocs.Migration/Asciidoc/PageChunker.cs @@ -2,191 +2,301 @@ // 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 System.Text.RegularExpressions; using Elastic.LegacyDocs.Migration.Asciidoc.Ast; -using Slugify; namespace Elastic.LegacyDocs.Migration.Asciidoc; -public record PageOutput(string Slug, string Title, string MarkdownContent); +public record PageOutput( + string Slug, + string Title, + string? NavigationTitle, + string MarkdownContent, + IReadOnlyList Children); public static partial class PageChunker { - private static readonly SlugHelper SlugHelper = new(); - [GeneratedRegex(@"^(.*)\s*$", RegexOptions.Singleline)] private static partial Regex TitleAbbrevRegex(); - public static IReadOnlyList Chunk(AsciidocDocument document, int chunkLevel, MarkdownEmitter emitter) + [GeneratedRegex(@"[^a-z0-9]+", RegexOptions.None)] + private static partial Regex SlugNonAlphanumericRegex(); + + /// + /// Chunks the document into a tree of pages using the same rule as the legacy asciidoctor + /// chunker: a section becomes its own page iff it is not [discrete]/[float] and its level + /// is <= chunkLevel + 1 (where chunkLevel == conf.yaml chunk:). + /// + public static IReadOnlyList Chunk( + AsciidocDocument document, int chunkLevel, MarkdownEmitter emitter, + Action? onDiagnostic = null) { if (chunkLevel <= 0) { emitter.UpdatePageSlug("index"); - return [new PageOutput("index", document.Title ?? "Index", emitter.Emit(document))]; + emitter.UpdateHeadingBase(0); + return [new PageOutput("index", document.Title ?? "Index", null, emitter.Emit(document), [])]; } - var (slugMap, titleMap) = BuildAnchorMaps(document.Children, chunkLevel); - emitter.UpdateAnchorMap(slugMap, titleMap); + // Effective chunk level in AST terms: chunk:1 => sections at level <= 2 are pages. + var effectiveChunkLevel = chunkLevel + 1; + + var slugMap = new Dictionary(StringComparer.OrdinalIgnoreCase); + var titleMap = new Dictionary(StringComparer.OrdinalIgnoreCase); + var allocatedSlugs = new HashSet(StringComparer.OrdinalIgnoreCase); + + _ = allocatedSlugs.Add("index"); + + // Detect the book root: a single Level-0 section in document.Children is always the + // book root / index wrapper, whether it arrived inline (IsIncludeRoot=false) or via a + // top-level include (IsIncludeRoot=true, e.g. index.x.asciidoc → index.asciidoc). + // Map its id to "index" so cross-references like [[elasticsearch-reference]] resolve + // to index.md, then traverse its children instead of the document root's children. + SectionNode? bookRoot = null; + if (document.Children is [SectionNode { Level: 0 } candidate]) + bookRoot = candidate; + + if (document.Id is not null) + slugMap[document.Id] = "index"; + if (bookRoot?.Id is not null) + slugMap[bookRoot.Id] = "index"; + + var rootTitle = bookRoot?.Title ?? document.Title ?? "Index"; + var rootChildren = bookRoot is not null ? bookRoot.Children : document.Children; - var (pages, remaining) = ExtractPages(document.Children, chunkLevel, emitter); + // Single traversal: build the page tree, anchor maps, and inline content together. + var (rootPageNodes, indexInlineContent) = Traverse( + rootChildren, effectiveChunkLevel, slugMap, titleMap, allocatedSlugs, onDiagnostic); - var indexDoc = document with { Children = remaining.ToList() }; + // Map any inline content at the doc root to the index slug. + CollectChildAnchors(indexInlineContent, "index", slugMap, titleMap); + + // Publish anchor maps to the emitter before any emission. + emitter.UpdateAnchorMap(slugMap, titleMap); + + // Emit the index page using the book root section so its H1 and id are included. + var indexSection = bookRoot is not null + ? bookRoot with { Children = indexInlineContent, Level = 0 } + : null; emitter.UpdatePageSlug("index"); - var indexContent = emitter.Emit(indexDoc); - var indexPage = new PageOutput("index", document.Title ?? "Index", indexContent); + emitter.UpdateHeadingBase(0); + var indexContent = indexSection is not null + ? emitter.Emit(indexSection) + : emitter.Emit(document with { Children = indexInlineContent }); + var indexPage = new PageOutput("index", rootTitle, null, indexContent, []); - return [indexPage, .. pages]; + var childPages = EmitPageNodes(rootPageNodes, emitter); + return [indexPage, .. childPages]; } - private static (Dictionary SlugMap, Dictionary TitleMap) BuildAnchorMaps( - IReadOnlyList children, int chunkLevel) - { - var slugMap = new Dictionary(StringComparer.OrdinalIgnoreCase); - var titleMap = new Dictionary(StringComparer.OrdinalIgnoreCase); - CollectAnchors(children, chunkLevel, slugMap, titleMap); - return (slugMap, titleMap); - } + // ── Internal page node (pre-emission) ───────────────────────────────────── - private static void CollectAnchors( - IReadOnlyList children, int chunkLevel, - Dictionary slugMap, Dictionary titleMap) + private sealed record PageNode( + SectionNode Section, + string Slug, + string? NavigationTitle, + List InlineContent, + List ChildPages); + + // ── Traversal ───────────────────────────────────────────────────────────── + + /// + /// Recursively splits AST children into page nodes and inline content. + /// Pages become their own entries in the nav tree; inline content stays in the parent page body. + /// + private static (List Pages, List Inline) Traverse( + IReadOnlyList children, int effectiveChunkLevel, + Dictionary slugMap, Dictionary titleMap, + HashSet allocatedSlugs, Action? onDiagnostic) { + var pages = new List(); + var inline = new List(); + foreach (var child in children) { - // Recurse transparently into open blocks — they may contain sections or anchored blocks - if (child is OpenBlockNode open) + switch (child) { - CollectAnchors(open.Children, chunkLevel, slugMap, titleMap); - continue; - } + case OpenBlockNode open: + { + // Transparent container: hoist inner pages up; rewrap remaining inline nodes. + var (innerPages, innerInline) = Traverse( + open.Children, effectiveChunkLevel, slugMap, titleMap, allocatedSlugs, onDiagnostic); + pages.AddRange(innerPages); + if (innerInline.Count > 0) + inline.Add(open with { Children = innerInline }); + break; + } - if (child is not SectionNode section) - continue; + case SectionNode section when IsPage(section, effectiveChunkLevel): + { + // This section becomes its own page. + var slug = AllocateSlug(section, allocatedSlugs, onDiagnostic); + if (section.Id is not null) + { + slugMap[section.Id] = slug; + titleMap[section.Id] = ExtractDisplayTitle(section); + } - // Non-include-root Level-0 sections are transparent book-root wrappers - if (section.Level == 0 && !section.IsIncludeRoot) - { - CollectAnchors(section.Children, chunkLevel, slugMap, titleMap); - continue; - } + var (subPages, subInline) = Traverse( + section.Children, effectiveChunkLevel, slugMap, titleMap, allocatedSlugs, onDiagnostic); - // Include roots and sections within chunk depth each become a page - if (section.IsIncludeRoot || section.Level <= chunkLevel) - { - var slug = section.Id ?? GenerateSlug(section.Title); - if (section.Id is not null) - { - slugMap[section.Id] = slug; - titleMap[section.Id] = ExtractDisplayTitle(section); - } - - CollectChildAnchors(section.Children, slug, slugMap, titleMap); - CollectAnchors(section.Children, chunkLevel, slugMap, titleMap); - } - else - { - // Inline section deeper than chunkLevel — recurse for nested IsIncludeRoot sections - CollectAnchors(section.Children, chunkLevel, slugMap, titleMap); + // Map all inline sub-content's anchors to this page's slug. + CollectChildAnchors(subInline, slug, slugMap, titleMap); + + var navTitle = ExtractDisplayTitle(section); + var navTitleOut = navTitle == section.Title ? null : navTitle; + + pages.Add(new PageNode(section, slug, navTitleOut, subInline, subPages)); + break; + } + + case SectionNode section: + { + var (innerPages, innerInline) = Traverse( + section.Children, effectiveChunkLevel, slugMap, titleMap, allocatedSlugs, onDiagnostic); + pages.AddRange(innerPages); + if (section.Level == 0 && !section.IsIncludeRoot) + { + // Transparent book-root wrapper: its inline content flows into the index page + // directly (no wrapper heading), so we hoist both pages and inline nodes. + inline.AddRange(innerInline); + } + else + { + // Non-page discrete/too-deep section: keep the section heading inline. + inline.Add(section with { Children = innerInline }); + } + break; + } + + default: + inline.Add(child); + break; } } - } - // Extracts the display title for a section: uses if present, otherwise the section title. - private static string ExtractDisplayTitle(SectionNode section) - { - foreach (var child in section.Children) - { - if (child is not PassthroughNode passthrough) - continue; - var m = TitleAbbrevRegex().Match(passthrough.Content.Trim()); - if (m.Success) - return m.Groups[1].Value; - } - return section.Title; + return (pages, inline); } + // ── Anchor collection ───────────────────────────────────────────────────── + + /// Maps every block anchor and non-page sub-section id to the parent page's slug. private static void CollectChildAnchors( IReadOnlyList children, string parentSlug, Dictionary slugMap, Dictionary titleMap) { foreach (var child in children) { - if (child is SectionNode sub && sub.Id is not null) + switch (child) { - slugMap[sub.Id] = parentSlug; - titleMap[sub.Id] = ExtractDisplayTitle(sub); - CollectChildAnchors(sub.Children, parentSlug, slugMap, titleMap); - } - else if (child is AnchoredBlock anchored) - { - slugMap[anchored.Id] = parentSlug; + case OpenBlockNode open: + CollectChildAnchors(open.Children, parentSlug, slugMap, titleMap); + break; + case AnchoredBlock anchored: + slugMap[anchored.Id] = parentSlug; + break; + case SectionNode sub: + if (sub.Id is not null) + { + slugMap[sub.Id] = parentSlug; + titleMap[sub.Id] = ExtractDisplayTitle(sub); + } + CollectChildAnchors(sub.Children, parentSlug, slugMap, titleMap); + break; } } } - private static (List Pages, List Remaining) ExtractPages( - IReadOnlyList children, - int chunkLevel, - MarkdownEmitter emitter - ) - { - var pages = new List(); - var remaining = new List(); + // ── Emission ────────────────────────────────────────────────────────────── - foreach (var child in children) + private static IReadOnlyList EmitPageNodes( + IReadOnlyList nodes, MarkdownEmitter emitter) + { + var result = new List(nodes.Count); + foreach (var node in nodes) { - // Recurse transparently into open blocks so nested sections are chunked correctly - if (child is OpenBlockNode open) - { - var (innerPages, innerRemaining) = ExtractPages(open.Children, chunkLevel, emitter); - pages.AddRange(innerPages); - if (innerRemaining.Count > 0) - remaining.Add(open with { Children = innerRemaining.ToList() }); - continue; - } + // Render only the inline content (sub-pages are emitted separately). + var section = node.Section with { Children = node.InlineContent }; + emitter.UpdatePageSlug(node.Slug); + emitter.UpdateHeadingBase(node.Section.Level); - if (child is not SectionNode section) + var sb = new StringBuilder(); + if (node.NavigationTitle is not null) { - remaining.Add(child); - continue; + _ = sb.Append("---\n"); + _ = sb.Append("navigation_title: \"").Append(node.NavigationTitle.Replace("\"", "\\\"")).Append("\"\n"); + _ = sb.Append("---\n"); + _ = sb.Append('\n'); } + _ = sb.Append(emitter.Emit(section)); - // Non-include-root Level-0 sections are transparent book-root wrappers - if (section.Level == 0 && !section.IsIncludeRoot) - { - var (innerPages, innerRemaining) = ExtractPages(section.Children, chunkLevel, emitter); - pages.AddRange(innerPages); - remaining.Add(section with { Children = innerRemaining.ToList() }); - continue; - } + var children = EmitPageNodes(node.ChildPages, emitter); + result.Add(new PageOutput(node.Slug, node.Section.Title, node.NavigationTitle, sb.ToString(), children)); + } + return result; + } - // Inline sections above the chunk depth stay in the parent page, but their - // children may still contain IsIncludeRoot sections that must be extracted. - if (section.Level > chunkLevel && !section.IsIncludeRoot) - { - var (innerPages, innerRemaining) = ExtractPages(section.Children, chunkLevel, emitter); - pages.AddRange(innerPages); - remaining.Add(section with { Children = innerRemaining.ToList() }); - continue; - } + // ── Helpers ─────────────────────────────────────────────────────────────── - var (subPages, sectionRemaining) = ExtractPages(section.Children, chunkLevel, emitter); + /// + /// Determines whether a section becomes its own page, replicating the legacy asciidoctor chunker rule: + /// - Never page if [discrete]/[float]. + /// - Level 0 sections: page only when they come from an include (IsIncludeRoot), i.e. they are a + /// standalone part included into the book root. The non-include-root Level-0 section is the + /// transparent book-root wrapper that becomes the index page. + /// - Level > 0: page when level <= effectiveChunkLevel (== conf.yaml chunk + 1). + /// + private static bool IsPage(SectionNode section, int effectiveChunkLevel) => + !section.IsDiscrete && + (section.Level == 0 ? section.IsIncludeRoot : section.Level <= effectiveChunkLevel); - var trimmedSection = section with { Children = sectionRemaining.ToList(), Level = 0 }; - var slug = section.Id ?? GenerateSlug(section.Title); - emitter.UpdatePageSlug(slug); - var content = emitter.Emit(trimmedSection); + private static string AllocateSlug( + SectionNode section, HashSet allocatedSlugs, Action? onDiagnostic) + { + var baseSlug = section.Id ?? AutoId(section.Title); + if (allocatedSlugs.Add(baseSlug)) + return baseSlug; - pages.Add(new PageOutput(slug, section.Title, content)); - pages.AddRange(subPages); + for (var i = 2; i < 10_000; i++) + { + var candidate = $"{baseSlug}_{i}"; + if (allocatedSlugs.Add(candidate)) + { + onDiagnostic?.Invoke( + $"Slug collision for '{baseSlug}' (section '{section.Title}'); using '{candidate}'"); + return candidate; + } } - - return (pages, remaining); + throw new InvalidOperationException($"Cannot allocate a unique slug for '{baseSlug}'"); } - private static string GenerateSlug(string title) + /// Reproduces asciidoctor's default section id: lowercase, non-alphanumeric runs → '_'. + private static string AutoId(string title) { - var slug = SlugHelper.GenerateSlug(title); + var lower = title.ToLowerInvariant(); + var slug = SlugNonAlphanumericRegex().Replace(lower, "_").Trim('_'); return string.IsNullOrEmpty(slug) ? "section" : slug; } + + private static string ExtractDisplayTitle(SectionNode section) + { + foreach (var child in section.Children) + { + // can be a PassthroughNode (passthrough block) or a ParagraphNode + // (plain text line) depending on how the source was written. + var raw = child switch + { + PassthroughNode p => p.Content.Trim(), + ParagraphNode { Inlines: [TextInline { Text: var t }] } => t.Trim(), + _ => null + }; + if (raw is null) + continue; + var m = TitleAbbrevRegex().Match(raw); + if (m.Success) + return m.Groups[1].Value; + } + return section.Title; + } } diff --git a/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs b/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs index 0c276e8373..56f04858a5 100644 --- a/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs +++ b/src/authoring/Elastic.LegacyDocs.Migration/YamlWriter.cs @@ -11,6 +11,8 @@ public record TocEntry public string? File { get; init; } public string? Folder { get; init; } public string? Toc { get; init; } + public bool Island { get; init; } + public List Children { get; init; } = []; } public static class YamlWriter @@ -30,17 +32,35 @@ public static void WriteTocYaml(string path, List entries) { var sb = new StringBuilder(); _ = sb.Append("toc:\n"); + AppendEntries(sb, entries, indent: 2); + + EnsureDirectoryAndWrite(path, sb.ToString()); + } + + private static void AppendEntries(StringBuilder sb, List entries, int indent) + { + var pad = new string(' ', indent); foreach (var entry in entries) { if (entry.File is not null) - _ = sb.Append(" - file: ").Append(entry.File).Append('\n'); + _ = sb.Append(pad).Append("- file: ").Append(entry.File).Append('\n'); else if (entry.Folder is not null) - _ = sb.Append(" - folder: ").Append(entry.Folder).Append('\n'); + _ = sb.Append(pad).Append("- folder: ").Append(entry.Folder).Append('\n'); else if (entry.Toc is not null) - _ = sb.Append(" - toc: ").Append(entry.Toc).Append('\n'); - } + { + _ = sb.Append(pad).Append("- toc: ").Append(entry.Toc).Append('\n'); + if (entry.Island) + _ = sb.Append(pad).Append(" island: true\n"); + } + else + continue; - EnsureDirectoryAndWrite(path, sb.ToString()); + if (entry.Children.Count > 0) + { + _ = sb.Append(pad).Append(" children:\n"); + AppendEntries(sb, entry.Children, indent + 4); + } + } } private static void EnsureDirectoryAndWrite(string path, string content) diff --git a/src/tooling/docs-builder/Commands/ServeCommand.cs b/src/tooling/docs-builder/Commands/ServeCommand.cs index 515c839abd..2321d9fc71 100644 --- a/src/tooling/docs-builder/Commands/ServeCommand.cs +++ b/src/tooling/docs-builder/Commands/ServeCommand.cs @@ -2,7 +2,6 @@ // 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.IO.Abstractions; using Documentation.Builder.Http; using Elastic.Documentation; using Elastic.Documentation.Configuration; diff --git a/src/tooling/docs-migrate/ConvertCommand.cs b/src/tooling/docs-migrate/ConvertCommand.cs index 77a8d7328e..d998f084d5 100644 --- a/src/tooling/docs-migrate/ConvertCommand.cs +++ b/src/tooling/docs-migrate/ConvertCommand.cs @@ -85,7 +85,7 @@ public async Task Convert( var fileEntries = await WritePages(pages, versionDir, ct); YamlWriter.WriteTocYaml(Path.Combine(versionDir, "toc.yml"), fileEntries); - versionEntries.Add(new TocEntry { Toc = versionLabel }); + versionEntries.Add(new TocEntry { Toc = versionLabel, Island = true }); convertedVersions.Add(versionLabel); _logger.LogInformation("Wrote {PageCount} pages for {Prefix}/{Version}", @@ -182,8 +182,6 @@ private async Task> ProcessBookVersion( }; var emitter = new MarkdownEmitter(emitterOptions); - // conf.yaml chunk: N means "chunk at N levels below the document root (= title)". - // The AST levels match directly: == is Level 1, === is Level 2, etc. return PageChunker.Chunk(document, book.Chunk, emitter); } @@ -195,7 +193,12 @@ private static async Task> WritePages( { var filename = $"{page.Slug}.md"; await File.WriteAllTextAsync(Path.Combine(directory, filename), page.MarkdownContent, ct); - entries.Add(new TocEntry { File = filename }); + + List childEntries = []; + if (page.Children.Count > 0) + childEntries = await WritePages(page.Children, directory, ct); + + entries.Add(new TocEntry { File = filename, Children = childEntries }); } return entries; } @@ -203,6 +206,10 @@ private static async Task> WritePages( private static void WriteBookVersionIndex(string prefixDir, LegacyBook book, List versions) { var sb = new StringBuilder(); + _ = sb.AppendLine("---"); + _ = sb.Append("navigation_title: \"").Append(book.Title).AppendLine("\""); + _ = sb.AppendLine("---"); + _ = sb.AppendLine(); _ = sb.Append("# ").Append(book.Title).AppendLine(" — All Versions"); _ = sb.AppendLine(); _ = sb.AppendLine("| Version | Status |"); @@ -256,8 +263,6 @@ private static void WriteRootDocsetYaml(string outputDir, List tocRefs) { var sb = new StringBuilder(); _ = sb.AppendLine("project: elastic-guide-archive"); - _ = sb.AppendLine("features:"); - _ = sb.AppendLine(" guide-nav: true"); _ = sb.AppendLine("subs:"); foreach (var (key, value) in SharedAttributes.ProductNames.OrderBy(kv => kv.Key, StringComparer.OrdinalIgnoreCase)) @@ -267,7 +272,10 @@ private static void WriteRootDocsetYaml(string outputDir, List tocRefs) _ = sb.AppendLine(" - file: index.md"); foreach (var prefix in tocRefs) + { _ = sb.Append(" - toc: ").AppendLine(prefix); + _ = sb.AppendLine(" island: true"); + } File.WriteAllText(Path.Combine(outputDir, "docset.yml"), sb.ToString()); } diff --git a/src/tooling/docs-migrate/ServeCommand.cs b/src/tooling/docs-migrate/ServeCommand.cs index ca511d075c..8cdf47f79c 100644 --- a/src/tooling/docs-migrate/ServeCommand.cs +++ b/src/tooling/docs-migrate/ServeCommand.cs @@ -2,6 +2,7 @@ // 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.Documentation.Configuration; using ProcNet; namespace Documentation.Migrate; @@ -13,7 +14,7 @@ internal sealed class ServeCommand /// Cancellation token public async Task Serve(int port = 3001, CancellationToken ct = default) { - var outputDir = Path.Combine(Directory.GetCurrentDirectory(), ".artifacts", "migrated"); + var outputDir = Path.Combine(Paths.WorkingDirectoryRoot.FullName, ".artifacts", "migrated"); if (!Directory.Exists(outputDir)) { @@ -24,7 +25,10 @@ public async Task Serve(int port = 3001, CancellationToken ct = default) string[] args = ["run", "--project", "src/tooling/docs-builder", "--", "serve", "--path", outputDir, "--port", $"{port}", "--no-hud"]; Console.WriteLine($"dotnet {string.Join(' ', args)}"); - var arguments = new ExecArguments("dotnet", args); + var arguments = new ExecArguments("dotnet", args) + { + WorkingDirectory = Paths.WorkingDirectoryRoot.FullName + }; try { return await Proc.ExecAsync(arguments, ct); diff --git a/src/tooling/docs-migrate/docs-migrate.csproj b/src/tooling/docs-migrate/docs-migrate.csproj index 0650fdf4a8..1cce436686 100644 --- a/src/tooling/docs-migrate/docs-migrate.csproj +++ b/src/tooling/docs-migrate/docs-migrate.csproj @@ -19,6 +19,7 @@ + diff --git a/tests/Elastic.LegacyDocs.Migration.Tests/ChunkerTests.cs b/tests/Elastic.LegacyDocs.Migration.Tests/ChunkerTests.cs new file mode 100644 index 0000000000..431a811838 --- /dev/null +++ b/tests/Elastic.LegacyDocs.Migration.Tests/ChunkerTests.cs @@ -0,0 +1,391 @@ +// 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 AwesomeAssertions; +using Elastic.LegacyDocs.Migration.Asciidoc; +using Elastic.LegacyDocs.Migration.Asciidoc.Ast; + +namespace Elastic.LegacyDocs.Migration.Tests; + +/// +/// Unit tests for PageChunker that verify it replicates the legacy asciidoctor chunker behaviour. +/// Key rule: a section becomes its own page iff it is not [discrete]/[float] AND its level is +/// <= (conf.yaml chunk + 1). Level-0 sections are pages only when they come from an include. +/// +public class ChunkerTests +{ + private static MarkdownEmitter Emitter() => + new(new MarkdownEmitterOptions { BookPrefix = "test", Version = "1.0" }); + + private static Elastic.LegacyDocs.Migration.Asciidoc.Ast.AsciidocDocument Parse(string content, Dictionary? files = null) + { + var opts = new AsciidocParserOptions + { + FileReader = files is not null + ? path => files.TryGetValue(path, out var c) ? c : null + : null + }; + return new AsciidocParser(opts).Parse(content, "/base"); + } + + // ── DocTitle becomes the index page ─────────────────────────────────────── + + [Fact] + public void DocTitle_BecomesIndexPage_NoDuplicatePage() + { + // The Level-0 `= Book Title` section is the transparent wrapper; it becomes `index.md`. + // There must NOT be a separate `book_title` slug. + const string source = """ + = Book Title + + Some landing text. + """; + + var pages = PageChunker.Chunk(Parse(source), chunkLevel: 1, Emitter()); + + pages.Should().HaveCount(1); + pages[0].Slug.Should().Be("index"); + pages[0].MarkdownContent.Should().Contain("Some landing text"); + } + + // ── Discrete sections never become pages ────────────────────────────────── + + [Fact] + public void DiscreteSection_IsNeverChunked() + { + // quickstart/index.asciidoc shape via include: + // = Elasticsearch Guide (Level-0 wrapper → index) + // = Quick starts (Level-0 include → its own page) + // [discrete] == Requirements (discrete → inline on quickstart page) + // == Index and search… (Level 1 ≤ 2 → child page) + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Elasticsearch Guide + + include::quickstart.adoc[] + """, + ["/base/quickstart.adoc"] = """ + [[quickstart]] + = Quick starts + + [discrete] + [[quickstart-requirements]] + == Requirements + + Requirements text. + + [[getting-started]] + == Index and search using APIs + + Getting started text. + """, + }; + + var pages = PageChunker.Chunk(Parse(files["/base/index.adoc"], files), chunkLevel: 1, Emitter()); + + // Top-level: index + quickstart. + pages.Should().HaveCount(2); + var quickstart = pages.First(p => p.Slug == "quickstart"); + + // [discrete] == Requirements → inline heading on the quickstart page, NOT a child page. + quickstart.Children.Should().HaveCount(1); + quickstart.Children[0].Slug.Should().Be("getting-started"); + quickstart.MarkdownContent.Should().Contain("Requirements text"); + quickstart.MarkdownContent.Should().NotContain("Getting started text"); // in child page + } + + // ── Section deeper than chunkLevel stays inline, rebased as ## ─────────── + + [Fact] + public void Section_DeeperThanChunkLevel_StaysOnParentPage() + { + // setup/install/targz.asciidoc shape (chunk:1 → effectiveChunkLevel 2): + // = Book (Level-0 wrapper → index) + // == Installing (Level 1 → page) + // === Install from archive (Level 2 ≤ 2 → page, child of Installing) + // ==== Next steps (Level 3 > 2 → inline ## on the targz page) + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Book + + include::setup.adoc[] + """, + ["/base/setup.adoc"] = """ + [[setup]] + == Installing Elasticsearch + + include::targz.adoc[] + """, + ["/base/targz.adoc"] = """ + [[targz]] + === Install from archive on Linux + + Intro text. + + ==== Next steps + + Next steps text. + """, + }; + + var pages = PageChunker.Chunk(Parse(files["/base/index.adoc"], files), chunkLevel: 1, Emitter()); + + // index + setup at top level. + pages.Should().HaveCount(2); + var setup = pages.First(p => p.Slug == "setup"); + // targz is a child of setup. + setup.Children.Should().HaveCount(1); + var targz = setup.Children[0]; + targz.Slug.Should().Be("targz"); + targz.Children.Should().BeEmpty(); // no further child pages + targz.MarkdownContent.Should().Contain("Intro text"); + targz.MarkdownContent.Should().Contain("## Next steps"); // Level 3, rebased: effective=3-2=1 → ## + } + + // ── TitleAbbrev emits navigation_title frontmatter ──────────────────────── + + [Fact] + public void TitleAbbrev_EmitsNavigationTitleFrontmatter() + { + // `== ...` (Level 1) is the doc title in a bare file; use a book wrapper. + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Book + + include::getting-started.adoc[] + """, + ["/base/getting-started.adoc"] = """ + [[getting-started]] + == Index and search data using Elasticsearch APIs + + Basics: Index and search using APIs + + Page content. + """, + }; + + var pages = PageChunker.Chunk(Parse(files["/base/index.adoc"], files), chunkLevel: 1, Emitter()); + + var page = pages.First(p => p.Slug == "getting-started"); + page.NavigationTitle.Should().Be("Basics: Index and search using APIs"); + page.MarkdownContent.Should().StartWith("---\n"); + page.MarkdownContent.Should().Contain("navigation_title: \"Basics: Index and search using APIs\""); + page.MarkdownContent.Should().NotContain(""); + } + + [Fact] + public void TitleAbbrev_MatchingTitle_DoesNotEmitFrontmatter() + { + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Book + + include::mypage.adoc[] + """, + ["/base/mypage.adoc"] = """ + [[mypage]] + == My Page + + My Page + + Content. + """, + }; + + var pages = PageChunker.Chunk(Parse(files["/base/index.adoc"], files), chunkLevel: 1, Emitter()); + + var page = pages.First(p => p.Slug == "mypage"); + page.NavigationTitle.Should().BeNull(); + page.MarkdownContent.Should().NotContain("navigation_title:"); + } + + // ── Auto-id derivation ──────────────────────────────────────────────────── + + [Fact] + public void IdLessSection_UsesAutoId() + { + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Book + + include::install.adoc[] + """, + ["/base/install.adoc"] = """ + == Install from Archive on Linux/MacOS + + Content. + """, + }; + + var pages = PageChunker.Chunk(Parse(files["/base/index.adoc"], files), chunkLevel: 1, Emitter()); + + // Auto-id: lowercase, non-alphanumeric runs → '_', leading/trailing '_' trimmed. + var page = pages.First(p => p.Slug != "index"); + page.Slug.Should().Be("install_from_archive_on_linux_macos"); + } + + [Fact] + public void DuplicateSlug_IsSuffixed() + { + // Two included files with the same section id would collide; the second gets _2. + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Book + + include::a.adoc[] + include::b.adoc[] + """, + ["/base/a.adoc"] = """ + [[dup]] + == Section A + + Content A. + """, + ["/base/b.adoc"] = """ + [[dup]] + == Section B + + Content B. + """, + }; + + var diagnostics = new List(); + var doc = Parse(files["/base/index.adoc"], files); + var pages = PageChunker.Chunk(doc, chunkLevel: 1, Emitter(), d => diagnostics.Add(d)); + + var slugs = FlatSlugs(pages); + slugs.Should().Contain("dup"); + slugs.Should().Contain("dup_2"); + diagnostics.Should().HaveCount(1); + diagnostics[0].Should().Contain("Slug collision"); + } + + // ── Include-file cross-level nesting ───────────────────────────────────── + + [Fact] + public void CrossInclude_Level1FollowingLevel0_NestedAsChildren() + { + // Mirrors the migration guide pattern: + // migration/index.asciidoc includes migration_intro (= L0) then + // individual migrate_8_N files (== L1), all via ProcessInclude. + // The L1 sections should become children of the L0 section, not siblings. + var files = new Dictionary + { + ["/base/index.adoc"] = """ + = Book + + include::migration/index.adoc[] + """, + ["/base/migration/index.adoc"] = """ + include::intro.adoc[] + include::migrate-1.adoc[] + include::migrate-2.adoc[] + """, + ["/base/migration/intro.adoc"] = """ + [[migration-guide]] + = Migration guide + + Intro text. + """, + ["/base/migration/migrate-1.adoc"] = """ + [[migrating-1]] + == Migrating to 1.0 + + Migration 1 content. + """, + ["/base/migration/migrate-2.adoc"] = """ + [[migrating-2]] + == Migrating to 2.0 + + Migration 2 content. + """, + }; + + var pages = PageChunker.Chunk(Parse(files["/base/index.adoc"], files), chunkLevel: 1, Emitter()); + + // Top level: index + migration-guide. + pages.Should().HaveCount(2); + var migrationGuide = pages.First(p => p.Slug == "migration-guide"); + migrationGuide.MarkdownContent.Should().Contain("Intro text"); + + // Version pages are children of migration-guide, not top-level siblings. + migrationGuide.Children.Should().HaveCount(2); + migrationGuide.Children[0].Slug.Should().Be("migrating-1"); + migrationGuide.Children[1].Slug.Should().Be("migrating-2"); + } + + // ── Nested toc.yml indentation ──────────────────────────────────────────── + + [Fact] + public void WriteTocYaml_NestedChildren_IndentsCorrectly() + { + var entries = new List + { + new() { File = "index.md" }, + new() + { + File = "quickstart.md", + Children = + [ + new TocEntry { File = "getting-started.md" }, + new TocEntry { File = "full-text.md" } + ] + }, + }; + + var path = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName(), "toc.yml"); + YamlWriter.WriteTocYaml(path, entries); + var yaml = File.ReadAllText(path); + + yaml.Should().StartWith("toc:\n"); + yaml.Should().Contain(" - file: index.md\n"); + yaml.Should().Contain(" - file: quickstart.md\n"); + yaml.Should().Contain(" children:\n"); + yaml.Should().Contain(" - file: getting-started.md\n"); + yaml.Should().Contain(" - file: full-text.md\n"); + } + + [Fact] + public void WriteTocYaml_IslandToc_EmitsIslandKey() + { + var entries = new List + { + new() { File = "index.md" }, + new() { Toc = "8.19", Island = true }, + new() { Toc = "8.18", Island = true }, + }; + + var path = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName(), "toc.yml"); + YamlWriter.WriteTocYaml(path, entries); + var yaml = File.ReadAllText(path); + + yaml.Should().Contain(" - toc: 8.19\n"); + yaml.Should().Contain(" island: true\n"); + yaml.Should().Contain(" - toc: 8.18\n"); + } + + // ── Helpers ─────────────────────────────────────────────────────────────── + + private static IReadOnlyList FlatSlugs(IReadOnlyList pages) + { + var result = new List(); + Collect(pages, result); + return result; + + static void Collect(IReadOnlyList ps, List acc) + { + foreach (var p in ps) + { + acc.Add(p.Slug); + Collect(p.Children, acc); + } + } + } +} diff --git a/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs b/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs index 66831c57db..437c7ca598 100644 --- a/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs +++ b/tests/Elastic.LegacyDocs.Migration.Tests/ParserTests.cs @@ -346,28 +346,42 @@ Sort content. var emitter = new MarkdownEmitter(new MarkdownEmitterOptions { BookPrefix = "test", Version = "1.0" }); var pages = PageChunker.Chunk(doc, chunkLevel: 1, emitter); - var slugs = pages.Select(p => p.Slug).ToList(); + // Each included file becomes its own page; included-inside-body files are child pages. + // Flatten the tree to verify all pages exist regardless of depth. + var allPages = Flatten(pages); + var slugs = allPages.Select(p => p.Slug).ToList(); // index (from = Elasticsearch Guide root) slugs.Should().Contain("index"); - // = Search your data → its own page + // = Search your data → its own top-level page slugs.Should().Contain("search-with-elasticsearch"); - var searchYourData = pages.First(p => p.Slug == "search-with-elasticsearch"); + var searchYourData = allPages.First(p => p.Slug == "search-with-elasticsearch"); searchYourData.MarkdownContent.Should().Contain("Intro paragraph"); searchYourData.MarkdownContent.Should().Contain("Run a search"); // inline section stays searchYourData.MarkdownContent.Should().NotContain("The search API"); // NOT merged into this page - // == The search API → its own page + // == The search API → child page of search-with-elasticsearch (nested include) slugs.Should().Contain("search-your-data-api"); - var theSearchApi = pages.First(p => p.Slug == "search-your-data-api"); + var theSearchApi = allPages.First(p => p.Slug == "search-your-data-api"); theSearchApi.MarkdownContent.Should().Contain("API intro"); theSearchApi.MarkdownContent.Should().Contain("API Run a search"); // inline stays theSearchApi.MarkdownContent.Should().NotContain("Sort search results"); // NOT merged - // === Sort search results → its own page (included file, even though === level) + // === Sort search results → child page of search-your-data-api (nested include) slugs.Should().Contain("sort-results"); - var sortResults = pages.First(p => p.Slug == "sort-results"); + var sortResults = allPages.First(p => p.Slug == "sort-results"); sortResults.MarkdownContent.Should().Contain("Sort content"); } + + private static List Flatten(IReadOnlyList pages) + { + var result = new List(); + foreach (var p in pages) + { + result.Add(p); + result.AddRange(Flatten(p.Children)); + } + return result; + } } From 230cf77a50b45c1fcacd9eb75e530c1fc0032ec9 Mon Sep 17 00:00:00 2001 From: Alex Cerezo Date: Fri, 14 Aug 2026 13:15:07 +0200 Subject: [PATCH 10/11] Enable antialiased font smoothing on body (#3868) Subpixel smoothing made Inter look heavier than the docs type in Figma. Co-authored-by: Claude Sonnet 4.6 (1M context) Co-authored-by: Cursor --- src/Elastic.Documentation.Site/Assets/styles.css | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/Elastic.Documentation.Site/Assets/styles.css b/src/Elastic.Documentation.Site/Assets/styles.css index 373aa70ed5..d025438eeb 100644 --- a/src/Elastic.Documentation.Site/Assets/styles.css +++ b/src/Elastic.Documentation.Site/Assets/styles.css @@ -48,6 +48,8 @@ html { body { /* This is still needed because of some usages of ch units and to maintain the previous behavior */ font-size: 16px; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; } :root { From b641504e8653fc9cbe1676c22288c5fb971a01de Mon Sep 17 00:00:00 2001 From: Vlada Chirmicci Date: Fri, 14 Aug 2026 12:24:02 +0100 Subject: [PATCH 11/11] Update the link text to remove (versionless) --- src/Elastic.Markdown/Layout/_LandingPage.cshtml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Layout/_LandingPage.cshtml b/src/Elastic.Markdown/Layout/_LandingPage.cshtml index a3fb4844a3..120f8ec3f1 100644 --- a/src/Elastic.Markdown/Layout/_LandingPage.cshtml +++ b/src/Elastic.Markdown/Layout/_LandingPage.cshtml @@ -81,7 +81,7 @@

        Vector Database

        Build your primary workload around embeddings: semantic search, RAG, or AI retrieval, with built-in models and vector-optimized defaults.

        - View (versionless) docs + View docs