0
# Command Line Interface
1

2
CLI tool for converting Markdown files to HTML with full option support and extension loading.
3

4
## Capabilities
5

6
### showdown makehtml
7

8
Main command for converting Markdown to HTML via command line.
9

10
```bash { .api }
11
showdown makehtml [options]
12
```
13

14
## Options
15

16
### Input/Output Options
17

18
```bash { .api }
19
-i, --input [file]              # Input source (file path or stdin)
20
-o, --output [file]             # Output target (file path or stdout)
21
-u, --encoding <encoding>       # Input encoding (default: utf8)
22
-y, --output-encoding <encoding> # Output encoding (default: utf8)
23
-a, --append                    # Append to output file instead of overwriting
24
```
25

26
### Conversion Options
27

28
```bash { .api }
29
-p, --flavor <flavor>           # Use predefined flavor (vanilla, github, ghost, original)
30
-c, --config <config...>        # Enable parser options
31
-e, --extensions <extensions...> # Load extensions (file paths)
32
```
33

34
### Utility Options
35

36
```bash { .api }
37
--config-help                   # Show available configuration options
38
-q, --quiet                     # Quiet mode (only print errors)
39
-m, --mute                      # Mute mode (print nothing)
40
-h, --help                      # Show help information
41
-V, --version                   # Show version number
42
```
43

44
## Usage Examples
45

46
### Basic Conversion
47

48
```bash
49
# Convert file to HTML
50
showdown makehtml -i input.md -o output.html
51

52
# Convert from stdin to stdout
53
echo "# Hello World" | showdown makehtml
54

55
# Read from stdin, write to file
56
showdown makehtml -i -o output.html < input.md
57
```
58

59
### Using Flavors
60

61
```bash
62
# Use GitHub Flavored Markdown
63
showdown makehtml -i input.md -o output.html --flavor github
64

65
# Use Ghost flavor
66
showdown makehtml -i input.md --flavor ghost
67

68
# Use original Markdown behavior
69
showdown makehtml -i input.md --flavor original
70
```
71

72
### Configuration Options
73

74
```bash
75
# Enable specific options
76
showdown makehtml -i input.md -c tables strikethrough ghCodeBlocks
77

78
# Enable options with values
79
showdown makehtml -i input.md -c prefixHeaderId="section-"
80

81
# Combine flavor with custom options
82
showdown makehtml -i input.md --flavor github -c emoji=false
83
```
84

85
### Extension Loading
86

87
```bash
88
# Load single extension
89
showdown makehtml -i input.md -e ./my-extension.js
90

91
# Load multiple extensions
92
showdown makehtml -i input.md -e ./ext1.js ./ext2.js ./ext3.js
93

94
# Combine with other options
95
showdown makehtml -i input.md --flavor github -e ./highlight.js -c tables
96
```
97

98
### Encoding Options
99

100
```bash
101
# Specify input encoding
102
showdown makehtml -i input.md -u utf16le
103

104
# Specify both input and output encoding
105
showdown makehtml -i input.md -u utf8 -y ascii
106

107
# For Windows users with special characters
108
showdown makehtml -i input.md -u utf8
109
```
110

111
### Output Control
112

113
```bash
114
# Append to existing file
115
showdown makehtml -i input.md -o output.html --append
116

117
# Quiet mode (only errors)
118
showdown makehtml -i input.md -o output.html --quiet
119

120
# Mute mode (no output)
121
showdown makehtml -i input.md -o output.html --mute
122
```
123

124
## Configuration Help
125

126
View all available configuration options:
127

128
```bash
129
showdown makehtml --config-help
130
```
131

132
This displays detailed information about all parser options including:
133
- Option names
134
- Default values  
135
- Descriptions
136
- Data types
137

138
## Configuration Examples
139

140
### GitHub-style Conversion
141

142
```bash
143
showdown makehtml -i README.md -o README.html \
144
  --flavor github \
145
  -c ghMentionsLink="https://github.com"
146
```
147

148
### Custom Blog Conversion
149

150
```bash
151
showdown makehtml -i post.md -o post.html \
152
  -c tables \
153
  -c strikethrough \
154
  -c headerLevelStart=2 \
155
  -c prefixHeaderId="post-"
156
```
157

158
### Extension with Options
159

160
```bash
161
showdown makehtml -i doc.md -o doc.html \
162
  -e ./syntax-highlight.js \
163
  -c ghCodeBlocks \
164
  -c tables
165
```
166

167
## Error Handling
168

169
The CLI provides informative error messages:
170

171
```bash
172
# File not found
173
showdown makehtml -i nonexistent.md
174
# ERROR: Could not read from file nonexistent.md, reason: ENOENT: no such file or directory
175

176
# Invalid extension
177
showdown makehtml -i input.md -e ./bad-extension.js
178
# ERROR: Could not load extension ./bad-extension.js. Reason: [error details]
179

180
# Invalid flavor
181
showdown makehtml -i input.md --flavor invalid
182
# ERROR: invalid flavor was not found
183
```
184

185
## Exit Codes
186

187
- `0`: Success
188
- `1`: Error (file not found, invalid options, conversion failure, etc.)
189

190
## Windows Considerations
191

192
For Windows users dealing with encoding issues:
193

194
```bash
195
# Set command line to UTF-8 before running
196
chcp 65001
197

198
# Then run showdown
199
showdown makehtml -i input.md -o output.html
200
```
201

202
Or specify encoding explicitly:
203

204
```bash
205
showdown makehtml -i input.md -o output.html -u utf8
206
```
207

208
## Stdin/Stdout Patterns
209

210
### Pipe from other commands
211

212
```bash
213
# From curl
214
curl -s https://raw.githubusercontent.com/user/repo/main/README.md | showdown makehtml
215

216
# From echo
217
echo "**Bold text**" | showdown makehtml
218

219
# From cat
220
cat *.md | showdown makehtml --flavor github
221
```
222

223
### Pipe to other commands
224

225
```bash
226
# Pipe to less for viewing
227
showdown makehtml -i large-doc.md | less
228

229
# Pipe to file with additional processing
230
showdown makehtml -i input.md | sed 's/old/new/g' > output.html
231

232
# Count output lines
233
showdown makehtml -i input.md | wc -l
234
```
235

236
## Batch Processing
237

238
Process multiple files:
239

240
```bash
241
# Using shell loop
242
for file in *.md; do
243
  showdown makehtml -i "$file" -o "${file%.md}.html" --flavor github
244
done
245

246
# Using find and xargs
247
find . -name "*.md" -exec showdown makehtml -i {} -o {}.html \;
248
```
249

250
## Performance Tips
251

252
- Use `--quiet` or `--mute` for batch processing to reduce output
253
- Load extensions once per batch rather than per file when possible
254
- Consider using the JavaScript API for high-volume processing
255
- Specify encoding explicitly to avoid detection overhead