Merge branch 'main' into fix/directive-syntax

Mpdreamz · Mpdreamz · commit 1b61f91e976f · 2025-01-14T22:19:33.000+01:00
diff --git a/docs/source/contribute/on-the-web.md b/docs/source/contribute/on-the-web.md
@@ -2,10 +2,6 @@
 title: Contribute on the web
 ---
 
-:::{warning}
-This feature is not supported yet. See [#171](https://github.com/elastic/docs-builder/issues/171) for more information.
-:::
-
 1. On the right side of the page you want to edit, select **Edit this page**.
 1. Do something on GitHub.
 1. Take the dog for a walk.
diff --git a/docs/source/syntax/_snippets/reusable-snippet.md b/docs/source/syntax/_snippets/reusable-snippet.md
diff --git a/docs/source/syntax/_snippets/unused-snippet.md b/docs/source/syntax/_snippets/unused-snippet.md
@@ -0,0 +1,5 @@
+This snippet is not included anywhere
+
+```{warning}
+This snippet is not included anywhere
+```
diff --git a/docs/source/syntax/file_inclusion.md b/docs/source/syntax/file_inclusion.md
@@ -12,11 +12,11 @@ If there are portions of content that are relevant to multiple pages, you can in
 ### Syntax
 
 ```markdown
-:::{include} _snippets/my_snippet.md
+:::{include} _snippets/reusable-snippet.md
 :::
 ```
 
-:::{include} _snippets/my_snippet.md
+:::{include} _snippets/reusable-snippet.md
 :::
 
 ### Asciidoc syntax
diff --git a/src/Elastic.Markdown/IO/Discovery/GitCheckoutInformation.cs b/src/Elastic.Markdown/IO/Discovery/GitCheckoutInformation.cs
@@ -10,11 +10,14 @@ namespace Elastic.Markdown.IO.Discovery;
 
 public record GitCheckoutInformation
 {
+	private string? _repositoryName;
+
 	private static GitCheckoutInformation Unavailable { get; } = new()
 	{
 		Branch = "unavailable",
 		Remote = "unavailable",
-		Ref = "unavailable"
+		Ref = "unavailable",
+		RepositoryName = "unavailable"
 	};
 
 	[JsonPropertyName("branch")]
@@ -26,14 +29,27 @@ public record GitCheckoutInformation
 	[JsonPropertyName("ref")]
 	public required string Ref { get; init; }
 
+	[JsonIgnore]
+	public string? RepositoryName
+	{
+		get => _repositoryName ??= Remote.Split('/').Last();
+		set => _repositoryName = value;
+	}
+
 	// manual read because libgit2sharp is not yet AOT ready
 	public static GitCheckoutInformation Create(IFileSystem fileSystem)
 	{
 		// filesystem is not real so return a dummy
 		if (fileSystem is not FileSystem)
 		{
 			var fakeRef = Guid.NewGuid().ToString().Substring(0, 16);
-			return new GitCheckoutInformation { Branch = $"test-{fakeRef}", Remote = "elastic/docs-builder", Ref = fakeRef, };
+			return new GitCheckoutInformation
+			{
+				Branch = $"test-{fakeRef}",
+				Remote = "elastic/docs-builder",
+				Ref = fakeRef,
+				RepositoryName = "docs-builder"
+			};
 		}
 
 		var gitConfig = Git(".git/config");
@@ -66,7 +82,15 @@ public static GitCheckoutInformation Create(IFileSystem fileSystem)
 		if (string.IsNullOrEmpty(remote))
 			remote = Environment.GetEnvironmentVariable("GITHUB_REPOSITORY") ?? "elastic/docs-builder-unknown";
 
-		return new GitCheckoutInformation { Ref = gitRef, Branch = branch, Remote = remote };
+		remote = remote.AsSpan().TrimEnd(".git").ToString();
+
+		return new GitCheckoutInformation
+		{
+			Ref = gitRef,
+			Branch = branch,
+			Remote = remote,
+			RepositoryName = remote.Split('/').Last()
+		};
 
 		IFileInfo Git(string path) => fileSystem.FileInfo.New(Path.Combine(Paths.Root.FullName, path));
 
@@ -80,7 +104,7 @@ string BranchTrackingRemote(string b, IniFile c)
 			if (!sections.Contains(branchSection))
 				return string.Empty;
 
-			var remoteName = ini.GetSetting(branchSection, "remote");
+			var remoteName = ini.GetSetting(branchSection, "remote")?.Trim();
 
 			var remoteSection = $"remote \"{remoteName}\"";
 
diff --git a/src/Elastic.Markdown/IO/DocumentationFile.cs b/src/Elastic.Markdown/IO/DocumentationFile.cs
@@ -19,3 +19,6 @@ public record StaticFile(IFileInfo SourceFile, IDirectoryInfo RootPath)
 
 public record ExcludedFile(IFileInfo SourceFile, IDirectoryInfo RootPath)
 	: DocumentationFile(SourceFile, RootPath);
+
+public record SnippetFile(IFileInfo SourceFile, IDirectoryInfo RootPath)
+	: DocumentationFile(SourceFile, RootPath);
diff --git a/src/Elastic.Markdown/IO/DocumentationSet.cs b/src/Elastic.Markdown/IO/DocumentationSet.cs
@@ -20,6 +20,8 @@ public class DocumentationSet
 	public IDirectoryInfo SourcePath { get; }
 	public IDirectoryInfo OutputPath { get; }
 
+	public string RelativeSourcePath { get; }
+
 	public DateTimeOffset LastWrite { get; }
 
 	public ConfigurationFile Configuration { get; }
@@ -31,6 +33,7 @@ public DocumentationSet(BuildContext context)
 		Context = context;
 		SourcePath = context.SourcePath;
 		OutputPath = context.OutputPath;
+		RelativeSourcePath = Path.GetRelativePath(Paths.Root.FullName, SourcePath.FullName);
 		Configuration = new ConfigurationFile(context.ConfigurationPath, SourcePath, context);
 
 		MarkdownParser = new MarkdownParser(SourcePath, context, GetMarkdownFile, Configuration);
@@ -87,6 +90,11 @@ private DocumentationFile CreateMarkDownFile(IFileInfo file, BuildContext contex
 		if (Configuration.Globs.Any(g => g.IsMatch(relativePath)))
 			return new MarkdownFile(file, SourcePath, MarkdownParser, context);
 
+		// we ignore files in folders that start with an underscore
+		if (relativePath.IndexOf("_snippets", StringComparison.Ordinal) >= 0)
+			return new SnippetFile(file, SourcePath);
+
+		// we ignore files in folders that start with an underscore
 		if (relativePath.IndexOf("/_", StringComparison.Ordinal) > 0 || relativePath.StartsWith("_"))
 			return new ExcludedFile(file, SourcePath);
 
diff --git a/src/Elastic.Markdown/Myst/Directives/IncludeBlock.cs b/src/Elastic.Markdown/Myst/Directives/IncludeBlock.cs
@@ -71,5 +71,24 @@ private void ExtractInclusionPath(ParserContext context)
 			Found = true;
 		else
 			this.EmitError($"`{IncludePath}` does not exist.");
+
+		// literal includes may point to locations other than `_snippets` since they do not
+		// participate in emitting links
+		if (Literal)
+			return;
+
+		var file = FileSystem.FileInfo.New(IncludePath);
+
+		if (file.Directory != null && file.Directory.FullName.IndexOf("_snippets", StringComparison.Ordinal) < 0)
+		{
+			this.EmitError($"{{include}} only supports including snippets from `_snippet` folders. `{IncludePath}` is not a snippet");
+			Found = false;
+		}
+
+		if (file.FullName == context.Path.FullName)
+		{
+			this.EmitError($"{{include}} cyclical include detected `{IncludePath}` points to itself");
+			Found = false;
+		}
 	}
 }
diff --git a/src/Elastic.Markdown/Slices/HtmlWriter.cs b/src/Elastic.Markdown/Slices/HtmlWriter.cs
@@ -47,6 +47,11 @@ public async Task<string> RenderLayout(MarkdownFile markdown, Cancel ctx = defau
 
 		var previous = DocumentationSet;
 
+		var remote = DocumentationSet.Context.Git.RepositoryName;
+		var branch = DocumentationSet.Context.Git.Branch;
+		var path = Path.Combine(DocumentationSet.RelativeSourcePath, markdown.RelativePath);
+		var editUrl = $"https://github.com/elastic/{remote}/edit/{branch}/{path}";
+
 		var slice = Index.Create(new IndexViewModel
 		{
 			Title = markdown.Title ?? "[TITLE NOT SET]",
@@ -56,7 +61,8 @@ public async Task<string> RenderLayout(MarkdownFile markdown, Cancel ctx = defau
 			CurrentDocument = markdown,
 			NavigationHtml = navigationHtml,
 			UrlPathPrefix = markdown.UrlPathPrefix,
-			Applies = markdown.YamlFrontMatter?.AppliesTo
+			Applies = markdown.YamlFrontMatter?.AppliesTo,
+			GithubEditUrl = editUrl
 		});
 		return await slice.RenderAsync(cancellationToken: ctx);
 	}
diff --git a/src/Elastic.Markdown/Slices/Index.cshtml b/src/Elastic.Markdown/Slices/Index.cshtml
@@ -9,6 +9,7 @@
 		CurrentDocument = Model.CurrentDocument,
 		NavigationHtml = Model.NavigationHtml,
 		UrlPathPrefix = Model.UrlPathPrefix,
+		GithubEditUrl = Model.GithubEditUrl
 	};
 }
 <section id="elastic-docs-v3">
diff --git a/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml b/src/Elastic.Markdown/Slices/Layout/_TableOfContents.cshtml
@@ -14,7 +14,7 @@
 			</ul>
 		</div>
 		<div class="edit-this-page">
-			<a href="https://github.com/elastic/markitpy-samples/blob/master/docs/source/index.md">Edit this page</a>
+			<a href="@Model.GithubEditUrl">Edit this page</a>
 		</div>
 	</div>
 </aside>
diff --git a/src/Elastic.Markdown/Slices/_ViewModels.cs b/src/Elastic.Markdown/Slices/_ViewModels.cs
@@ -16,6 +16,7 @@ public class IndexViewModel
 	public required MarkdownFile CurrentDocument { get; init; }
 	public required string NavigationHtml { get; init; }
 	public required string? UrlPathPrefix { get; init; }
+	public required string? GithubEditUrl { get; init; }
 	public required Deployment? Applies { get; init; }
 }
 
