0
# Command Line Interface
1

2
Comprehensive CLI tool for generating markdown documentation from JSDoc-annotated JavaScript source code. The CLI provides all programmatic API functionality plus additional modes and configuration options.
3

4
## Capabilities
5

6
### Basic Command Usage
7

8
Generate markdown documentation from JavaScript files using the `jsdoc2md` command.
9

10
```bash { .api }
11
# Basic usage with files
12
jsdoc2md <files...>
13

14
# Using glob patterns
15
jsdoc2md "src/**/*.js"
16

17
# Multiple files
18
jsdoc2md file1.js file2.js lib/*.js
19
```
20

21
**Usage Examples:**
22

23
```bash
24
# Generate docs from all JS files in src directory
25
jsdoc2md src/*.js
26

27
# Process specific files
28
jsdoc2md index.js lib/utils.js lib/helpers.js
29

30
# Use glob patterns for complex file selection
31
jsdoc2md "src/**/*.js" "!src/**/*.test.js"
32
```
33

34
### Output Modes
35

36
The CLI supports multiple output modes for different use cases.
37

38
```bash { .api }
39
# Standard markdown output (default)
40
jsdoc2md [options] <files>
41

42
# JSON template data output
43
jsdoc2md [options] <files> --json
44

45
# Raw JSDoc data output  
46
jsdoc2md [options] <files> --jsdoc
47

48
# Namepath information output
49
jsdoc2md [options] <files> --namepaths
50
```
51

52
**Usage Examples:**
53

54
```bash
55
# Generate markdown documentation
56
jsdoc2md src/*.js > docs/API.md
57

58
# Get JSON template data for custom processing
59
jsdoc2md src/*.js --json > template-data.json
60

61
# Get raw JSDoc data for analysis
62
jsdoc2md src/*.js --jsdoc > jsdoc-data.json
63

64
# Get namepath information
65
jsdoc2md src/*.js --namepaths > namepaths.json
66
```
67

68
### Documentation Formatting Options
69

70
Control the appearance and structure of generated markdown.
71

72
```bash { .api }
73
# Heading depth control
74
jsdoc2md [files] --heading-depth <number>
75

76
# Example code language
77
jsdoc2md [files] --example-lang <language>
78

79
# Formatting options
80
jsdoc2md [files] --name-format --separators --no-gfm
81

82
# Index formatting
83
jsdoc2md [files] --module-index-format <format> --global-index-format <format>
84

85
# List formatting
86
jsdoc2md [files] --param-list-format <format> --property-list-format <format>
87

88
# Link formatting
89
jsdoc2md [files] --clever-links --monospace-links
90
```
91

92
**Usage Examples:**
93

94
```bash
95
# Set heading depth and example language
96
jsdoc2md src/*.js --heading-depth 1 --example-lang javascript
97

98
# Format identifiers as code and add separators
99
jsdoc2md src/*.js --name-format --separators
100

101
# Disable GitHub-flavored markdown
102
jsdoc2md src/*.js --no-gfm
103

104
# Customize index and list formats
105
jsdoc2md src/*.js --module-index-format table --param-list-format list
106

107
# Configure link rendering
108
jsdoc2md src/*.js --clever-links
109
```
110

111
### Template Customization
112

113
Use custom templates and plugins to control output generation.
114

115
```bash { .api }
116
# Custom template file
117
jsdoc2md [files] --template <template-file>
118

119
# Plugin support
120
jsdoc2md [files] --plugin <plugin-name>
121

122
# Helper and partial files
123
jsdoc2md [files] --helper <helper-file> --partial <partial-file>
124
```
125

126
**Usage Examples:**
127

128
```bash
129
# Use custom Handlebars template
130
jsdoc2md src/*.js --template custom-template.hbs
131

132
# Use a plugin for additional helpers
133
jsdoc2md src/*.js --plugin dmd-plugin-enhanced
134

135
# Add custom helpers and partials
136
jsdoc2md src/*.js --helper custom-helpers.js --partial custom-partials.hbs
137

138
# Combine multiple customizations
139
jsdoc2md src/*.js --template my-template.hbs --plugin my-plugin --helper helpers.js
140
```
141

142
### Input Source Options
143

144
Specify input sources in different ways beyond file paths.
145

146
```bash { .api }
147
# Source code from stdin or string
148
jsdoc2md --source <source-code>
149

150
# JSDoc configuration file
151
jsdoc2md --configure <config-file>
152

153
# File input (default)
154
jsdoc2md --files <files...>
155
```
156

157
**Usage Examples:**
158

159
```bash
160
# Process source code directly
161
jsdoc2md --source "/**
162
 * Add two numbers
163
 * @param {number} a
164
 * @param {number} b  
165
 * @returns {number}
166
 */
167
function add(a, b) { return a + b; }"
168

169
# Use JSDoc configuration file
170
jsdoc2md --configure jsdoc.conf.json
171

172
# Explicit file specification
173
jsdoc2md --files src/index.js src/utils.js
174
```
175

