Merge pull request #420 from ia3andy/gfm-alerts

Add GFM alerts extension

Author: robinst

commonmark-ext-gfm-alerts/README.md

@@ -0,0 +1,74 @@
+# commonmark-ext-gfm-alerts
+
+Extension for [commonmark-java](https://github.com/commonmark/commonmark-java) that adds support for [GitHub Flavored Markdown alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
+
+Enables highlighting important information using blockquote syntax with five standard alert types: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.
+
+## Usage
+
+#### Markdown Syntax
+
+```markdown
+> [!NOTE]
+> Useful information
+
+> [!WARNING]
+> Critical information
+```
+
+#### 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
+
+Add custom types beyond the five standard GFM types:
+
+```java
+var extension = AlertsExtension.builder()
+        .addCustomType("BUG", "Known Bug")
+        .build();
+```
+
+Custom types must be UPPERCASE. Standard type titles can also be overridden for localization.
+
+#### Styling
+
+Alerts render as `<div>` elements with CSS classes:
+
+```html
+<div class="markdown-alert markdown-alert-note" data-alert-type="note">
+  <p class="markdown-alert-title">Note</p>
+  <p>Content</p>
+</div>
+```
+
+Basic CSS example:
+
+```css
+.markdown-alert {
+    padding: 0.5rem 1rem;
+    margin-bottom: 1rem;
+    border-left: 4px solid;
+}
+
+.markdown-alert-note { border-color: #0969da; background-color: #ddf4ff; }
+.markdown-alert-tip { border-color: #1a7f37; background-color: #dcffe4; }
+.markdown-alert-important { border-color: #8250df; background-color: #f6f0ff; }
+.markdown-alert-warning { border-color: #9a6700; background-color: #fff8c5; }
+.markdown-alert-caution { border-color: #cf222e; background-color: #ffebe9; }
+```
+
+![Alerts](screenshots/alerts.png)
+
+Icons can be added using GitHub's [Octicons](https://primer.style/octicons/):
+
+![Alerts with icons](screenshots/alerts-with-icons.png)
+
+## License
+
+See the main commonmark-java project for license information.

commonmark-ext-gfm-alerts/pom.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.commonmark</groupId>
+        <artifactId>commonmark-parent</artifactId>
+        <version>0.27.2-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>commonmark-ext-gfm-alerts</artifactId>
+    <name>commonmark-java extension for alerts</name>
+    <description>commonmark-java extension for GFM alerts (admonition blocks) using [!TYPE] syntax (GitHub Flavored Markdown)</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.commonmark</groupId>
+            <artifactId>commonmark</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.commonmark</groupId>
+            <artifactId>commonmark-test-util</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>

commonmark-ext-gfm-alerts/screenshots/alerts-with-icons.png

@@ -0,0 +1,5 @@
+module org.commonmark.ext.gfm.alerts {
+    exports org.commonmark.ext.gfm.alerts;
+
+    requires transitive org.commonmark;
+}

commonmark-ext-gfm-alerts/screenshots/alerts.png

@@ -0,0 +1,19 @@
+package org.commonmark.ext.gfm.alerts;
+
+import org.commonmark.node.CustomBlock;
+
+/**
+ * Alert block for highlighting important information using {@code [!TYPE]} syntax.
+ */
+public class Alert extends CustomBlock {
+
+    private final String type;
+
+    public Alert(String type) {
+        this.type = type;
+    }
+
+    public String getType() {
+        return type;
+    }
+}

commonmark-ext-gfm-alerts/src/main/java/module-info.java

@@ -0,0 +1,118 @@
+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.AlertHtmlNodeRenderer;
+import org.commonmark.ext.gfm.alerts.internal.AlertMarkdownNodeRenderer;
+import org.commonmark.parser.Parser;
+import org.commonmark.renderer.NodeRenderer;
+import org.commonmark.renderer.html.HtmlNodeRendererContext;
+import org.commonmark.renderer.html.HtmlNodeRendererFactory;
+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 java.util.HashMap;
+import java.util.Locale;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Extension for GFM alerts using {@code [!TYPE]} syntax (GitHub Flavored Markdown).
+ * <p>
+ * Create with {@link #create()} or {@link #builder()} and configure on builders
+ * ({@link org.commonmark.parser.Parser.Builder#extensions(Iterable)},
+ * {@link HtmlRenderer.Builder#extensions(Iterable)}).
+ * Parsed alerts become {@link Alert} blocks.
+ */
+public class AlertsExtension implements Parser.ParserExtension, HtmlRenderer.HtmlRendererExtension,
+        MarkdownRenderer.MarkdownRendererExtension {
+
+    static final Set<String> STANDARD_TYPES = Set.of("NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION");
+
+    private final Map<String, String> customTypes;
+
+    private AlertsExtension(Builder builder) {
+        this.customTypes = new HashMap<>(builder.customTypes);
+    }
+
+    public static Extension create() {
+        return builder().build();
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    @Override
+    public void extend(Parser.Builder parserBuilder) {
+        var allowedTypes = new HashSet<>(STANDARD_TYPES);
+        allowedTypes.addAll(customTypes.keySet());
+        parserBuilder.postProcessor(new AlertPostProcessor(allowedTypes));
+    }
+
+    @Override
+    public void extend(HtmlRenderer.Builder rendererBuilder) {
+        rendererBuilder.nodeRendererFactory(new HtmlNodeRendererFactory() {
+            @Override
+            public NodeRenderer create(HtmlNodeRendererContext context) {
+                return new AlertHtmlNodeRenderer(context, customTypes);
+            }
+        });
+    }
+
+    @Override
+    public void extend(MarkdownRenderer.Builder rendererBuilder) {
+        rendererBuilder.nodeRendererFactory(new MarkdownNodeRendererFactory() {
+            @Override
+            public NodeRenderer create(MarkdownNodeRendererContext context) {
+                return new AlertMarkdownNodeRenderer(context);
+            }
+
+            @Override
+            public Set<Character> getSpecialCharacters() {
+                return Set.of();
+            }
+        });
+    }
+
+    /**
+     * Builder for configuring the alerts extension.
+     */
+    public static class Builder {
+        private final Map<String, String> customTypes = new HashMap<>();
+
+        /**
+         * Adds a custom alert type with a display title.
+         * <p>
+         * This can also be used to override the display title of standard GFM types
+         * (e.g., for localization).
+         *
+         * @param type the alert type (must be uppercase)
+         * @param title the display title for this alert type
+         * @return {@code this}
+         */
+        public Builder addCustomType(String type, String title) {
+            if (type == null || type.isEmpty()) {
+                throw new IllegalArgumentException("Type must not be null or empty");
+            }
+            if (title == null || title.isEmpty()) {
+                throw new IllegalArgumentException("Title must not be null or empty");
+            }
+            if (!type.equals(type.toUpperCase(Locale.ROOT))) {
+                throw new IllegalArgumentException("Type must be uppercase: " + type);
+            }
+            customTypes.put(type, title);
+            return this;
+        }
+
+        /**
+         * @return a configured {@link Extension}
+         */
+        public Extension build() {
+            return new AlertsExtension(this);
+        }
+    }
+}

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

@@ -0,0 +1,78 @@
+package org.commonmark.ext.gfm.alerts.internal;
+
+import org.commonmark.ext.gfm.alerts.Alert;
+import org.commonmark.node.Node;
+import org.commonmark.renderer.html.HtmlNodeRendererContext;
+import org.commonmark.renderer.html.HtmlWriter;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+public class AlertHtmlNodeRenderer extends AlertNodeRenderer {
+
+    private final HtmlWriter htmlWriter;
+    private final HtmlNodeRendererContext context;
+    private final Map<String, String> customTypeTitles;
+
+    public AlertHtmlNodeRenderer(HtmlNodeRendererContext context, Map<String, String> customTypeTitles) {
+        this.htmlWriter = context.getWriter();
+        this.context = context;
+        this.customTypeTitles = customTypeTitles;
+    }
+
+    @Override
+    protected void renderAlert(Alert alert) {
+        var type = alert.getType();
+        var cssClass = type.toLowerCase();
+
+        htmlWriter.line();
+        var attributes = new LinkedHashMap<String, String>();
+        attributes.put("class", "markdown-alert markdown-alert-" + cssClass);
+        attributes.put("data-alert-type", cssClass);
+
+        htmlWriter.tag("div", context.extendAttributes(alert, "div", attributes));
+        htmlWriter.line();
+
+        // Render alert title
+        htmlWriter.tag("p", Map.of("class", "markdown-alert-title"));
+        htmlWriter.text(getAlertTitle(type));
+        htmlWriter.tag("/p");
+        htmlWriter.line();
+
+        // Render children (the alert content)
+        renderChildren(alert);
+
+        htmlWriter.tag("/div");
+        htmlWriter.line();
+    }
+
+    private String getAlertTitle(String type) {
+        var customTypeTitle = customTypeTitles.get(type);
+        if (customTypeTitle != null) {
+            return customTypeTitle;
+        }
+        switch (type) {
+            case "NOTE":
+                return "Note";
+            case "TIP":
+                return "Tip";
+            case "IMPORTANT":
+                return "Important";
+            case "WARNING":
+                return "Warning";
+            case "CAUTION":
+                return "Caution";
+            default:
+                throw new IllegalStateException("Unknown alert type: " + type);
+        }
+    }
+
+    private void renderChildren(Node parent) {
+        var node = parent.getFirstChild();
+        while (node != null) {
+            var next = node.getNext();
+            context.render(node);
+            node = next;
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+package org.commonmark.ext.gfm.alerts.internal;
+
+import org.commonmark.ext.gfm.alerts.Alert;
+import org.commonmark.node.Node;
+import org.commonmark.renderer.markdown.MarkdownNodeRendererContext;
+import org.commonmark.renderer.markdown.MarkdownWriter;
+
+public class AlertMarkdownNodeRenderer extends AlertNodeRenderer {
+
+    private final MarkdownWriter writer;
+    private final MarkdownNodeRendererContext context;
+
+    public AlertMarkdownNodeRenderer(MarkdownNodeRendererContext context) {
+        this.writer = context.getWriter();
+        this.context = context;
+    }
+
+    @Override
+    protected void renderAlert(Alert alert) {
+        // First line: > [!TYPE]
+        writer.writePrefix("> ");
+        writer.pushPrefix("> ");
+        writer.raw("[!" + alert.getType() + "]");
+        writer.line();
+        renderChildren(alert);
+        writer.popPrefix();
+        writer.block();
+    }
+
+    private void renderChildren(Node parent) {
+        var node = parent.getFirstChild();
+        while (node != null) {
+            var next = node.getNext();
+            context.render(node);
+            node = next;
+        }
+    }
+}

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

@@ -0,0 +1,23 @@
+package org.commonmark.ext.gfm.alerts.internal;
+
+import org.commonmark.ext.gfm.alerts.Alert;
+import org.commonmark.node.Node;
+import org.commonmark.renderer.NodeRenderer;
+
+import java.util.Set;
+
+public abstract class AlertNodeRenderer implements NodeRenderer {
+
+    @Override
+    public Set<Class<? extends Node>> getNodeTypes() {
+        return Set.of(Alert.class);
+    }
+
+    @Override
+    public void render(Node node) {
+        var alert = (Alert) node;
+        renderAlert(alert);
+    }
+
+    protected abstract void renderAlert(Alert alert);
+}