0
# Command Line Interface
1
2
CLI tool for converting markdown files to HTML with dialect selection and flexible input/output handling.
3
4
## Capabilities
5
6
### md2html Command
7
8
Command-line utility for markdown to HTML conversion.
9
10
```bash
11
# Basic usage
12
md2html [options] [file]
13
14
# Options:
15
# --dialect=DIALECT Choose "Gruber" (default) or "Maruku"
16
# --help Show usage information
17
#
18
# Input: File path or stdin when file is "-" or omitted
19
# Output: HTML written to stdout
20
```
21
22
**Installation:**
23
24
```bash
25
# Install globally to get md2html command
26
npm install -g markdown
27
28
# Or use locally installed version
29
npx md2html file.md
30
```
31
32
### Basic File Conversion
33
34
Convert markdown files to HTML with automatic output.
35
36
**Usage Examples:**
37
38
```bash
39
# Convert file to HTML
40
md2html document.md > document.html
41
42
# Convert with output redirection
43
md2html README.md > README.html
44
45
# Process multiple files (shell loop)
46
for file in *.md; do
47
md2html "$file" > "${file%.md}.html"
48
done
49
```
50
51
### Dialect Selection
52
53
Choose between Gruber (default) and Maruku parsing dialects.
54
55
**Usage Examples:**
56
57
```bash
58
# Use default Gruber dialect
59
md2html document.md
60
61
# Use Maruku dialect for extended features
62
md2html --dialect=Maruku document.md
63
64
# Maruku supports tables, metadata, etc.
65
md2html --dialect=Maruku table.md > table.html
66
```
67
68
### Stdin Processing
69
70
Process markdown from standard input for pipeline usage.
71
72
**Usage Examples:**
73
74
```bash
75
# Process from stdin
76
echo "# Hello World" | md2html
77
78
# Explicit stdin with dash
79
echo "**Bold text**" | md2html -
80
81
# Pipeline processing
82
curl -s https://example.com/doc.md | md2html --dialect=Maruku
83
84
# Process from here-document
85
md2html << 'EOF'
86
# Documentation
87
88
This is **important** information.
89
90
- Item 1
91
- Item 2
92
EOF
93
```
94
95
### Help and Usage Information
96
97
Get command help and usage instructions.
98
99
```bash
100
# Show help
101
md2html --help
102
103
# Output:
104
# usage: md2html [--dialect=DIALECT] FILE
105
#
106
# Valid dialects are Gruber (the default) or Maruku
107
```
108
109
### Error Handling
110
111
The command handles various error conditions:
112
113
```bash
114
# File not found
115
md2html nonexistent.md
116
# Writes error to stderr, exits with code 1
117
118
# Invalid dialect
119
md2html --dialect=Invalid file.md
120
# No error (invalid dialect ignored, uses default)
121
122
# Permission errors
123
md2html /root/restricted.md
124
# Writes error to stderr, exits with code 1
125
```
126
127
### Advanced Usage Patterns
128
129
Complex workflows combining shell features with md2html.
130
131
**Batch Processing:**
132
133
```bash
134
#!/bin/bash
135
# Convert all markdown files in directory tree
136
137
find . -name "*.md" -type f | while read -r file; do
138
output="${file%.md}.html"
139
echo "Converting: $file -> $output"
140
md2html --dialect=Maruku "$file" > "$output"
141
done
142
```
143
144
**Pipeline with Processing:**
145
146
```bash
147
# Download, process, and format markdown
148
curl -s https://api.github.com/repos/user/repo/readme |
149
jq -r '.content' |
150
base64 -d |
151
md2html --dialect=Maruku |
152
tidy -q -i --show-warnings no
153
```
154
155
**Conditional Dialect Selection:**
156
157
```bash
158
#!/bin/bash
159
file="$1"
160
161
# Use Maruku for files with tables or metadata
162
if grep -q '|.*|' "$file" || grep -q '^[A-Za-z]*:' "$file"; then
163
dialect="Maruku"
164
else
165
dialect="Gruber"
166
fi
167
168
echo "Using $dialect dialect for $file"
169
md2html --dialect="$dialect" "$file"
170
```
171
172
**Template Integration:**
173
174
```bash
175
#!/bin/bash
176
# Wrap markdown conversion in HTML template
177
178
header='<!DOCTYPE html><html><head><title>Document</title></head><body>'
179
footer='</body></html>'
180
181
echo "$header"
182
md2html "$1"
183
echo "$footer"
184
```
185
186
## Implementation Details
187
188
The md2html command is implemented in `bin/md2html.js` and uses the core markdown library:
189
190
```javascript
191
// Simplified implementation overview
192
var markdown = require("markdown").markdown;
193
var nopt = require("nopt");
194
195
// Parse command line options
196
var opts = nopt({
197
"dialect": ["Gruber", "Maruku"],
198
"help": Boolean
199
});
200
201
// Process input stream
202
stream.on("end", function() {
203
var html = markdown.toHTML(buffer, opts.dialect);
204
console.log(html);
205
});
206
```
207
208
The command integrates with standard Unix conventions:
209
- Reads from files or stdin
210
- Writes HTML to stdout
211
- Writes errors to stderr
212
- Uses appropriate exit codes
213
- Supports standard shell redirection and piping