BREAKING CHANGE: Allow explicit code callout only after a comment

docs/_docset.yml

@@ -102,6 +102,7 @@ toc:
  - folder: nested
  - file: cross-links.md
  - file: custom-highlighters.md
+ - file: code-callouts.md
  - folder: mover
  children:
  - file: first-page.md

docs/syntax/code.md

@@ -39,19 +39,18 @@ There are two ways to add callouts to a code block. When using callouts, you mus
 
 #### Explicit callouts
 
-Add `<\d+>` to the end of a line to explicitly create a code callout.
+Add one or more callouts to a code block by adding a comment (`#` or `//` ) with a callout label at the end of the line. The callout label must be a number enclosed in angle brackets `<>`. 
 
 An ordered list with the same number of items as callouts must follow the code block. If the number of list items doesn’t match the callouts, docs-builder will throw an error.
 
-
 ::::{tab-set}
 
 :::{tab-item} Output
 
 ```yaml
 project:
  license:
- content: CC-BY-4.0 <1>
+ content: CC-BY-4.0 # <1>
 ```
 
 1. The license
@@ -65,7 +64,7 @@ project:
 ```yaml
 project:
  license:
- content: CC-BY-4.0 <1>
+ content: CC-BY-4.0 # <1>
 ```
 
 1. The license

docs/testing/code-callouts.md

@@ -0,0 +1,12 @@
+# Code Callout testing
+
+```plaintext
+This should not be registered as explicit callout <1>
+```
+
+```plaintext
+This should not be registered as explicit callout <1> but the following should // <1> <2>
+```
+
+1. But this is a code callout
+2. This also

src/Elastic.Markdown/Assets/markdown/code.css

@@ -28,7 +28,7 @@
 }
 
 pre code .code-callout {
-@apply ml-1;
+@apply ml-[1ch];
 transform: translateY(-1px);
 user-select: none;
 }
@@ -48,8 +48,9 @@
 }
 }
 
