Snippets in JSX static site generators

readme.md

@@ -199,6 +199,31 @@ Notes:
  * [H33: Supplementing link text with the title attribute](https://www.w3.org/TR/WCAG20-TECHS/H33.html)
 
 
+### MDX / Link Reference Comment Syntax
+
+When using MDX files (e.g. with [fumadocs](https://fumadocs.dev), [Astro](https://astro.build/), or other JSX-based static site generators), HTML comments (`<!-- -->`) are not supported. An alternative comment syntax using [markdown link reference definitions](https://spec.commonmark.org/0.31.2/#link-reference-definitions) can be used instead:
+
+<pre>
+[//]: # (snippet: MySnippetName)
+[//]: # (endSnippet)
+</pre>
+
+This works the same way as the HTML comment syntax but is compatible with both standard markdown and MDX parsers. When using InPlaceOverwrite convention, the content between the markers will be replaced with the snippet content, and the link reference format will be preserved:
+
+    [//]: # (snippet: MySnippetName)
+    ```cs
+    My Snippet Code
+    ```
+    [//]: # (endSnippet)
+
+This syntax also works for web-snippets:
+
+<pre>
+[//]: # (web-snippet: https://example.com/file.cs#snippetKey)
+[//]: # (endSnippet)
+</pre>
+
+
 ### Including a snippet from the web
 
 Snippets that start with `http` will be downloaded and the contents rendered. For example:

readme.source.md

@@ -192,6 +192,31 @@ Notes:
  * [H33: Supplementing link text with the title attribute](https://www.w3.org/TR/WCAG20-TECHS/H33.html)
 
 
+### MDX / Link Reference Comment Syntax
+
+When using MDX files (e.g. with [fumadocs](https://fumadocs.dev), [Astro](https://astro.build/), or other JSX-based static site generators), HTML comments (`<!-- -->`) are not supported. An alternative comment syntax using [markdown link reference definitions](https://spec.commonmark.org/0.31.2/#link-reference-definitions) can be used instead:
+
+<pre>
+[//]: # (snippet: MySnippetName)
+[//]: # (endSnippet)
+</pre>
+
+This works the same way as the HTML comment syntax but is compatible with both standard markdown and MDX parsers. When using InPlaceOverwrite convention, the content between the markers will be replaced with the snippet content, and the link reference format will be preserved:
+
+    [//]: # (snippet: MySnippetName)
+    ```cs
+    My Snippet Code
+    ```
+    [//]: # (endSnippet)
+
+This syntax also works for web-snippets:
+
+<pre>
+[//]: # (web-snippet: https://example.com/file.cs#snippetKey)
+[//]: # (endSnippet)
+</pre>
+
+
 ### Including a snippet from the web
 
 Snippets that start with `http` will be downloaded and the contents rendered. For example:

src/MarkdownSnippets/Processing/IncludeProcessor.cs

@@ -210,6 +210,7 @@ static IEnumerable<Line> BuildMultiple(Line line, string? path, Include include,
     static bool ShouldWriteIncludeOnDiffLine(string line) =>
         SnippetKey.IsSnippetLine(line) ||
         line.StartsWith("<!-- endSnippet -->") ||
+        line.StartsWith("[//]: # (endSnippet)") ||
         line.EndsWith("```") ||
         line.StartsWith('|') ||
         line.EndsWith('|');

src/MarkdownSnippets/Processing/MarkdownProcessor.cs

@@ -181,20 +181,20 @@ Action<string> CreateIndentedAppendLine(string indent) => s =>
                 continue;
             }
 
-            void AppendSnippet(string key1)
+            void AppendSnippet(string key1, bool useLinkRefFormat = false)
             {
                 builder.Clear();
                 var indentedAppendLine = CreateIndentedAppendLine(line.LeadingWhitespace);
-                ProcessSnippetLine(indentedAppendLine, missingSnippets, usedSnippets, key1, relativePath, line);
+                ProcessSnippetLine(indentedAppendLine, missingSnippets, usedSnippets, key1, relativePath, line, useLinkRefFormat);
                 builder.TrimEnd();
                 line.Current = builder.ToString();
             }
 
-            void AppendWebSnippet(string url, string snippetKey, string? viewUrl = null)
+            void AppendWebSnippet(string url, string snippetKey, string? viewUrl = null, bool useLinkRefFormat = false)
             {
                 builder.Clear();
                 var indentedAppendLine = CreateIndentedAppendLine(line.LeadingWhitespace);
-                ProcessWebSnippetLine(indentedAppendLine, missingSnippets, usedSnippets, url, snippetKey, viewUrl, line);
+                ProcessWebSnippetLine(indentedAppendLine, missingSnippets, usedSnippets, url, snippetKey, viewUrl, line, useLinkRefFormat);
                 builder.TrimEnd();
                 line.Current = builder.ToString();
             }
@@ -244,6 +244,34 @@ void AppendWebSnippet(string url, string snippetKey, string? viewUrl = null)
                 continue;
             }
 
+            if (SnippetKey.ExtractLinkRefCommentSnippet(line, out key))
+            {
+                AppendSnippet(key, useLinkRefFormat: true);
+
+                index++;
+
+                lines.RemoveUntil(
+                    index,
+                    "[//]: # (endSnippet)",
+                    relativePath,
+                    line);
+                continue;
+            }
+
+            if (SnippetKey.ExtractLinkRefCommentWebSnippet(line, out url, out snippetKey, out viewUrl))
+            {
+                AppendWebSnippet(url, snippetKey, viewUrl, useLinkRefFormat: true);
+
+                index++;
+
+                lines.RemoveUntil(
+                    index,
+                    "[//]: # (endSnippet)",
+                    relativePath,
+                    line);
+                continue;
+            }
+
             if (line.Current.TrimStart() == "<!-- toc -->")
             {
                 tocLine = line;
@@ -292,14 +320,16 @@ bool ValidateContent(string? relativePath, Line line, List<ValidationError> vali
         return true;
     }
 
-    void ProcessSnippetLine(Action<string> appendLine, List<MissingSnippet> missings, List<Snippet> used, string key, string? relativePath, Line line)
+    void ProcessSnippetLine(Action<string> appendLine, List<MissingSnippet> missings, List<Snippet> used, string key, string? relativePath, Line line, bool useLinkRefFormat = false)
     {
-        appendLine($"<!-- snippet: {key} -->");
+        var startMarker = useLinkRefFormat ? $"[//]: # (snippet: {key})" : $"<!-- snippet: {key} -->";
+        var endMarker = useLinkRefFormat ? "[//]: # (endSnippet)" : "<!-- endSnippet -->";
+        appendLine(startMarker);
 
         if (TryGetSnippets(key, relativePath, line.Path, out var snippetsForKey))
         {
             appendSnippets(key, snippetsForKey, appendLine);
-            appendLine("<!-- endSnippet -->");
+            appendLine(endMarker);
             used.AddRange(snippetsForKey);
             return;
         }
@@ -309,14 +339,19 @@ void ProcessSnippetLine(Action<string> appendLine, List<MissingSnippet> missings
         appendLine("```");
         appendLine($"** Could not find snippet '{key}' **");
         appendLine("```");
-        appendLine("<!-- endSnippet -->");
+        appendLine(endMarker);
     }
 
-    void ProcessWebSnippetLine(Action<string> appendLine, List<MissingSnippet> missings, List<Snippet> used, string url, string snippetKey, string? viewUrl, Line line)
+    void ProcessWebSnippetLine(Action<string> appendLine, List<MissingSnippet> missings, List<Snippet> used, string url, string snippetKey, string? viewUrl, Line line, bool useLinkRefFormat = false)
     {
-        var commentText = viewUrl == null
-            ? $"<!-- web-snippet: {url}#{snippetKey} -->"
-            : $"<!-- web-snippet: {url}#{snippetKey} {viewUrl} -->";
+        var endMarker = useLinkRefFormat ? "[//]: # (endSnippet)" : "<!-- endSnippet -->";
+        var commentText = useLinkRefFormat
+            ? (viewUrl == null
+                ? $"[//]: # (web-snippet: {url}#{snippetKey})"
+                : $"[//]: # (web-snippet: {url}#{snippetKey} {viewUrl})")
+            : (viewUrl == null
+                ? $"<!-- web-snippet: {url}#{snippetKey} -->"
+                : $"<!-- web-snippet: {url}#{snippetKey} {viewUrl} -->");
         appendLine(commentText);
         // Download file content
         try
@@ -329,7 +364,7 @@ void ProcessWebSnippetLine(Action<string> appendLine, List<MissingSnippet> missi
                 appendLine("```");
                 appendLine($"** Could not fetch or parse web-snippet '{url}#{snippetKey}' **");
                 appendLine("```");
-                appendLine("<!-- endSnippet -->");
+                appendLine(endMarker);
                 return;
             }
             // Extract snippets from content
@@ -343,7 +378,7 @@ void ProcessWebSnippetLine(Action<string> appendLine, List<MissingSnippet> missi
                 appendLine("```");
                 appendLine($"** Could not find snippet '{snippetKey}' in '{url}' **");
                 appendLine("```");
-                appendLine("<!-- endSnippet -->");
+                appendLine(endMarker);
                 return;
             }
             // Create new snippet with viewUrl if provided
@@ -359,7 +394,7 @@ void ProcessWebSnippetLine(Action<string> appendLine, List<MissingSnippet> missi
                     expressiveCode: found.ExpressiveCode,
                     viewUrl: viewUrl);
             appendSnippets(snippetKey, [snippetToAppend], appendLine);
-            appendLine("<!-- endSnippet -->");
+            appendLine(endMarker);
             used.Add(snippetToAppend);
         }
         catch
@@ -369,7 +404,7 @@ void ProcessWebSnippetLine(Action<string> appendLine, List<MissingSnippet> missi
             appendLine("```");
             appendLine($"** Could not fetch or parse web-snippet '{url}#{snippetKey}' **");
             appendLine("```");
-            appendLine("<!-- endSnippet -->");
+            appendLine(endMarker);
         }
     }
 

src/MarkdownSnippets/Processing/SnippetKey.cs

@@ -158,4 +158,86 @@ public static bool IsStartCommentWebSnippetLine(string line) =>
 
     public static bool IsStartCommentWebSnippetLine(CharSpan line) =>
         line.StartsWith("<!-- web-snippet:", StringComparison.OrdinalIgnoreCase);
+
+    // [//]: # (snippet: key) format — link reference comment syntax for MDX compatibility
+
+    public static bool ExtractLinkRefCommentSnippet(Line line, [NotNullWhen(true)] out string? key)
+    {
+        var lineCurrent = line.Current.AsSpan().TrimStart();
+        if (!IsLinkRefCommentSnippetLine(lineCurrent))
+        {
+            key = null;
+            return false;
+        }
+
+        // after "[//]: # (snippet: " = 18 chars
+        var substring = lineCurrent[18..];
+        var indexOf = substring.IndexOf(")", StringComparison.Ordinal);
+        if (indexOf < 0)
+        {
+            throw new SnippetException($"Could not find closing ')' in: {line.Original}. Path: {line.Path}. Line: {line.LineNumber}");
+        }
+
+        key = substring[..indexOf].Trim().ToString();
+        return true;
+    }
+
+    public static bool ExtractLinkRefCommentWebSnippet(Line line, [NotNullWhen(true)] out string? url, [NotNullWhen(true)] out string? snippetKey) =>
+        ExtractLinkRefCommentWebSnippet(line, out url, out snippetKey, out _);
+
+    public static bool ExtractLinkRefCommentWebSnippet(Line line, [NotNullWhen(true)] out string? url, [NotNullWhen(true)] out string? snippetKey, out string? viewUrl)
+    {
+        var lineCurrent = line.Current.AsSpan().TrimStart();
+        if (!IsLinkRefCommentWebSnippetLine(lineCurrent))
+        {
+            url = null;
+            snippetKey = null;
+            viewUrl = null;
+            return false;
+        }
+
+        // after "[//]: # (web-snippet: " = 22 chars
+        var substring = lineCurrent[22..];
+        var indexOf = substring.IndexOf(")", StringComparison.Ordinal);
+        if (indexOf < 0)
+        {
+            throw new SnippetException($"Could not find closing ')' in: {line.Original}. Path: {line.Path}. Line: {line.LineNumber}");
+        }
+
+        var value = substring[..indexOf].Trim();
+
+        // Check for optional second URL separated by whitespace
+        var firstSpaceIndex = value.IndexOfAny([' ', '\t']);
+        CharSpan firstPart;
+        if (firstSpaceIndex >= 0)
+        {
+            firstPart = value[..firstSpaceIndex];
+            var secondPart = value[(firstSpaceIndex + 1)..].TrimStart();
+            var nextSpace = secondPart.IndexOfAny([' ', '\t']);
+            viewUrl = (nextSpace >= 0 ? secondPart[..nextSpace] : secondPart).ToString();
+        }
+        else
+        {
+            firstPart = value;
+            viewUrl = null;
+        }
+
+        var hashIndex = firstPart.LastIndexOf('#');
+        if (hashIndex < 0 || hashIndex == firstPart.Length - 1)
+        {
+            url = null;
+            snippetKey = null;
+            viewUrl = null;
+            return false;
+        }
+        url = firstPart[..hashIndex].ToString();
+        snippetKey = firstPart[(hashIndex + 1)..].ToString();
+        return true;
+    }
+
+    public static bool IsLinkRefCommentSnippetLine(CharSpan line) =>
+        line.StartsWith("[//]: # (snippet:", StringComparison.OrdinalIgnoreCase);
+
+    public static bool IsLinkRefCommentWebSnippetLine(CharSpan line) =>
+        line.StartsWith("[//]: # (web-snippet:", StringComparison.OrdinalIgnoreCase);
 }

src/Tests/MarkdownProcessor/MarkdownProcessorTests.LinkRefComment_Overwrite.verified.txt

@@ -0,0 +1,36 @@
+{
+  UsedSnippets: [
+    {
+      Key: snippet1,
+      Language: cs,
+      Value: Snippet,
+      Error: ,
+      FileLocation: thePath(1-2),
+      IsInError: false
+    },
+    {
+      Key: snippet2,
+      Language: cs,
+      Value: Snippet,
+      Error: ,
+      FileLocation: thePath(1-2),
+      IsInError: false
+    }
+  ],
+  result:
+[//]: # (snippet: snippet1)
+```cs
+Snippet
+```
+[//]: # (endSnippet)
+
+some text
+
+[//]: # (snippet: snippet2)
+```cs
+Snippet
+```
+[//]: # (endSnippet)
+
+some other text
+}

src/Tests/MarkdownProcessor/MarkdownProcessorTests.LinkRefComment_Overwrite_Missing.verified.txt

@@ -0,0 +1,14 @@
+{
+  MissingSnippets: [
+    {
+      Key: missingKey,
+      LineNumber: 2
+    }
+  ],
+  result:
+[//]: # (snippet: missingKey)
+```
+** Could not find snippet 'missingKey' **
+```
+[//]: # (endSnippet)
+}