From 87a1d1ab4ca734df8277562c147644ec2ea30014 Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Fri, 21 Mar 2025 14:34:52 -0300 Subject: [PATCH 1/9] Introduce a "Report an issue" link on documentation pages. The link's href is populated with the current window location to pre-fill the github template. --- src/Elastic.Markdown/Assets/styles.css | 12 ++++++++++-- src/Elastic.Markdown/Assets/toc-nav.ts | 8 ++++++++ .../Slices/Layout/_TableOfContents.cshtml | 19 +++++++++++++++++++ 3 files changed, 37 insertions(+), 2 deletions(-) diff --git a/src/Elastic.Markdown/Assets/styles.css b/src/Elastic.Markdown/Assets/styles.css index eac2a3991..895726d08 100644 --- a/src/Elastic.Markdown/Assets/styles.css +++ b/src/Elastic.Markdown/Assets/styles.css @@ -93,7 +93,15 @@ inline-flex justify-center items-center; - + + .link-icon { + @apply + shrink-0 + size-4 + ml-0 + mr-1 + } + .link-arrow { @apply shrink-0 @@ -104,7 +112,7 @@ } &:hover{ - svg { + svg:not(.link-icon) { @apply translate-x-2; } } diff --git a/src/Elastic.Markdown/Assets/toc-nav.ts b/src/Elastic.Markdown/Assets/toc-nav.ts index 48e870171..287772609 100644 --- a/src/Elastic.Markdown/Assets/toc-nav.ts +++ b/src/Elastic.Markdown/Assets/toc-nav.ts @@ -137,4 +137,12 @@ export function initTocNav() { window.addEventListener('scroll', update); window.addEventListener('resize', update); setupSmoothScrolling(elements); + setupReportIssue(); +} + +function setupReportIssue() { + var currentPage = window.location.href; + var reportIssue = document.getElementById('report-issue-link'); + if (reportIssue) + reportIssue.setAttribute('href', `https://github.com/elastic/docs-content/issues/new?template=issue-report.yaml&link=${currentPage}`); } diff --git a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml index 475a69a23..266fced79 100644 --- a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml +++ b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml @@ -27,6 +27,12 @@ {
+ + + + + Edit this page @@ -34,6 +40,19 @@
+
+ + + + + Report an issue + + + + +
} From 734a4aa183c5440624631d3ae3751a7111c9997c Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Fri, 21 Mar 2025 16:14:18 -0300 Subject: [PATCH 2/9] Add source:web label to the issue report shortcut. --- src/Elastic.Markdown/Assets/toc-nav.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Assets/toc-nav.ts b/src/Elastic.Markdown/Assets/toc-nav.ts index 287772609..4f93b4725 100644 --- a/src/Elastic.Markdown/Assets/toc-nav.ts +++ b/src/Elastic.Markdown/Assets/toc-nav.ts @@ -144,5 +144,5 @@ function setupReportIssue() { var currentPage = window.location.href; var reportIssue = document.getElementById('report-issue-link'); if (reportIssue) - reportIssue.setAttribute('href', `https://github.com/elastic/docs-content/issues/new?template=issue-report.yaml&link=${currentPage}`); + reportIssue.setAttribute('href', `https://github.com/elastic/docs-content/issues/new?template=issue-report.yaml&link=${currentPage}&labels=source%3Aweb`); } From e4d27bc4fc7f29ca8c1af9b103e9d98a912ea7a0 Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Fri, 21 Mar 2025 16:18:58 -0300 Subject: [PATCH 3/9] Remove unused href --- src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml index 28454de97..cb39b6818 100644 --- a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml +++ b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml @@ -41,7 +41,7 @@
- + From 8a24547a4169c438fd24fb0c8bc7912f54346227 Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Mon, 24 Mar 2025 02:31:04 -0300 Subject: [PATCH 4/9] Infer current page being reported via Razor Model * Provide default value for CanonicalBaseUrl --- src/Elastic.Markdown/Assets/toc-nav.ts | 8 -------- src/Elastic.Markdown/Slices/HtmlWriter.cs | 6 +++++- src/Elastic.Markdown/Slices/Index.cshtml | 3 ++- .../Slices/Layout/_TableOfContents.cshtml | 2 +- src/Elastic.Markdown/Slices/_ViewModels.cs | 2 ++ src/docs-builder/Cli/Commands.cs | 4 +++- src/docs-builder/Http/DocumentationWebHost.cs | 10 ++++++++-- 7 files changed, 21 insertions(+), 14 deletions(-) diff --git a/src/Elastic.Markdown/Assets/toc-nav.ts b/src/Elastic.Markdown/Assets/toc-nav.ts index 4f93b4725..48e870171 100644 --- a/src/Elastic.Markdown/Assets/toc-nav.ts +++ b/src/Elastic.Markdown/Assets/toc-nav.ts @@ -137,12 +137,4 @@ export function initTocNav() { window.addEventListener('scroll', update); window.addEventListener('resize', update); setupSmoothScrolling(elements); - setupReportIssue(); -} - -function setupReportIssue() { - var currentPage = window.location.href; - var reportIssue = document.getElementById('report-issue-link'); - if (reportIssue) - reportIssue.setAttribute('href', `https://github.com/elastic/docs-content/issues/new?template=issue-report.yaml&link=${currentPage}&labels=source%3Aweb`); } diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs index 7f964bdc8..de2040e1e 100644 --- a/src/Elastic.Markdown/Slices/HtmlWriter.cs +++ b/src/Elastic.Markdown/Slices/HtmlWriter.cs @@ -98,6 +98,9 @@ private async Task RenderLayout(MarkdownFile markdown, MarkdownDocument editUrl = $"https://github.com/elastic/{remote}/edit/{branch}/{path}"; } + var reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl!, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); + var reportUrl = $"https://github.com/elastic/docs-content/issues/new?template=issue_report.yaml&link={reportLinkParameter}&labels=source:web"; + var slice = Index.Create(new IndexViewModel { DocSetName = DocumentationSet.Name, @@ -118,7 +121,8 @@ private async Task RenderLayout(MarkdownFile markdown, MarkdownDocument CanonicalBaseUrl = DocumentationSet.Build.CanonicalBaseUrl, EnableGoogleTagManager = DocumentationSet.Build.EnableGoogleTagManager, Features = DocumentationSet.Configuration.Features, - StaticFileContentHashProvider = StaticFileContentHashProvider + StaticFileContentHashProvider = StaticFileContentHashProvider, + ReportIssueUrl = reportUrl }); return await slice.RenderAsync(cancellationToken: ctx); } diff --git a/src/Elastic.Markdown/Slices/Index.cshtml b/src/Elastic.Markdown/Slices/Index.cshtml index 3ad9d007c..2bf7b90e0 100644 --- a/src/Elastic.Markdown/Slices/Index.cshtml +++ b/src/Elastic.Markdown/Slices/Index.cshtml @@ -18,7 +18,8 @@ CanonicalBaseUrl = Model.CanonicalBaseUrl, EnableGoogleTagManager = Model.EnableGoogleTagManager, Features = Model.Features, - StaticFileContentHashProvider = Model.StaticFileContentHashProvider + StaticFileContentHashProvider = Model.StaticFileContentHashProvider, + ReportIssueUrl = Model.ReportIssueUrl }; }
diff --git a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml index cb39b6818..1ee5906aa 100644 --- a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml +++ b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml @@ -41,7 +41,7 @@
- + diff --git a/src/Elastic.Markdown/Slices/_ViewModels.cs b/src/Elastic.Markdown/Slices/_ViewModels.cs index 92ac5b5c7..d02ea4a77 100644 --- a/src/Elastic.Markdown/Slices/_ViewModels.cs +++ b/src/Elastic.Markdown/Slices/_ViewModels.cs @@ -24,6 +24,7 @@ public class IndexViewModel public required string NavigationHtml { get; init; } public required string? UrlPathPrefix { get; init; } public required string? GithubEditUrl { get; init; } + public required string? ReportIssueUrl { get; init; } public required ApplicableTo? Applies { get; init; } public required bool AllowIndexing { get; init; } public required Uri? CanonicalBaseUrl { get; init; } @@ -49,6 +50,7 @@ public class LayoutViewModel public required string NavigationHtml { get; init; } public required string? UrlPathPrefix { get; init; } public required string? GithubEditUrl { get; init; } + public required string? ReportIssueUrl { get; init; } public required bool AllowIndexing { get; init; } public required Uri? CanonicalBaseUrl { get; init; } public required bool EnableGoogleTagManager { get; init; } diff --git a/src/docs-builder/Cli/Commands.cs b/src/docs-builder/Cli/Commands.cs index 1e95c4b33..cbc7a4f0b 100644 --- a/src/docs-builder/Cli/Commands.cs +++ b/src/docs-builder/Cli/Commands.cs @@ -104,7 +104,9 @@ public async Task Generate( Uri? canonicalBaseUri = null; - if (canonicalBaseUrl != null && !Uri.TryCreate(canonicalBaseUrl, UriKind.Absolute, out canonicalBaseUri)) + if (canonicalBaseUrl is null) + canonicalBaseUri = new Uri("https://docs-v3-preview.elastic.dev"); + else if (!Uri.TryCreate(canonicalBaseUrl, UriKind.Absolute, out canonicalBaseUri)) throw new ArgumentException($"The canonical base url '{canonicalBaseUrl}' is not a valid absolute uri"); try diff --git a/src/docs-builder/Http/DocumentationWebHost.cs b/src/docs-builder/Http/DocumentationWebHost.cs index f08fdef7b..1d2fe4f03 100644 --- a/src/docs-builder/Http/DocumentationWebHost.cs +++ b/src/docs-builder/Http/DocumentationWebHost.cs @@ -36,7 +36,13 @@ public DocumentationWebHost(string? path, int port, ILoggerFactory logger, IFile .AddFilter("Microsoft.Hosting.Lifetime", LogLevel.Information); var collector = new LiveModeDiagnosticsCollector(logger); - _context = new BuildContext(collector, fileSystem, fileSystem, path, null); + + var hostUrl = $"http://localhost:{port}"; + + _context = new BuildContext(collector, fileSystem, fileSystem, path, null) + { + CanonicalBaseUrl = new Uri(hostUrl), + }; _ = builder.Services .AddAotLiveReload(s => { @@ -51,7 +57,7 @@ public DocumentationWebHost(string? path, int port, ILoggerFactory logger, IFile if (IsDotNetWatchBuild()) _ = builder.Services.AddHostedService(); - _ = builder.WebHost.UseUrls($"http://localhost:{port}"); + _ = builder.WebHost.UseUrls(hostUrl); _webApplication = builder.Build(); SetUpRoutes(); From 1c30ef60fc9eee96390fd9a730837ba3fc19f55f Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Mon, 24 Mar 2025 03:02:07 -0300 Subject: [PATCH 5/9] Sanitize reportLinkParameter creation. Fix tests. --- src/Elastic.Markdown/Slices/HtmlWriter.cs | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs index de2040e1e..d0585f583 100644 --- a/src/Elastic.Markdown/Slices/HtmlWriter.cs +++ b/src/Elastic.Markdown/Slices/HtmlWriter.cs @@ -98,7 +98,9 @@ private async Task RenderLayout(MarkdownFile markdown, MarkdownDocument editUrl = $"https://github.com/elastic/{remote}/edit/{branch}/{path}"; } - var reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl!, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); + Uri? reportLinkParameter = null; + if (DocumentationSet.Build.CanonicalBaseUrl is not null) + reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl!, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); var reportUrl = $"https://github.com/elastic/docs-content/issues/new?template=issue_report.yaml&link={reportLinkParameter}&labels=source:web"; var slice = Index.Create(new IndexViewModel From a0cf822f65a9065f774e77a612a41804b7fa0550 Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Mon, 24 Mar 2025 03:02:35 -0300 Subject: [PATCH 6/9] Typo --- src/Elastic.Markdown/Slices/HtmlWriter.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs index d0585f583..9cadd0c56 100644 --- a/src/Elastic.Markdown/Slices/HtmlWriter.cs +++ b/src/Elastic.Markdown/Slices/HtmlWriter.cs @@ -100,7 +100,7 @@ private async Task RenderLayout(MarkdownFile markdown, MarkdownDocument Uri? reportLinkParameter = null; if (DocumentationSet.Build.CanonicalBaseUrl is not null) - reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl!, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); + reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); var reportUrl = $"https://github.com/elastic/docs-content/issues/new?template=issue_report.yaml&link={reportLinkParameter}&labels=source:web"; var slice = Index.Create(new IndexViewModel From a87b04dbd9a75c5fb738fa4006fd29c9871fd3d7 Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Tue, 25 Mar 2025 01:38:27 -0300 Subject: [PATCH 7/9] Remove link arrows on TableOfContents. --- .../Slices/Layout/_TableOfContents.cshtml | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml index 1ee5906aa..283088975 100644 --- a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml +++ b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml @@ -34,10 +34,6 @@ Edit this page - - -
@@ -47,10 +43,6 @@ Report an issue - - -
} From c7dfac14e4c2afea097c9a537ed7bece2bc05ee6 Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Tue, 25 Mar 2025 10:14:33 -0300 Subject: [PATCH 8/9] Fix issue report path and set links to open in a new tab --- src/Elastic.Markdown/Slices/HtmlWriter.cs | 2 +- src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs index dbe7ecefb..382e2468d 100644 --- a/src/Elastic.Markdown/Slices/HtmlWriter.cs +++ b/src/Elastic.Markdown/Slices/HtmlWriter.cs @@ -102,7 +102,7 @@ private async Task RenderLayout(MarkdownFile markdown, MarkdownDocument Uri? reportLinkParameter = null; if (DocumentationSet.Build.CanonicalBaseUrl is not null) reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); - var reportUrl = $"https://github.com/elastic/docs-content/issues/new?template=issue_report.yaml&link={reportLinkParameter}&labels=source:web"; + var reportUrl = $"https://github.com/elastic/docs-content/issues/new?template=issue-report.yaml&link={reportLinkParameter}&labels=source:web"; var slice = Index.Create(new IndexViewModel { diff --git a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml index 283088975..c7e37853d 100644 --- a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml +++ b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml @@ -26,18 +26,17 @@ @if (Model.GithubEditUrl is not null) {
- + - Edit this page
- + From 2e1adb3764edb4b37175e7430706248223a3a22e Mon Sep 17 00:00:00 2001 From: Felipe Cotti Date: Tue, 25 Mar 2025 10:45:06 -0300 Subject: [PATCH 9/9] Fix merge formatting --- src/Elastic.Markdown/Slices/HtmlWriter.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs index d23622bf0..57129b28d 100644 --- a/src/Elastic.Markdown/Slices/HtmlWriter.cs +++ b/src/Elastic.Markdown/Slices/HtmlWriter.cs @@ -104,7 +104,7 @@ private async Task RenderLayout(MarkdownFile markdown, MarkdownDocument reportLinkParameter = new Uri(DocumentationSet.Build.CanonicalBaseUrl, Path.Combine(DocumentationSet.Build.UrlPathPrefix ?? string.Empty, markdown.Url)); var reportUrl = $"https://github.com/elastic/docs-content/issues/new?template=issue-report.yaml&link={reportLinkParameter}&labels=source:web"; - var siteName = DocumentationSet.Tree.Index?.Title ?? "Elastic Documentation"; + var siteName = DocumentationSet.Tree.Index?.Title ?? "Elastic Documentation"; var slice = Index.Create(new IndexViewModel {