-pre code .code-callout .hljs-number {
-@apply text-white!;
+pre code .code-callout,
+pre code .code-callout>*{
+@apply text-white! text-xs;
 }
 
 pre code .code-callout,

src/Elastic.Markdown/Myst/CodeBlocks/EnhancedCodeBlockParser.cs

@@ -258,12 +258,16 @@ private static List<CallOut> EnumerateAnnotations(Regex.ValueMatchEnumerator mat
 private static List<CallOut> ParseClassicCallOuts(ValueMatch match, ref ReadOnlySpan<char> span, ref int callOutIndex, int originatingLine)
 {
 var indexOfLastComment = Math.Max(span.LastIndexOf(" # "), span.LastIndexOf(" // "));
+
+if (indexOfLastComment == -1)
+return [];
+
 var startIndex = span.LastIndexOf('<');
 if (startIndex <= 0)
 return [];
 
 var allStartIndices = new List<int>();
-for (var i = 0; i < span.Length; i++)
+for (var i = indexOfLastComment; i < span.Length; i++)
 {
 if (span[i] == '<')
 allStartIndices.Add(i);

tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs

@@ -53,9 +53,9 @@ public void ParsesMagicCallOuts() => Block!.CallOuts
 
 public class ClassicCallOutsRequiresContent(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-var x = 1; <1>
+var x = 1; # <1>
 var y = x - 2;
-var z = y - 2; <2>
+var z = y - 2; # <2>
 """
 )
 {
@@ -72,9 +72,9 @@ public void RequiresContentToFollow() => Collector.Diagnostics.Should().HaveCoun
 
 public class ClassicCallOutsNotFollowedByList(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-var x = 1; <1>
+var x = 1; # <1>
 var y = x - 2;
-var z = y - 2; <2>
+var z = y - 2; # <2>
 """,
 """
 ## hello world
@@ -96,9 +96,9 @@ public void RequiresContentToFollow() => Collector.Diagnostics.Should().HaveCoun
 
 public class ClassicCallOutsFollowedByAListWithOneParagraph(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-var x = 1; <1>
+var x = 1; // <1>
 var y = x - 2;
-var z = y - 2; <2>
+var z = y - 2; // <2>
 """,
 """
 
@@ -122,9 +122,9 @@ public void ParsesMagicCallOuts() => Block!.CallOuts
 
 public class ClassicCallOutsFollowedByListButWithTwoParagraphs(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-var x = 1; <1>
+var x = 1; // <1>
 var y = x - 2;
-var z = y - 2; <2>
+var z = y - 2; // <2>
 """,
 """
 
@@ -153,9 +153,9 @@ public void RequiresContentToFollow() => Collector.Diagnostics.Should().HaveCoun
 
 public class ClassicCallOutsFollowedByListWithWrongCoung(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-var x = 1; <1>
+var x = 1; // <1>
 var y = x - 2;
-var z = y - 2; <2>
+var z = y - 2; // <2>
 """,
 """
 1. Only marking the first callout
@@ -176,9 +176,9 @@ public void RequiresContentToFollow() => Collector.Diagnostics.Should().HaveCoun
 
 public class ClassicCallOutsReuseHighlights(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-var x = 1; <1>
-var y = x - 2; <2>
-var z = y - 2; <2>
+var x = 1; // <1>
+var y = x - 2; // <2>
+var z = y - 2; // <2>
 """,
 """
 1. The first
@@ -205,15 +205,15 @@ public void ParsesAllForLineInformation() => Block!.CallOuts
 
 public class ClassicCallOutWithTheRightListItems(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-receivers: <1>
+receivers: # <1>
  # ...
  otlp:
  protocols:
  grpc:
  endpoint: 0.0.0.0:4317
  http:
  endpoint: 0.0.0.0:4318
-processors: <2>
+processors: # <2>
  # ...
  memory_limiter:
  check_interval: 1s
@@ -222,13 +222,13 @@ public class ClassicCallOutWithTheRightListItems(ITestOutputHelper output) : Cod
 
 exporters:
  debug:
- verbosity: detailed <3>
- otlp: <4>
+ verbosity: detailed # <3>
+ otlp: # <4>
  # Elastic APM server https endpoint without the "https://" prefix
- endpoint: "${env:ELASTIC_APM_SERVER_ENDPOINT}" <5> <7>
+ endpoint: "${env:ELASTIC_APM_SERVER_ENDPOINT}" # <5> <7>
  headers:
  # Elastic APM Server secret token
- Authorization: "Bearer ${env:ELASTIC_APM_SECRET_TOKEN}" <6> <7>
+ Authorization: "Bearer ${env:ELASTIC_APM_SECRET_TOKEN}" # <6> <7>
 
 service:
  pipelines:
@@ -240,7 +240,7 @@ public class ClassicCallOutWithTheRightListItems(ITestOutputHelper output) : Cod
  receivers: [otlp]
  processors: [..., memory_limiter, batch]
  exporters: [debug, otlp]
- logs: <8>
+ logs: # <8>
  receivers: [otlp]
  processors: [..., memory_limiter, batch]
  exporters: [debug, otlp]
@@ -299,12 +299,12 @@ public void ParsesMagicCallOuts() => Block!.CallOuts
 
 public class CodeBlockWithChevronInsideCode(ITestOutputHelper output) : CodeBlockCallOutTests(output, "csharp",
 """
-app.UseFilter<StopwatchFilter>(); <1>
-app.UseFilter<CatchExceptionFilter>(); <2>
+app.UseFilter<StopwatchFilter>(); # <1>
+app.UseFilter<CatchExceptionFilter>(); # <2>
 
-var x = 1; <1>
+var x = 1; # <1>
 var y = x - 2;
-var z = y - 2; <1> <2>
+var z = y - 2; # <1> <2>
 """,
 """
 1. First callout