0
# CommonMark Java
1

2
CommonMark Java is a comprehensive Java implementation of the CommonMark specification for parsing and rendering Markdown text. It provides a complete parsing system that converts Markdown input into an abstract syntax tree (AST) of nodes, supports visiting and manipulating these nodes, and offers HTML and text rendering capabilities. The library is designed for high performance, maintains a small footprint with zero dependencies in the core module, and offers extensive flexibility through AST manipulation and customizable rendering.
3

4
## Package Information
5

6
- **Package Name**: org.commonmark:commonmark  
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.commonmark</groupId>
13
    <artifactId>commonmark</artifactId>
14
    <version>0.17.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.commonmark.parser.Parser;
22
import org.commonmark.renderer.html.HtmlRenderer;
23
import org.commonmark.renderer.text.TextContentRenderer;
24
import org.commonmark.node.Node;
25
```
26

27
## Basic Usage
28

29
```java
30
import org.commonmark.parser.Parser;
31
import org.commonmark.renderer.html.HtmlRenderer;
32
import org.commonmark.node.Node;
33

34
// Parse Markdown text to AST
35
Parser parser = Parser.builder().build();
36
Node document = parser.parse("This is *Markdown*");
37

38
// Render to HTML
39
HtmlRenderer renderer = HtmlRenderer.builder().build();
40
String html = renderer.render(document);
41
// Result: <p>This is <em>Markdown</em></p>
42

43
// Parse from Reader (for files)
44
try (FileReader reader = new FileReader("document.md")) {
45
    Node document = parser.parseReader(reader);
46
    String html = renderer.render(document);
47
}
48
```
49

50
## Architecture
51

52
CommonMark Java is built around several key components:
53

54
- **Parser System**: Main `Parser` class converts Markdown text to AST nodes using configurable block and inline parsers
55
- **AST Node Hierarchy**: Complete set of node classes representing all CommonMark elements with visitor pattern support
56
- **Rendering Engine**: Pluggable renderers for HTML, text, and custom output formats with extensible node renderer system
57
- **Extension Framework**: Interface-based extension system for adding custom syntax, parsers, and renderers
58
- **Source Tracking**: Optional source span tracking for mapping AST nodes back to original input positions
59

60
## Capabilities
61

62
### Core Parsing
63

64
Complete Markdown parsing functionality that converts text input into a structured Abstract Syntax Tree (AST). Supports all CommonMark specification features with configurable parsing options.
65

66
```java { .api }
67
public static Parser.Builder builder();
68
public Node parse(String input);
69
public Node parseReader(Reader input) throws IOException;
70
```
71

72
[Core Parsing](./core-parsing.md)
73

74
### AST Node System
75

76
Comprehensive node hierarchy representing all CommonMark elements including blocks, inlines, and document structure. Provides visitor pattern support for traversing and manipulating the AST.
77

78
```java { .api }
79
public abstract class Node {
80
    public abstract void accept(Visitor visitor);
81
    public Node getNext();
82
    public Node getParent();
83
    public void appendChild(Node child);
84
}
85

86
public interface Visitor {
87
    void visit(Document document);
88
    void visit(Heading heading);
89
    void visit(Paragraph paragraph);
90
    // ... visit methods for all node types
91
}
92
```
93

94
[AST Node System](./ast-nodes.md)
95

96
### HTML Rendering
97

98
High-performance HTML rendering with extensive customization options including URL sanitization, attribute providers, and custom node renderers.
99

100
```java { .api }
101
public static HtmlRenderer.Builder builder();
102
public String render(Node node);
103
public void render(Node node, Appendable output);
104
```
105

106
[HTML Rendering](./html-rendering.md)
107

108
### Text Content Rendering  
109

110
Plain text rendering for converting CommonMark documents back to text format with optional newline stripping and custom formatting.
111

112
```java { .api }
113
public static TextContentRenderer.Builder builder();
114
public String render(Node node);
115
public void render(Node node, Appendable output);
116
```
117

118
[Text Content Rendering](./text-rendering.md)
119

120
### Extension System
121

122
Comprehensive extension framework for adding custom syntax support, parsers, and renderers. Supports block parser factories, delimiter processors, and post-processors.
123

124
```java { .api }
125
public interface Extension {
126
    // Marker interface for extensions
127
}
128

129
public interface Parser.ParserExtension extends Extension {
130
    void extend(Parser.Builder parserBuilder);
131
}
132

133
public interface HtmlRenderer.HtmlRendererExtension extends Extension {
134
    void extend(HtmlRenderer.Builder rendererBuilder);
135
}
136
```
137

138
[Extension System](./extensions.md)
139

140
## Core Types
141

142
```java { .api }
143
// Main entry points
144
public class Parser {
145
    public static Builder builder();
146
    public Node parse(String input);
147
    public Node parseReader(Reader input) throws IOException;
148
}
149

150
public class HtmlRenderer implements Renderer {
151
    public static Builder builder();
152
    public String render(Node node);
153
    public void render(Node node, Appendable output);
154
}
155

156
public class TextContentRenderer implements Renderer {
157
    public static Builder builder();
158
    public String render(Node node);
159
    public void render(Node node, Appendable output);
160
}
161

162
// Base node hierarchy
163
public abstract class Node {
164
    public abstract void accept(Visitor visitor);
165
    public Node getNext();
166
    public Node getPrevious();
167
    public Node getFirstChild();
168
    public Node getLastChild();
169
    public Node getParent();
170
    public void appendChild(Node child);
171
    public void prependChild(Node child);
172
    public void unlink();
173
    public void insertAfter(Node sibling);
174
    public void insertBefore(Node sibling);
175
}
176

177
public abstract class Block extends Node {
178
    public Block getParent();
179
}
180

181
// Extension interfaces
182
public interface Extension {
183
    // Marker interface
184
}
185

186
public interface Renderer {
187
    void render(Node node, Appendable output);
188
    String render(Node node);
189
}
190
```