Add Text Content Rendering Support for Alerts

Author: rdestefa

CHANGELOG.md

@@ -8,20 +8,20 @@ with the exception that 0.x versions can break between minor versions.
 
 ## [Unreleased]
 ### Added
-- Support rendering GFM task list items to Markdown
-- Support rendering YAML front matter to Markdown
+- Support rendering GFM task list items to Markdown (#433)
+- Support rendering YAML front matter to Markdown (#434)
 - Alerts
-  - Allow customizing HTML attributes for alert title `<p>` tag via `AttributeProvider`
+  - Allow customizing HTML attributes for alert title `<p>` tag via `AttributeProvider` (#427)
   - New configuration for `AlertsExtension` to allow authors to provide custom
     titles per alert. See the
     [custom titles section of the alerts README](./commonmark-ext-gfm-alerts/README.md#custom-alert-titles)
-    for more information.
+    for more information. (#430)
   - New configuration for `AlertsExtension` to allow alerts to be nested within
     other blocks (including other alerts). See
     [this section of the alerts README](./commonmark-ext-gfm-alerts/README.md#nesting-alerts)
-    for more information.
+    for more information. (#430)
   - New configuration for `AlertsExtension` to allow the set of alert types
-    (including standard GFM types) to be completely overwritten.
+    (including standard GFM types) to be completely overwritten. (#435)
     ```java
     var extension = AlertsExtension.builder()
             .setAllowedTypes(Map.ofEntries(
@@ -31,6 +31,8 @@ with the exception that 0.x versions can break between minor versions.
             ))
             .build();
     ```
+  - Support rendering alerts to text (#437)
+
 
 ## [0.28.0] - 2026-03-31
 ### Added

commonmark-ext-gfm-alerts/src/main/java/org/commonmark/ext/gfm/alerts/Alert.java

@@ -18,4 +18,43 @@ public Alert(String type) {
     public String getType() {
         return type;
     }
+
+    /**
+     * @return Whether this alert has any body content (not including the title).
+     * <p>
+     *
+     * - Examples where this would be {@code true}:
+     *   <pre>{@code
+     *   > [!NOTE]
+     *   > Body text
+     *   }</pre>
+     *   <pre>{@code
+     *   > [!NOTE] Custom title
+     *   > Body text
+     *   }</pre>
+     *
+     * - Examples where this would be {@code false}:
+     *
+     *   <pre>{@code
+     *   > [!NOTE]
+     *   }</pre>
+     *   <pre>{@code
+     *   > [!NOTE]
+     *   >
+     *   >
+     *   }</pre>
+     *   <pre>{@code
+     *   > [!NOTE] Custom title
+     *   }</pre>
+     */
+    public boolean hasBody() {
+        var first = this.getFirstChild();
+        if (first instanceof AlertTitle) {
+            // Body exists if there's a sibling after AlertTitle
+            return first.getNext() != null;
+        } else {
+            // Body exists if there are any children
+            return first != null;
+        }
+    }
 }

commonmark-ext-gfm-alerts/src/main/java/org/commonmark/ext/gfm/alerts/AlertsExtension.java

@@ -4,12 +4,14 @@
 import org.commonmark.ext.gfm.alerts.internal.AlertBlockParser;
 import org.commonmark.ext.gfm.alerts.internal.AlertHtmlNodeRenderer;
 import org.commonmark.ext.gfm.alerts.internal.AlertMarkdownNodeRenderer;
+import org.commonmark.ext.gfm.alerts.internal.AlertTextContentNodeRenderer;
 import org.commonmark.parser.Parser;
 import org.commonmark.renderer.NodeRenderer;
 import org.commonmark.renderer.html.HtmlRenderer;
 import org.commonmark.renderer.markdown.MarkdownNodeRendererContext;
 import org.commonmark.renderer.markdown.MarkdownNodeRendererFactory;
 import org.commonmark.renderer.markdown.MarkdownRenderer;
+import org.commonmark.renderer.text.TextContentRenderer;
 
 import java.util.HashMap;
 import java.util.Locale;
@@ -48,7 +50,7 @@
  *   }</pre>
  */
 public class AlertsExtension implements Parser.ParserExtension, HtmlRenderer.HtmlRendererExtension,
-        MarkdownRenderer.MarkdownRendererExtension {
+        TextContentRenderer.TextContentRendererExtension, MarkdownRenderer.MarkdownRendererExtension {
 
     /**
      * The standard GitHub Flavored Markdown (GFM) types that the extension
@@ -95,6 +97,11 @@ public void extend(HtmlRenderer.Builder rendererBuilder) {
         rendererBuilder.nodeRendererFactory(context -> new AlertHtmlNodeRenderer(context, allowedTypes));
     }
 
+    @Override
+    public void extend(TextContentRenderer.Builder rendererBuilder) {
+        rendererBuilder.nodeRendererFactory(context -> new AlertTextContentNodeRenderer(context, allowedTypes));
+    }
+
     @Override
     public void extend(MarkdownRenderer.Builder rendererBuilder) {
         rendererBuilder.nodeRendererFactory(new MarkdownNodeRendererFactory() {

commonmark-ext-gfm-alerts/src/main/java/org/commonmark/ext/gfm/alerts/internal/AlertHtmlNodeRenderer.java

@@ -24,6 +24,9 @@ public AlertHtmlNodeRenderer(HtmlNodeRendererContext context, Map<String, String
     @Override
     protected void renderAlert(Alert alert) {
         var type = alert.getType();
+        if (!allowedTypes.containsKey(type)) {
+            throw new IllegalStateException("Unknown alert type: " + type);
+        }
         var cssClass = type.toLowerCase();
 
         htmlWriter.line();
@@ -40,7 +43,7 @@ protected void renderAlert(Alert alert) {
         if (first instanceof AlertTitle) {
             renderChildren(first);
         } else {
-            htmlWriter.text(getAlertTitle(type));
+            htmlWriter.text(allowedTypes.get(type));
         }
         htmlWriter.tag("/p");
         htmlWriter.line();
@@ -52,24 +55,8 @@ protected void renderAlert(Alert alert) {
         htmlWriter.line();
     }
 
-    private String getAlertTitle(String type) {
-        var typeTitle = allowedTypes.get(type);
-        if (typeTitle == null) {
-            throw new IllegalStateException("Unknown alert type: " + type);
-        }
-        return typeTitle;
-    }
-
-    private void renderChildren(Node parent) {
-        var node = parent.getFirstChild();
-        while (node != null) {
-            var next = node.getNext();
-
-            // AlertTitle is rendered separately from other nodes.
-            if (!(node instanceof AlertTitle)) {
-                context.render(node);
-            }
-            node = next;
-        }
+    @Override
+    protected void renderNode(Node node) {
+        context.render(node);
     }
 }

commonmark-ext-gfm-alerts/src/main/java/org/commonmark/ext/gfm/alerts/internal/AlertMarkdownNodeRenderer.java

@@ -30,22 +30,17 @@ protected void renderAlert(Alert alert) {
             renderChildren(first);
         }
 
-        writer.line();
-        renderChildren(alert);
+        if (alert.hasBody()) {
+            writer.line();
+            renderChildren(alert);
+        }
+
         writer.popPrefix();
         writer.block();
     }
 
-    private void renderChildren(Node parent) {
-        var node = parent.getFirstChild();
-        while (node != null) {
-            var next = node.getNext();
-
-            // AlertTitle is rendered separately from other nodes.
-            if (!(node instanceof AlertTitle)) {
-                context.render(node);
-            }
-            node = next;
-        }
+    @Override
+    protected void renderNode(Node node) {
+        context.render(node);
     }
 }

commonmark-ext-gfm-alerts/src/main/java/org/commonmark/ext/gfm/alerts/internal/AlertNodeRenderer.java

@@ -1,6 +1,7 @@
 package org.commonmark.ext.gfm.alerts.internal;
 
 import org.commonmark.ext.gfm.alerts.Alert;
+import org.commonmark.ext.gfm.alerts.AlertTitle;
 import org.commonmark.node.Node;
 import org.commonmark.renderer.NodeRenderer;
 
@@ -20,4 +21,31 @@ public void render(Node node) {
     }
 
     protected abstract void renderAlert(Alert alert);
+
+    /**
+     * Renders the children of a parent node, excluding AlertTitle nodes.
+     * AlertTitle is rendered separately from other content.
+     *
+     * @param parent the parent node whose children should be rendered
+     */
+    protected final void renderChildren(Node parent) {
+        var node = parent.getFirstChild();
+        while (node != null) {
+            var next = node.getNext();
+
+            // AlertTitle is rendered separately from other nodes.
+            if (!(node instanceof AlertTitle)) {
+                renderNode(node);
+            }
+            node = next;
+        }
+    }
+
+    /**
+     * Renders a single node. Subclasses must implement this to delegate
+     * to their context's render method.
+     *
+     * @param node the node to render
+     */
+    protected abstract void renderNode(Node node);
 }

commonmark-ext-gfm-alerts/src/main/java/org/commonmark/ext/gfm/alerts/internal/AlertTextContentNodeRenderer.java

@@ -0,0 +1,54 @@
+package org.commonmark.ext.gfm.alerts.internal;
+
+import org.commonmark.ext.gfm.alerts.Alert;
+import org.commonmark.ext.gfm.alerts.AlertTitle;
+import org.commonmark.node.Node;
+import org.commonmark.renderer.text.LineBreakRendering;
+import org.commonmark.renderer.text.TextContentNodeRendererContext;
+import org.commonmark.renderer.text.TextContentWriter;
+
+import java.util.Map;
+
+public class AlertTextContentNodeRenderer extends AlertNodeRenderer {
+
+    private final TextContentNodeRendererContext context;
+    private final TextContentWriter textContent;
+    private final Map<String, String> allowedTypes;
+
+    public AlertTextContentNodeRenderer(TextContentNodeRendererContext context, Map<String, String> allowedTypes) {
+        this.context = context;
+        this.textContent = context.getWriter();
+        this.allowedTypes = allowedTypes;
+    }
+
+    @Override
+    protected void renderAlert(Alert alert) {
+        var type = alert.getType();
+        if (!allowedTypes.containsKey(type)) {
+            throw new IllegalStateException("Unknown alert type: " + type);
+        }
+
+        var first = alert.getFirstChild();
+        if (first instanceof AlertTitle) {
+            renderChildren(first);
+        } else {
+            textContent.write(allowedTypes.get(type));
+        }
+
+        if (alert.hasBody()) {
+            if (context.lineBreakRendering() == LineBreakRendering.STRIP) {
+                textContent.write(": ");
+            } else {
+                textContent.block();
+            }
+            renderChildren(alert);
+        }
+
+        textContent.block();
+    }
+
+    @Override
+    protected void renderNode(Node node) {
+        context.render(node);
+    }
+}

commonmark-ext-gfm-alerts/src/test/java/org/commonmark/ext/gfm/alerts/AlertsMarkdownRendererTest.java

@@ -78,6 +78,18 @@ public void alertWithList() {
         assertRoundTrip(input);
     }
 
+    @Test
+    public void alertNoBody() {
+        var input = "> [!NOTE]\n";
+        assertRoundTrip(input);
+    }
+
+    @Test
+    public void alertNoBodyOtherBlocks() {
+        var input = "- List\n\n> [!NOTE]\n\n- List\n";
+        assertRoundTrip(input);
+    }
+
     // Custom titles
 
     @Test
@@ -99,6 +111,18 @@ public void customTitleWithMultipleBlocks() {
         assertThat(rendered).isEqualTo(expected);
     }
 
+    @Test
+    public void customTitleNoBody() {
+        var input = "> [!WARNING] Custom title\n";
+        assertRoundTripCustomTitles(input);
+    }
+
+    @Test
+    public void customTitleNoBodyOtherBlocks() {
+        var input = "1. Ordered list\n\n> [!WARNING] Custom title\n\n1. Ordered list\n";
+        assertRoundTripCustomTitles(input);
+    }
+
     // Helpers
 
     private void assertRoundTrip(String input, Parser parser, MarkdownRenderer renderer) {