0
# Command Line Interface
1

2
The `mmdc` command provides a comprehensive CLI for converting Mermaid diagrams to various output formats. It supports single diagram conversion, markdown processing, and extensive customization options.
3

4
## Capabilities
5

6
### Basic Diagram Conversion
7

8
Convert Mermaid diagram files to SVG, PNG, or PDF formats.
9

10
```bash { .api }
11
mmdc -i <input> -o <output>
12
```
13

14
**Parameters:**
15
- `-i, --input <input>`: Input mermaid file path or "-" for stdin
16
- `-o, --output [output]`: Output file path or "-" for stdout
17

18
**Usage Examples:**
19

20
```bash
21
# Convert .mmd file to SVG
22
mmdc -i diagram.mmd -o diagram.svg
23

24
# Convert to PNG
25
mmdc -i flowchart.mmd -o flowchart.png
26

27
# Convert to PDF
28
mmdc -i sequence.mmd -o sequence.pdf
29

30
# Read from stdin, write to stdout
31
cat diagram.mmd | mmdc -i - -o -
32
```
33

34
### Output Format Selection
35

36
Specify the output format explicitly when it cannot be inferred from the file extension.
37

38
```bash { .api }
39
mmdc -e <format>
40
```
41

42
**Parameters:**
43
- `-e, --outputFormat [format]`: Output format (svg, png, pdf)
44

45
**Usage Examples:**
46

47
```bash
48
# Force SVG output even if output file has different extension
49
mmdc -i input.mmd -o diagram.img -e svg
50

51
# Use with stdout output
52
mmdc -i input.mmd -o - -e png
53
```
54

55
### Theme and Styling
56

57
Customize the appearance of generated diagrams with themes, colors, and CSS.
58

59
```bash { .api }
60
mmdc -t <theme> -b <color> -C <cssFile>
61
```
62

63
**Parameters:**
64
- `-t, --theme [theme]`: Chart theme (default, forest, dark, neutral)
65
- `-b, --backgroundColor [color]`: Background color (transparent, red, '#F0F0F0', etc.)
66
- `-C, --cssFile [file]`: CSS file for custom styling
67

68
**Usage Examples:**
69

70
```bash
71
# Dark theme with transparent background
72
mmdc -i input.mmd -o output.png -t dark -b transparent
73

74
# Custom CSS styling
75
mmdc -i input.mmd -o output.svg -C custom-styles.css
76

77
# Specific background color
78
mmdc -i input.mmd -o output.png -b '#E8F4FD'
79
```
80

81
### Page Dimensions and Scaling
82

83
Control the size and scale of the output image.
84

85
```bash { .api }
86
mmdc -w <width> -H <height> -s <scale>
87
```
88

89
**Parameters:**
90
- `-w, --width [width]`: Page width in pixels (default: 800)
91
- `-H, --height [height]`: Page height in pixels (default: 600)
92
- `-s, --scale [scale]`: Puppeteer scale factor (default: 1)
93

94
**Usage Examples:**
95

96
```bash
97
# Large canvas size
98
mmdc -i input.mmd -o output.png -w 1600 -H 1200
99

100
# High DPI output
101
mmdc -i input.mmd -o output.png -s 2
102

103
# PDF with fit-to-content
104
mmdc -i input.mmd -o output.pdf -f
105
```
106

107
### Configuration Files
108

109
Use external configuration files for Mermaid and Puppeteer settings.
110

111
```bash { .api }
112
mmdc -c <configFile> -p <puppeteerConfigFile>
113
```
114

115
**Parameters:**
116
- `-c, --configFile [file]`: JSON configuration file for Mermaid
117
- `-p, --puppeteerConfigFile [file]`: JSON configuration file for Puppeteer
118

119
**Usage Examples:**
120

121
```bash
122
# Use Mermaid config file
123
mmdc -i input.mmd -o output.svg -c mermaid-config.json
124

125
# Use both config files
126
mmdc -i input.mmd -o output.png -c mermaid.json -p puppeteer.json
127
```
128

129
**Example Mermaid config file:**
130