176
### Cache and Configuration Management
177

178
Control caching behavior and view configuration.
179

180
```bash { .api }
181
# Cache control
182
jsdoc2md [options] --no-cache
183
jsdoc2md --clear
184

185
# Configuration inspection
186
jsdoc2md --config
187

188
# Help and version
189
jsdoc2md --help
190
jsdoc2md --version
191
```
192

193
**Usage Examples:**
194

195
```bash
196
# Disable caching for this run
197
jsdoc2md src/*.js --no-cache
198

199
# Clear the cache
200
jsdoc2md --clear
201

202
# View current configuration
203
jsdoc2md --config
204

205
# Get help
206
jsdoc2md --help
207

208
# Check version
209
jsdoc2md --version
210
```
211

212
## CLI Options Reference
213

214
### JSDoc Options
215

216
Options for controlling JSDoc parsing and input sources.
217

218
```bash { .api }
219
--files, -f <files...>        # Files or glob patterns to process
220
--source <code>               # Source code string to process  
221
--configure, -c <file>        # Path to JSDoc configuration file
222
--namepaths                   # Print namepaths only
223
```
224

225
### jsdoc2md Options
226

227
Main tool options affecting operation mode and behavior.
228

229
```bash { .api }
230
--help, -h                    # Print usage information
231
--config                      # Print all supplied options and exit
232
--json                        # Print template data (jsdoc-parse output)
233
--jsdoc                       # Print raw JSDoc data
234
--version                     # Print version number
235
--no-cache                    # Disable caching for this invocation
236
--clear                       # Clear the cache and exit
237
```
238

239
### DMD (Output) Options
240

241
Options controlling markdown output formatting and appearance.
242

243
```bash { .api }
244
--template, -t <file>         # Custom handlebars template file
245
--private                     # Include @private identifiers
246
--heading-depth, -d <number>  # Root heading depth (default: 2)
247
--plugin <modules...>         # Installed packages with helper/partial overrides
248
--helper <modules...>         # Handlebars helper modules
249
--partial <files...>          # Handlebars partial files
250
--example-lang, -l <lang>     # Default language for @example blocks
251
--name-format                 # Format identifier names as code
252
--no-gfm                      # Disable GitHub-flavored markdown
253
--separators                  # Add <hr> breaks between identifiers
254
--module-index-format, -m <format>  # Module index style: none, grouped, table, dl
255
--global-index-format, -g <format>  # Global index style: none, grouped, table, dl
256
--param-list-format, -p <format>    # Parameter list style: list, table
257
--property-list-format, -r <format> # Property list style: list, table
258
--member-index-format <format>      # Member list style: list, grouped
259
--clever-links                # Render URL links plaintext, others monospace
260
--monospace-links             # Render all links in monospace
261
--EOL <type>                  # Line ending type: posix, win32
262
```
263

264
## Configuration Files
265

266
The CLI supports configuration files in multiple formats:
267

268
### package.json Configuration
269

270
```json
271
{
272
  "jsdoc2md": {
273
    "files": "src/*.js",
274
    "heading-depth": 1,
275
    "example-lang": "javascript",
276
    "separators": true
277
  }
278
}
279
```
280

281
### .jsdoc2md.json Configuration
282

283
```json
284
{
285
  "files": ["src/index.js", "src/utils.js"],
286
  "template": "templates/api.hbs",
287
  "heading-depth": 1,
288
  "name-format": true,
289
  "param-list-format": "list"
290
}
291
```
292

293
## Integration Examples
294

295
### NPM Scripts Integration
296

297
```json
298
{
299
  "scripts": {
300
    "docs": "jsdoc2md src/*.js > docs/API.md",
301
    "docs:watch": "nodemon --watch src --ext js --exec 'npm run docs'",
302
    "docs:json": "jsdoc2md src/*.js --json > docs/template-data.json"
303
  }
304
}
305
```
306

307
### Build Process Integration
308

309
```bash
310
# Generate docs as part of build
311
npm run build && jsdoc2md dist/*.js > docs/API.md
312

313
# Pre-commit hook
314
#!/bin/sh
315
jsdoc2md src/*.js > README_API.md
316
git add README_API.md
317
```
318

319
### Custom Template Usage
320

321
```bash
322
# Create custom template
323
echo '# {{package.name}} API\n{{>main}}' > api-template.hbs
324

325
# Use custom template
326
jsdoc2md src/*.js --template api-template.hbs > API.md
327
```
328

329
## Error Handling
330

331
CLI error handling includes comprehensive error messages and exit codes:
332

333
- **Exit code 0**: Success
334
- **Exit code 1**: Error (file not found, parsing error, etc.)
335

336
```bash
337
# Handle errors in scripts
338
if ! jsdoc2md src/*.js > docs/API.md; then
339
  echo "Documentation generation failed"
340
  exit 1
341
fi
342
```