Allow Custom Alert Titles

Author: rdestefa

CHANGELOG.md

@@ -14,7 +14,7 @@ with the exception that 0.x versions can break between minor versions.
 ### Added
 - New extension for alerts (aka callouts/admonitions)
   - Syntax:
-    ```
+    ```markdown
     > [!NOTE]
     > The text of the note.
     ```
@@ -102,9 +102,9 @@ with the exception that 0.x versions can break between minor versions.
 ### Added
 - New extension for footnotes!
   - Syntax:
-    ```
+    ```markdown
     Main text[^1]
-    
+
     [^1]: Additional text in a footnote
     ```
   - Inline footnotes like `^[inline footnote]` are also supported when enabled
@@ -269,7 +269,7 @@ with the exception that 0.x versions can break between minor versions.
   - Use class `ImageAttributesExtension` in artifact `commonmark-ext-image-attributes`
 - Extension for task lists (GitHub-style), thanks @dohertyfjatl
   - Syntax:
-    ```
+    ```markdown
     - [x] task #1
     - [ ] task #2
     ```

commonmark-ext-gfm-alerts/README.md

@@ -6,7 +6,7 @@ Enables highlighting important information using blockquote syntax with five sta
 
 ## Usage
 
-#### Markdown Syntax
+### Markdown Syntax
 
 ```markdown
 > [!NOTE]
@@ -16,15 +16,15 @@ Enables highlighting important information using blockquote syntax with five sta
 > Critical information
 ```
 
-#### Standard GFM Types
+### Standard GFM Types
 
 ```java
 var extension = AlertsExtension.create();
 var parser = Parser.builder().extensions(List.of(extension)).build();
 var renderer = HtmlRenderer.builder().extensions(List.of(extension)).build();
 ```
 
-#### Custom Alert Types
+### Custom Alert Types
 
 Add custom types beyond the five standard GFM types:
 
@@ -36,7 +36,24 @@ var extension = AlertsExtension.builder()
 
 Custom types must be UPPERCASE. Standard type titles can also be overridden for localization.
 
-#### Styling
+### Custom Alert Titles
+
+Allow authors to provide custom titles per alert by adding text after the alert
+marker on the same line:
+
+```java
+var extension = AlertsExtension.builder().allowCustomTitles().build();
+```
+
+```markdown
+> [!NOTE] Keep in mind
+> Useful information
+
+> [!WARNING] Be **very** careful
+> Critical information
+```
+
+### Styling
 
 Alerts render as `<div>` elements with CSS classes:
 
@@ -51,9 +68,9 @@ Basic CSS example:
 
 ```css
 .markdown-alert {
-    padding: 0.5rem 1rem;
-    margin-bottom: 1rem;
-    border-left: 4px solid;
+  padding: 0.5rem 1rem;
+  margin-bottom: 1rem;
+  border-left: 4px solid;
 }
 
 .markdown-alert-note { border-color: #0969da; background-color: #ddf4ff; }

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

@@ -4,6 +4,8 @@
 
 /**
  * Alert block for highlighting important information using {@code [!TYPE]} syntax.
+ *
+ * @see AlertTitle
  */
 public class Alert extends CustomBlock {
 

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

@@ -0,0 +1,25 @@
+package org.commonmark.ext.gfm.alerts;
+
+import org.commonmark.node.CustomNode;
+
+/**
+ * Inline content container for the optional custom title of an {@link Alert}.
+ *
+ * <p>
+ * When present, an {@code AlertTitle} is always the first child of an {@link Alert}.
+ * Its own children are the parsed inline nodes of the title (i.e., the text after
+ * the {@code [!TYPE]} marker on the same line). For example, in
+ *
+ * <pre><code>
+ * &gt; [!NOTE] Custom _title_
+ * &gt; Body text
+ * </code></pre>
+ *
+ * the {@code AlertTitle} contains a {@code Text} node ({@code "Custom "}) followed
+ * by an {@code Emphasis} node wrapping {@code "title"}.
+ *
+ * @see AlertsExtension.Builder#allowCustomTitles()
+ * @see AlertsExtension.Builder#disallowCustomTitles()
+ */
+public class AlertTitle extends CustomNode {
+}

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

@@ -1,7 +1,7 @@
 package org.commonmark.ext.gfm.alerts;
 
 import org.commonmark.Extension;
-import org.commonmark.ext.gfm.alerts.internal.AlertPostProcessor;
+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.parser.Parser;
@@ -33,9 +33,13 @@ public class AlertsExtension implements Parser.ParserExtension, HtmlRenderer.Htm
     static final Set<String> STANDARD_TYPES = Set.of("NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION");
 
     private final Map<String, String> customTypes;
+    private final boolean customTitlesAllowed;
+    private final boolean nestedAlertsAllowed;
 
     private AlertsExtension(Builder builder) {
         this.customTypes = new HashMap<>(builder.customTypes);
+        this.customTitlesAllowed = builder.customTitlesAllowed;
+        this.nestedAlertsAllowed = builder.nestedAlertsAllowed;
     }
 
     public static Extension create() {
@@ -50,7 +54,8 @@ public static Builder builder() {
     public void extend(Parser.Builder parserBuilder) {
         var allowedTypes = new HashSet<>(STANDARD_TYPES);
         allowedTypes.addAll(customTypes.keySet());
-        parserBuilder.postProcessor(new AlertPostProcessor(allowedTypes));
+        parserBuilder.customBlockParserFactory(
+            new AlertBlockParser.Factory(allowedTypes, customTitlesAllowed, nestedAlertsAllowed));
     }
 
     @Override
@@ -83,6 +88,8 @@ public Set<Character> getSpecialCharacters() {
      */
     public static class Builder {
         private final Map<String, String> customTypes = new HashMap<>();
+        private boolean customTitlesAllowed = false;
+        private boolean nestedAlertsAllowed = false;
 
         /**
          * Adds a custom alert type with a display title.
@@ -108,6 +115,46 @@ public Builder addCustomType(String type, String title) {
             return this;
         }
 
+        /**
+         * Allows custom titles on alerts. See {@link AlertTitle} for more information.
+         * @return {@code this}
+         */
+        public Builder allowCustomTitles() {
+            customTitlesAllowed = true;
+            return this;
+        }
+
+        /**
+         * Disallows custom titles on alerts. See {@link AlertTitle} for more information.
+         * @return {@code this}
+         */
+        public Builder disallowCustomTitles() {
+            customTitlesAllowed = false;
+            return this;
+        }
+
+        /**
+         * Allows alerts to be parsed within blocks other than {@code Document} (the root).
+         * <p>
+         * Note that even with this enabled, {@link Parser.Builder#maxOpenBlockParsers(int)}
+         * will be respected.
+         * @return {@code this}
+         */
+        public Builder allowNestedAlerts() {
+            nestedAlertsAllowed = true;
+            return this;
+        }
+
+        /**
+         * Prevents alerts from being parsed within blocks other than {@code Document}
+         * (the root). If they appear, they will be parsed as regular {@code BlockQuote}s.
+         * @return {@code this}
+         */
+        public Builder disallowNestedAlerts() {
+            nestedAlertsAllowed = false;
+            return this;
+        }
+
         /**
          * @return a configured {@link Extension}
          */