0
# Command Line Interface
1
2
Command-line tool for processing Markdown files with support for various output formats and file I/O operations. The CLI provides a convenient way to convert Markdown files from the command line.
3
4
## Capabilities
5
6
### Main CLI Function
7
8
Entry point for the command-line interface that processes Markdown files and outputs converted content.
9
10
```python { .api }
11
def main():
12
"""
13
Command-line interface entry point for processing Markdown files.
14
15
Processes command-line arguments and converts Markdown input to various formats.
16
Available as the 'cmark' console command after installation.
17
18
Command-line arguments:
19
infile: Input Markdown file to parse (optional, defaults to stdin)
20
-o [FILE]: Output HTML/JSON file (optional, defaults to stdout)
21
-a: Print formatted AST instead of HTML
22
-aj: Output JSON AST instead of HTML
23
-h, --help: Show help message and exit
24
25
Returns:
26
None: Outputs results to stdout or specified output file, then exits
27
"""
28
```
29
30
## Command Usage
31
32
The `cmark` command is available after installing the commonmark package:
33
34
```bash
35
pip install commonmark
36
```
37
38
### Basic Usage
39
40
Convert Markdown file to HTML:
41
42
```bash
43
cmark input.md
44
```
45
46
Convert from stdin:
47
48
```bash
49
echo "# Hello World" | cmark
50
```
51
52
### Input File
53
54
Process a single Markdown file:
55
56
```bash
57
cmark input.md
58
```
59
60
### Output Redirection
61
62
Save output to a file:
63
64
```bash
65
cmark input.md > output.html
66
```
67
68
Or use the `-o` option:
69
70
```bash
71
cmark input.md -o output.html
72
```
73
74
### Format Options
75
76
Output pretty-printed AST:
77
78
```bash
79
cmark input.md -a
80
```
81
82
Output JSON AST:
83
84
```bash
85
cmark input.md -aj
86
```
87
88
## Usage Examples
89
90
### Convert Single File
91
92
```bash
93
# Create a sample Markdown file
94
echo "# Hello World\n\nThis is **bold** text." > sample.md
95
96
# Convert to HTML
97
cmark sample.md
98
# Output: <h1>Hello World</h1>\n<p>This is <strong>bold</strong> text.</p>\n
99
```
100
101
### Process from Standard Input
102
103
```bash
104
# Convert Markdown from stdin
105
echo "- Item 1\n- Item 2" | cmark
106
# Output: <ul>\n<li>Item 1</li>\n<li>Item 2</li>\n</ul>\n
107
```
108
109
### Single File Processing
110
111
```bash
112
# Process a single file
113
echo "# Sample Document" > sample.md
114
cmark sample.md
115
# Outputs HTML for the file
116
```
117
118
### Advanced Examples
119
120
```bash
121
# Output AST for debugging
122
echo "# Title\n*italic*" | cmark -a
123
124
# Save JSON AST to file
125
cmark document.md -aj -o ast.json
126
127
# Convert to HTML with explicit output file
128
cmark README.md -o README.html
129
```
130
131
### Integration with Other Tools
132
133
```bash
134
# Use with find to process Markdown files one at a time
135
find . -name "*.md" -exec cmark {} \;
136
137
# Process and save to HTML files
138
for file in *.md; do
139
cmark "$file" -o "${file%.md}.html"
140
done
141
```
142
143
## Programmatic Usage
144
145
You can also call the CLI function directly from Python:
146
147
```python
148
import sys
149
from commonmark.cmark import main
150
151
# Simulate command-line arguments
152
sys.argv = ['cmark', 'input.md']
153
main()
154
```
155
156
## Implementation Details
157
158
The CLI implementation:
159
160
- Reads from a single file specified in command-line arguments or stdin if no file given
161
- Uses the default HTML output format (same as `commonmark.commonmark()` with `format="html"`)
162
- Accepts only one input file at a time
163
- Outputs results to stdout or specified output file with `-o`
164
- Follows standard Unix conventions for input/output handling
165
166
The `cmark` console script is registered in the package's `setup.py` and points to `commonmark.cmark:main`.