131
```json
132
{
133
  "theme": "dark",
134
  "themeVariables": {
135
    "primaryColor": "#ff6b6b",
136
    "primaryTextColor": "#ffffff",
137
    "primaryBorderColor": "#ff4757"
138
  },
139
  "flowchart": {
140
    "useMaxWidth": false,
141
    "htmlLabels": true
142
  }
143
}
144
```
145

146
**Example Puppeteer config file:**
147

148
```json
149
{
150
  "headless": "shell",
151
  "args": ["--no-sandbox", "--disable-setuid-sandbox"],
152
  "timeout": 30000
153
}
154
```
155

156
### Markdown Processing
157

158
Process markdown files containing embedded Mermaid diagrams, extracting and converting them to images.
159

160
```bash { .api }
161
mmdc -i <markdown> -o <output> -a <artefacts>
162
```
163

164
**Parameters:**
165
- `-a, --artefacts [path]`: Output directory for generated diagram images
166

167
**Usage Examples:**
168

169
```bash
170
# Process README.md and generate diagram images
171
mmdc -i README.md -o README-processed.md
172

173
# Store images in specific directory
174
mmdc -i documentation.md -o docs-processed.md -a ./diagrams
175
```
176

177
**Markdown Input Example:**
178

179
```markdown
180
# Project Documentation
181

182
Here's our system architecture:
183

184
\`\`\`mermaid
185
graph TD
186
    A[Client] --> B[Load Balancer]
187
    B --> C[Web Server]
188
\`\`\`
189

190
And here's the user flow:
191

192
\`\`\`mermaid
193
sequenceDiagram
194
    User->>App: Login request
195
    App->>DB: Validate credentials
196
\`\`\`
197
```
198

199
**Generated Output:**
200

201
```markdown
202
# Project Documentation
203

204
Here's our system architecture:
205

206
![diagram](./README-processed-1.svg)
207

208
And here's the user flow:
209

210
![diagram](./README-processed-2.svg)
211
```
212

213
### Advanced Options
214

215
Additional options for specialized use cases.
216

217
```bash { .api }
218
mmdc -I <svgId> -f -q --iconPacks <packages>
219
```
220

221
**Parameters:**
222
- `-I, --svgId [id]`: The id attribute for the SVG element
223
- `-f, --pdfFit`: Scale PDF to fit chart dimensions
224
- `-q, --quiet`: Suppress log output
225
- `--iconPacks <packages...>`: Icon packs to use (Iconify NPM packages)
226

227
**Usage Examples:**
228

229
```bash
230
# Custom SVG ID
231
mmdc -i input.mmd -o output.svg -I "my-diagram"
232

233
# PDF with fit-to-content scaling
234
mmdc -i large-diagram.mmd -o output.pdf -f
235

236
# Quiet mode (no console output)
237
mmdc -i input.mmd -o output.png -q
238

239
# Use icon packs
240
mmdc -i input.mmd -o output.svg --iconPacks @iconify-json/logos @iconify-json/mdi
241
```
242

243
### Error Handling
244

245
The CLI exits with code 0 on success and code 1 on error. Error messages are printed to stderr.
246

247
**Common Error Scenarios:**
248

249
```bash
250
# Input file doesn't exist
251
mmdc -i nonexistent.mmd -o output.svg
252
# Error: Input file "nonexistent.mmd" doesn't exist
253

254
# Invalid output format
255
mmdc -i input.mmd -o output.xyz
256
# Error: Output file must end with ".md"/".markdown", ".svg", ".png" or ".pdf"
257

258
# Invalid theme
259
mmdc -i input.mmd -o output.svg -t invalid
260
# Error: argument '-t, --theme [theme]' argument 'invalid' is invalid. Allowed choices are default, forest, dark, neutral.
261
```
262

263
### Help and Version
264

265
Get help information and version details.
266

267
```bash { .api }
268
mmdc -h
269
mmdc --version
270
```
271

272
**Usage Examples:**
273

274
```bash
275
# Show help
276
mmdc -h
277

278
# Show version
279
mmdc --version
280
```