0
# CommonMark
1

2
A Python parser for the CommonMark Markdown spec that converts Markdown text into HTML and other formats. CommonMark provides a complete implementation of the CommonMark specification with both high-level convenience functions and low-level parsing/rendering control.
3

4
## Package Information
5

6
- **Package Name**: commonmark
7
- **Language**: Python
8
- **Installation**: `pip install commonmark`
9
- **Version**: 0.9.1
10

11
## Core Imports
12

13
```python
14
import commonmark
15
```
16

17
For specific components:
18

19
```python
20
from commonmark import commonmark, Parser, HtmlRenderer, ReStructuredTextRenderer
21
from commonmark import dumpAST, dumpJSON
22
```
23

24
## Basic Usage
25

26
### Simple Conversion
27

28
```python
29
import commonmark
30

31
# Convert Markdown to HTML (default)
32
html = commonmark.commonmark("# Hello\n*World*!")
33
print(html)  # <h1>Hello</h1>\n<p><em>World</em>!</p>\n
34

35
# Convert to other formats
36
json_ast = commonmark.commonmark("# Hello\n*World*!", format="json")
37
rst = commonmark.commonmark("# Hello\n*World*!", format="rst")
38
```
39

40
### Programmatic Parsing and Rendering
41

42
```python
43
from commonmark import Parser, HtmlRenderer
44

45
# Parse Markdown into AST
46
parser = Parser()
47
ast = parser.parse("# Hello\n*World*!")
48

49
# Render AST to HTML
50
renderer = HtmlRenderer()
51
html = renderer.render(ast)
52
print(html)
53
```
54

55
## Architecture
56

57
CommonMark follows a two-stage processing model:
58

59
- **Parser**: Converts Markdown text into an Abstract Syntax Tree (AST) represented as Node objects
60
- **Renderers**: Transform the AST into various output formats (HTML, reStructuredText, JSON)
61
- **AST Manipulation**: Node objects support tree manipulation operations for advanced use cases
62

63
This design enables parsing once and rendering to multiple formats, as well as programmatic modification of the document structure.
64

65
## Capabilities
66

67
### High-Level API
68

69
Simple one-function interface for common Markdown conversion tasks, supporting multiple output formats with sensible defaults.
70

71
```python { .api }
72
def commonmark(text, format="html"):
73
    """
74
    Render CommonMark into HTML, JSON, AST, or reStructuredText.
75
    
76
    Args:
77
        text (str): CommonMark Markdown text to parse
78
        format (str): Output format - 'html', 'json', 'ast', or 'rst'
79
    
80
    Returns:
81
        str: Rendered output in specified format
82
    """
83
```
84

85
[High-Level API](./high-level.md)
86

87
### Parsing and AST Manipulation
88

89
Comprehensive parsing functionality with full control over the Abstract Syntax Tree, including node creation, modification, and traversal operations.
90

91
```python { .api }
92
class Parser:
93
    def __init__(self, options={}): ...
94
    def parse(self, my_input): ...
95

96
class Node:
97
    def __init__(self, node_type, sourcepos): ...
98
    def walker(self): ...
99
    def append_child(self, child): ...
100
    def unlink(self): ...
101

102
class NodeWalker:
103
    def __init__(self, root): ...
104
    def nxt(self): ...
105
```
106

107
[Parsing and AST](./parsing.md)
108

109
### Rendering
110

111
Multiple output format renderers with customizable options for converting AST to HTML, reStructuredText, and other formats.
112

113
```python { .api }
114
class HtmlRenderer:
115
    def __init__(self, options={}): ...
116
    def render(self, ast): ...
117

118
class ReStructuredTextRenderer:
119
    def __init__(self, indent_char=' '): ...
120
    def render(self, ast): ...
121

122
class Renderer:
123
    def render(self, ast): ...
124
    def lit(self, s): ...
125
    def cr(self): ...
126
```
127

128
[Rendering](./rendering.md)
129

130
### Debugging and Utilities
131

132
Utility functions for debugging, AST inspection, and format conversion including JSON serialization and pretty-printing.
133

134
```python { .api }
135
def dumpAST(obj, ind=0, topnode=False): ...
136
def dumpJSON(obj): ...
137
def is_container(node): ...
138
```
139

140
[Utilities](./utilities.md)
141

142
### Command Line Interface
143

144
Command-line tool for processing Markdown files with support for various output formats and file I/O operations.
145

146
```python { .api }
147
def main(): ...
148
```
149

150
Available as `cmark` console command.
151

152
[CLI](./cli.md)