@@ -27,6 +28,7 @@ public class LayoutViewModel
 	public required MarkdownFile CurrentDocument { get; init; }
 	public required string NavigationHtml { get; set; }
 	public required string? UrlPathPrefix { get; set; }
+	public required string? GithubEditUrl { get; set; }
 
 	private MarkdownFile[]? _parents;
 	public MarkdownFile[] Parents
diff --git a/tests/Elastic.Markdown.Tests/DocSet/LinkReferenceTests.cs b/tests/Elastic.Markdown.Tests/DocSet/LinkReferenceTests.cs
@@ -10,15 +10,23 @@
 
 namespace Elastic.Markdown.Tests.DocSet;
 
-public class LinkReferenceTests(ITestOutputHelper output) : NavigationTestsBase(output)
+public class LinkReferenceTests : NavigationTestsBase
 {
+	public LinkReferenceTests(ITestOutputHelper output) : base(output) => Reference = LinkReference.Create(Set);
+
+	private LinkReference Reference { get; }
+
 	[Fact]
-	public void Create()
-	{
-		var reference = LinkReference.Create(Set);
+	public void ShouldNotBeNull() =>
+		Reference.Should().NotBeNull();
 
-		reference.Should().NotBeNull();
-	}
+	[Fact]
+	public void EmitsLinks() =>
+		Reference.Links.Should().NotBeNullOrEmpty();
+
+	[Fact]
+	public void ShouldNotIncludeSnippets() =>
+		Reference.Links.Should().NotContain(l => l.Contains("_snippets/"));
 }
 
 public class GitCheckoutInformationTests(ITestOutputHelper output) : NavigationTestsBase(output)
