Add support for multiple line comments (#940)

* Add support for comment blocks spanning multiple lines

* Improve documentation on the feature

Author: cotti

docs/syntax/comments.md

@@ -1,7 +1,5 @@
 # Comments
 
-Elastic docs V3 currently only supports single-line comments.
-
 ## Single line comments
 
 Use `%` to add single-line comments.
@@ -10,4 +8,17 @@ Use `%` to add single-line comments.
 % This is a comment
 ```
 
-Make sure to add a space after the `%`.
+Make sure to add a space after the `%`.
+
+## Multiline comments
+
+Use `<!--` and `-->` to add multiple line comment blocks.
+
+```markdown
+- There is a commented section below.
+<!--
+This section should not appear -
+Neither should this line.
+-->
+- And there is a commented section above.
+```

src/Elastic.Markdown/Myst/Comments/CommentMarkdownExtension.cs

@@ -22,6 +22,8 @@ public void Setup(MarkdownPipelineBuilder pipeline)
 	{
 		if (!pipeline.BlockParsers.Contains<CommentBlockParser>())
 			_ = pipeline.BlockParsers.InsertBefore<ThematicBreakParser>(new CommentBlockParser());
+		if (!pipeline.BlockParsers.Contains<MultipleLineCommentBlockParser>())
+			_ = pipeline.BlockParsers.InsertBefore<ThematicBreakParser>(new MultipleLineCommentBlockParser());
 	}
 
 	public void Setup(MarkdownPipeline pipeline, IMarkdownRenderer renderer)

src/Elastic.Markdown/Myst/Comments/MultipleLineCommentBlockParser.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.Diagnostics;
+using Markdig.Parsers;
+using Markdig.Syntax;
+
+namespace Elastic.Markdown.Myst.Comments;
+
+[DebuggerDisplay("{GetType().Name} Line: {Line}, {Lines}")]
+public class MultipleLineCommentBlock(BlockParser parser) : LeafBlock(parser);
+
+public class MultipleLineCommentBlockParser : BlockParser
+{
+	public MultipleLineCommentBlockParser() => OpeningCharacters = ['<'];
+
+	private const string BlockStart = "<!--";
+	private const string BlockEnd = "-->";
+
+	public override BlockState TryOpen(BlockProcessor processor)
+	{
+		var currentLine = processor.Line;
+		if (currentLine.Match(BlockStart))
+		{
+			var block = new MultipleLineCommentBlock(this)
+			{
+				Column = processor.Column,
+				Span =
+				{
+					Start = processor.Start
+				}
+			};
+			processor.NewBlocks.Push(block);
+			processor.GoToColumn(currentLine.End);
+			return BlockState.Continue;
+		}
+		return BlockState.None;
+	}
+
+	public override BlockState TryContinue(BlockProcessor processor, Block block)
+	{
+		var currentLine = processor.Line;
+
+		if (!currentLine.Match(BlockEnd))
+			return BlockState.Continue;
+
+		block.UpdateSpanEnd(currentLine.End);
+		return BlockState.BreakDiscard;
+	}
+}

tests/Elastic.Markdown.Tests/Inline/CommentTest.cs

@@ -27,3 +27,75 @@ public void GeneratesAttributesInHtml() =>
 			"""
 		);
 }
+
+public class MultipleLineCommentTest(ITestOutputHelper output) : InlineTest(output,
+	"""
+	not a comment, and multi line comment below
+	<!--
+	multi line comment
+	Another line inside the commented area
+	end of comments
+	-->
+
+	also not a comment
+	"""
+)
+{
+
+	[Fact]
+	public void GeneratesAttributesInHtml() =>
+		// language=html
+		Html.ReplaceLineEndings().Should().NotContainAny(
+				"<p><!--",
+				"<p>Multi line comment, first line",
+				"<p>Another line inside the commented area",
+				"<p>end of comments",
+				"<p>-->")
+			.And.ContainAll(
+				"<p>not a comment, and multi line comment below</p>",
+				"<p>also not a comment</p>"
+			).And.Be(
+				"""
+				<p>not a comment, and multi line comment below</p>
+				<p>also not a comment</p>
+				""".ReplaceLineEndings()
+				);
+}
+
+public class MultipleLineCommentWithLinkTest(ITestOutputHelper output) : InlineTest(output,
+	"""
+	not a comment, and multi line comment below
+	<!--
+	multi line comment
+	[regular link](http://elastic.co/non-existing-link)
+	[global search field]({{this-variable-does-not-exist}}/introduction.html)
+	end of comments
+	-->
+
+	also not a comment
+	"""
+)
+{
+	[Fact]
+	public void HasNoErrors() => Collector.Diagnostics.Should().HaveCount(0);
+
+	[Fact]
+	public void GeneratesAttributesInHtml() =>
+		// language=html
+		Html.ReplaceLineEndings().Should().NotContainAny(
+				"<p><!--",
+				"<p>Multi line comment, first line",
+				"regular link",
+				"global search field",
+				"<p>end of comments",
+				"<p>-->")
+			.And.ContainAll(
+				"<p>not a comment, and multi line comment below</p>",
+				"<p>also not a comment</p>"
+			).And.Be(
+				"""
+					<p>not a comment, and multi line comment below</p>
+					<p>also not a comment</p>
+					""".ReplaceLineEndings()
+			);
+}