commonmark-java

To enable support for GitHub Flavored Markdown (GFM) alerts, create an AlertsExtension and register it with both the Parser and the HtmlRenderer. This allows you to use the > [!TYPE] syntax in your markdown.

var extension = AlertsExtension.create();
var parser = Parser.builder().extensions(List.of(extension)).build();
var renderer = HtmlRenderer.builder().extensions(List.of(extension)).build();

Extensions are provided in separate artifacts. To use them, add the extension dependency and pass a list of Extension objects to both the Parser.Builder and HtmlRenderer.Builder.

<!-- Example: Adding GFM Tables -->
<dependency>
    <groupId>org.commonmark</groupId>
    <artifactId>commonmark-ext-gfm-tables</artifactId>
    <version>0.29.0</version>
</dependency>

import org.commonmark.ext.gfm.tables.TablesExtension;

List<Extension> extensions = List.of(TablesExtension.create());
Parser parser = Parser.builder()
        .extensions(extensions)
        .build();
HtmlRenderer renderer = HtmlRenderer.builder()
        .extensions(extensions)
        .build();

To use the core CommonMark library in your Java project, add the following dependency to your pom.xml. Note that for 0.x releases, the API is not considered stable and may break between minor releases.

<dependency>
    <groupId>org.commonmark</groupId>
    <artifactId>commonmark</artifactId>
    <version>0.29.0</version>
</dependency>

To run lint checks for Android support in commonmark-java, ensure your environment meets the following requirements and configuration steps:

Requirements

• Java: Version 11 or above
• Android SDK: Version 30 installed (x86 is recommended)

Configuration Steps

1. Download the Android SDK.
2. Ensure SDK Platform 30 is installed.
3. Add the following directories to your PATH environment variable:
   • path_to_android_sdk/platform-tools
   • path_to_android_sdk/tools
4. Create a local.properties file in the commonmark-android-test directory and define the SDK path:

sdk.dir=/path_to_android_sdk

Use an AttributeProvider to inject custom attributes (like CSS classes) into specific HTML elements during rendering.

Parser parser = Parser.builder().build();
HtmlRenderer renderer = HtmlRenderer.builder()
        .attributeProviderFactory(new AttributeProviderFactory() {
            public AttributeProvider create(AttributeProviderContext context) {
                return new ImageAttributeProvider();
            }
        })
        .build();

Node document = parser.parse("![text](/url.png)");
renderer.render(document);
// "<p><img src=\"/url.png\" alt=\"text\" class=\"border\" /></p>\n"

class ImageAttributeProvider implements AttributeProvider {
    @Override
    public void setAttributes(Node node, String tagName, Map<String, String> attributes) {
        if (node instanceof Image) {
            attributes.put("class", "border");
        }
    }
}

Use Parser to convert Markdown text into an Abstract Syntax Tree (AST) and HtmlRenderer to convert that AST into HTML. Both use a builder pattern for configuration.

import org.commonmark.node.*;
import org.commonmark.parser.Parser;
import org.commonmark.renderer.html.HtmlRenderer;

var parser = Parser.builder().build();
var document = parser.parse("This is *Markdown*");
var renderer = HtmlRenderer.builder().build();
renderer.render(document);  // "<p>This is <em>Markdown</em></p>\n"

You can render an existing AST back into Markdown text using MarkdownRenderer.

import org.commonmark.node.*;
import org.commonmark.renderer.markdown.MarkdownRenderer;

// Build document
var heading = new Heading();
heading.setLevel(2);
heading.appendChild(new Text("My heading"));
var document = new Document();
document.appendChild(heading);

// Render to Markdown
var renderer = MarkdownRenderer.builder().build();
renderer.render(document);  // "## My heading\n"

After parsing, you can traverse the AST using a visitor by extending AbstractVisitor and overriding the visit methods for specific node types.

Node node = parser.parse("Example\n=======\n\nSome more text");
WordCountVisitor visitor = new WordCountVisitor();
node.accept(visitor);
visitor.wordCount;  // 4

class WordCountVisitor extends AbstractVisitor {
    int wordCount = 0;

    @Override
    public void visit(Text text) {
        // Count words
        wordCount += text.getLiteral().split("\\W+").length;

        // Descend into children
        visitChildren(text);
    }
}

By default, alerts cannot be nested within other blocks (like lists) and will be parsed as regular blockquotes. To allow alerts to be nested within other blocks, enable allowNestedAlerts(true) in the AlertsExtension.builder().

var extension = AlertsExtension.builder().allowNestedAlerts(true).build();

By default, alerts use a standard title based on the type. To allow authors to provide custom titles on the same line as the alert marker (e.g., > [!NOTE] Custom Title), enable allowCustomTitles(true) in the AlertsExtension.builder().

var extension = AlertsExtension.builder().allowCustomTitles(true).build();