@@ -34,5 +42,8 @@ public void Create()
 		git.Branch.Should().NotContain(git.Ref);
 		git.Ref.Should().NotBeNullOrWhiteSpace();
 		git.Remote.Should().NotBeNullOrWhiteSpace();
+		git.Remote.Should().NotContain("unknown");
+		git.RepositoryName.Should().NotContain(".git");
+		git.Remote.Should().NotContain(".git");
 	}
 }
diff --git a/tests/Elastic.Markdown.Tests/FileInclusion/IncludeTests.cs b/tests/Elastic.Markdown.Tests/FileInclusion/IncludeTests.cs
@@ -114,3 +114,70 @@ public void EmitsError()
 			.OnlyContain(d => d.Message.Contains("include requires an argument."));
 	}
 }
+
+public class IncludeNeedsToLiveInSpecialFolder(ITestOutputHelper output) : DirectiveTest<IncludeBlock>(output,
+"""
+```{include} test.md
+```
+"""
+)
+{
+
+	protected override void AddToFileSystem(MockFileSystem fileSystem)
+	{
+		// language=markdown
+		var inclusion = "*Hello world*";
+		fileSystem.AddFile(@"docs/source/test.md", inclusion);
+	}
+
+	[Fact]
+	public void ParsesBlock() => Block.Should().NotBeNull();
+
+	[Fact]
+	public void IncludesNothing() => Html.Should().Be("");
+
+	[Fact]
+	public void EmitsError()
+	{
+		Collector.Diagnostics.Should().NotBeNullOrEmpty().And.HaveCount(1);
+		Collector.Diagnostics.Should().OnlyContain(d => d.Severity == Severity.Error);
+		Collector.Diagnostics.Should()
+			.OnlyContain(d => d.Message.Contains("only supports including snippets from `_snippet` folders."));
+	}
+}
+
+
+public class CanNotIncludeItself(ITestOutputHelper output) : DirectiveTest<IncludeBlock>(output,
+"""
+```{include} _snippets/test.md
+```
+"""
+)
+{
+
+	protected override void AddToFileSystem(MockFileSystem fileSystem)
+	{
+		// language=markdown
+		var inclusion =
+"""
+:::{include} test.md
+:::
+""";
+		fileSystem.AddFile(@"docs/source/_snippets/test.md", inclusion);
+	}
+
+	[Fact]
+	public void ParsesBlock() => Block.Should().NotBeNull();
+
+	[Fact]
+	public void IncludesNothing() => Html.Should().Be("");
+
+	[Fact]
+	public void EmitsError()
+	{
+		Collector.Diagnostics.Should().NotBeNullOrEmpty().And.HaveCount(1);
+		Collector.Diagnostics.Should().OnlyContain(d => d.Severity == Severity.Error);
+		Collector.Diagnostics.Should()
+			.OnlyContain(d => d.Message.Contains("cyclical include detected"));
+	}
+}

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@`
`9`	`9`	`CurrentDocument = Model.CurrentDocument,`
`10`	`10`	`NavigationHtml = Model.NavigationHtml,`
`11`	`11`	`UrlPathPrefix = Model.UrlPathPrefix,`
	`12`	`+ GithubEditUrl = Model.GithubEditUrl`
`12`	`13`	`};`
`13`	`14`	`}`
`14`	`15`	`<section id="elastic-docs-v3">`