0
# Command Line Interface
1

2
Command-line tool for processing markdown files and generating table of contents with support for file modification, custom formatting, and JSON output.
3

4
## Capabilities
5

6
### Basic Usage
7

8
The CLI provides a simple interface for TOC generation from files or stdin.
9

10
```bash { .api }
11
# Generate TOC and print to stdout
12
markdown-toc <input-file>
13

14
# Read from stdin
15
echo "# Title\n## Section" | markdown-toc -
16

17
# Generate TOC and inject into file  
18
markdown-toc -i <input-file>
19
```
20

21
**Usage Examples:**
22

23
```bash
24
# Basic TOC generation
25
markdown-toc README.md
26

27
# Process from stdin
28
cat document.md | markdown-toc -
29

30
# Inject TOC into file between <!-- toc --> markers
31
markdown-toc -i README.md
32
```
33

34
### Command Options
35

36
Comprehensive options for customizing CLI behavior.
37

38
```bash { .api }
39
markdown-toc [options] <input>
40

41
Options:
42
  -i                    Edit the input file directly, injecting TOC at <!-- toc -->
43
  --json                Print the TOC in JSON format  
44
  --append <string>     Append a string to the end of the TOC
45
  --bullets <chars>     Bullets to use for items in the generated TOC
46
  --maxdepth <number>   Use headings whose depth is at most maxdepth (default: 6)
47
  --no-firsth1          Include the first h1-level heading in a file
48
  --no-stripHeadingTags Do not strip extraneous HTML tags from heading text
49

50
Arguments:
51
  <input>               The Markdown file to parse for TOC, or "-" for stdin
52
```
53

54
**Usage Examples with Options:**
55

56
```bash
57
# Limit depth and customize bullets
58
markdown-toc --maxdepth 3 --bullets "*" README.md
59

60
# Multiple bullet types for different levels
61
markdown-toc --bullets "*" --bullets "-" --bullets "+" README.md
62

63
# Include first H1 and append footer
64
markdown-toc --no-firsth1 --append "_(Generated by markdown-toc)_" README.md
65

66
# Output JSON format
67
markdown-toc --json README.md
68

69
# Combine multiple options
70
markdown-toc -i --maxdepth 2 --bullets "-" --append "\n\n*Auto-generated*" docs/API.md
71
```
72

73
### File Processing
74

75
In-place file modification with the `-i` flag.
76

77
```bash
78
# Before: README.md contains <!-- toc --> marker
79
markdown-toc -i README.md
80
# After: README.md has TOC injected at marker location
81

82
# Process multiple files (using shell globbing)
83
for file in docs/*.md; do
84
  markdown-toc -i --maxdepth 3 "$file"
85
done
86
```
87

88
### JSON Output
89

90
Structured JSON output for programmatic use.
91

92
```bash
93
markdown-toc --json README.md
94
```
95

96
```json
97
[
98
  {
99
    "content": "Introduction", 
100
    "slug": "introduction",
101
    "lvl": 1,
102
    "i": 0,
103
    "seen": 0
104
  },
105
  {
106
    "content": "Getting Started",
107
    "slug": "getting-started", 
108
    "lvl": 2,
109
    "i": 1,
110
    "seen": 0
111
  }
112
]
113
```
114

115
### Standard Input Processing
116

117
Process markdown content from stdin for pipeline usage.
118

119
```bash
120
# Generate TOC from stdin
121
echo -e "# Title\n## Section\n### Subsection" | markdown-toc -
122

123
# Pipeline processing
124
curl -s https://raw.githubusercontent.com/user/repo/main/README.md | markdown-toc -
125

126
# Process with options
127
cat document.md | markdown-toc --maxdepth 2 --bullets "•" -
128
```
129

130
### Error Handling
131

132
The CLI includes comprehensive error handling and validation.
133

134
```bash
135
# Invalid usage examples that trigger errors:
136

137
# Missing input file
138
markdown-toc
139
# Error: Usage: markdown-toc [options] <input>
140

141
# Using -i with stdin  
142
echo "# Title" | markdown-toc -i -
143
# Error: markdown-toc: you cannot use -i with "-" (stdin) for input
144

145
# Using -i with --json
146
markdown-toc -i --json README.md  
147
# Error: markdown-toc: you cannot use both --json and -i
148

149
# File not found
150
markdown-toc nonexistent.md
151
# Error: ENOENT: no such file or directory
152
```
153

154
### Integration Examples
155

156
Common integration patterns for build processes and automation.
157

158
```bash
159
# In package.json scripts
160
{
161
  "scripts": {
162
    "docs:toc": "markdown-toc -i README.md",
163
    "docs:build": "markdown-toc -i --maxdepth 3 docs/*.md"
164
  }
165
}
166

167
# In Makefile
168
docs-toc:
169
	find docs -name "*.md" -exec markdown-toc -i --maxdepth 2 {} \;
170

171
# In CI/CD pipeline  
172
script:
173
  - markdown-toc --json README.md > toc.json
174
  - markdown-toc -i --maxdepth 3 --append "_(Updated: $(date))_" docs/API.md
175
```
176

177
### Batch Processing
178

179
Process multiple files with consistent options.
180

181
```bash
182
# Process all markdown files in directory
183
find . -name "*.md" -not -path "./node_modules/*" | \
184
  xargs -I {} markdown-toc -i --maxdepth 3 --bullets "-" {}
185

186
# Generate TOC for all files and save outputs
187
for file in docs/*.md; do
188
  basename=$(basename "$file" .md)
189
  markdown-toc "$file" > "toc-${basename}.md"
190
done
191
```
192

193
### Advanced Usage
194

195
Complex processing scenarios combining options.
196

197
```bash
198
# Generate detailed TOC with custom formatting
199
markdown-toc \
200
  --maxdepth 4 \
201
  --bullets "▶" \
202
  --append "\n\n---\n*Table of contents generated on $(date)*" \
203
  --no-stripHeadingTags \
204
  documentation.md
205

206
# Process with custom bullets for each level
207
markdown-toc \
208
  --bullets "•" \
209
  --bullets "◦" \
210
  --bullets "▪" \
211
  --bullets "▫" \
212
  complex-document.md
213
```
214

215
### Exit Codes
216

217
The CLI uses standard exit codes for error handling.
218

219
```bash
220
# Success
221
markdown-toc README.md
222
echo $? # Output: 0
223

224
# File not found
225
markdown-toc missing.md
226
echo $? # Output: 1
227

228
# Invalid arguments  
229
markdown-toc -i --json README.md
230
echo $? # Output: 1
231
```