0
# CLI Interface
1

2
Command-line interface for server-side rendering and batch processing, supporting all KaTeX options and file I/O operations.
3

4
## Installation and Usage
5

6
```bash
7
# Install KaTeX globally for CLI access
8
npm install -g katex
9

10
# Or use npx for one-time usage
11
npx katex --help
12
```
13

14
## Capabilities
15

16
### Basic Rendering
17

18
Convert TeX expressions to HTML using standard input/output or files.
19

20
```bash
21
# Read from stdin, output to stdout
22
echo "E = mc^2" | katex
23

24
# Read from file, output to stdout  
25
katex --input equation.tex
26

27
# Read from stdin, write to file
28
echo "\\frac{1}{2}" | katex --output result.html
29

30
# Read from file, write to file
31
katex --input math.tex --output math.html
32
```
33

34
### Display Mode
35

36
Control inline vs display math rendering.
37

38
```bash
39
# Render in display mode (centered, larger)
40
katex --display-mode --input equation.tex
41

42
# Render in inline mode (default)
43
echo "\\sum_{i=1}^n i" | katex
44
```
45

46
### Output Format
47

48
Control the output markup format.
49

50
```bash
51
# HTML + MathML output (default)
52
katex --format htmlAndMathml --input math.tex
53

54
# HTML only
55
katex --format html --input math.tex  
56

57
# MathML only
58
katex --format mathml --input math.tex
59
```
60

61
### Error Handling
62

63
Configure error behavior and styling.
64

65
```bash
66
# Suppress errors, show error text instead of throwing
67
katex --no-throw-on-error --input bad-math.tex
68

69
# Custom error color (without # prefix)
70
katex --no-throw-on-error --error-color ff6b6b --input bad-math.tex
71

72
# Default behavior: throw on errors
73
katex --input bad-math.tex  # Will exit with error code
74
```
75

76
### Macro Definitions
77

78
Define custom macros via command line or macro files.
79

80
```bash
81
# Single macro definition  
82
katex --macro "\\RR:\\mathbb{R}" --input math.tex
83

84
# Multiple macros
85
katex \
86
  --macro "\\RR:\\mathbb{R}" \
87
  --macro "\\NN:\\mathbb{N}" \
88
  --macro "\\d:\\mathrm{d}" \
89
  --input math.tex
90

91
# Macros from file (one per line, format: \macro:expansion)
92
katex --macro-file macros.txt --input math.tex
93
```
94

95
**Example macro file (`macros.txt`):**
96
```
97
\RR:\mathbb{R}
98
\NN:\mathbb{N} 
99
\ZZ:\mathbb{Z}
100
\CC:\mathbb{C}
101
\d:\mathrm{d}
102
\diff:\frac{\mathrm{d}#1}{\mathrm{d}#2}
103
```
104

105
### Advanced Options
106

107
Configure LaTeX compatibility, security, and performance.
108

109
```bash
110
# Strict LaTeX mode
111
katex --strict --input math.tex
112

113
# Trust input for HTML features
114
katex --trust --input math-with-links.tex
115

116
# Custom rule thickness
117
katex --min-rule-thickness 0.05 --input fractions.tex
118

119
# Maximum element size limit
120
katex --max-size 50 --input large-math.tex
121

122
# Maximum macro expansions
123
katex --max-expand 500 --input macro-heavy.tex
124

125
# Color as text color mode
126
katex --color-is-text-color --input colored-math.tex
127
```
128

129
### Complete CLI Reference
130

131
```bash
132
Usage: katex [options]
133

134
Options:
135
  -V, --version                     output the version number
136
  -d, --display-mode                render in display mode
137
  -F, --format <type>               output format: htmlAndMathml, html, mathml
138
  -t, --no-throw-on-error          render errors instead of throwing
139
  -c, --error-color <color>         error color (without #)
140
  -m, --macro <def>                 define macro: \name:expansion
141
  -f, --macro-file <path>           read macros from file
142
  -b, --color-is-text-color         \color behaves like \textcolor
143
  -S, --strict                      strict LaTeX mode
144
  -T, --trust                       trust input (enable HTML features)
145
  -s, --max-size <n>                maximum element size in ems
146
  -e, --max-expand <n>              maximum macro expansions
147
  --min-rule-thickness <size>       minimum rule thickness in ems
148
  -i, --input <path>                input file path
149
  -o, --output <path>               output file path
150
  -h, --help                        display help
151
```
152

153
### Batch Processing
154

155
Process multiple files using shell scripting:
156

157
```bash
158
# Process all .tex files in directory
159
for file in *.tex; do
160
  katex --input "$file" --output "${file%.tex}.html"
161
done
162

163
# Process with consistent options
164
find . -name "*.tex" -exec katex \
165
  --display-mode \
166
  --no-throw-on-error \
167
  --macro-file macros.txt \
168
  --input {} \
169
  --output {}.html \;
170
```
171

172
### Integration Examples
173

174
**Node.js Script:**
175
```javascript
176
const { execSync } = require('child_process');
177

178
function renderTeX(tex, options = {}) {
179
  const args = [];
180
  
181
  if (options.displayMode) args.push('--display-mode');
182
  if (options.noThrow) args.push('--no-throw-on-error');
183
  if (options.format) args.push(`--format ${options.format}`);
184
  
185
  const cmd = `echo "${tex}" | katex ${args.join(' ')}`;
186
  return execSync(cmd, { encoding: 'utf8' });
187
}
188

189
const html = renderTeX('E = mc^2', { displayMode: true });
190
console.log(html);
191
```
192

193
**Build Tool Integration:**
194
```javascript
195
// webpack.config.js
196
const { execSync } = require('child_process');
197

198
module.exports = {
199
  plugins: [
200
    {
201
      apply: (compiler) => {
202
        compiler.hooks.emit.tap('KatexPlugin', (compilation) => {
203
          // Process .tex assets
204
          Object.keys(compilation.assets)
205
            .filter(name => name.endsWith('.tex'))
206
            .forEach(name => {
207
              const source = compilation.assets[name].source();
208
              const html = execSync(`echo "${source}" | katex --display-mode`, 
209
                                  { encoding: 'utf8' });
210
              compilation.assets[name.replace('.tex', '.html')] = {
211
                source: () => html,
212
                size: () => html.length
213
              };
214
            });
215
        });
216
      }
217
    }
218
  ]
219
};
220
```
221

222
### Server-Side Rendering
223

224
Use CLI for server-side math rendering:
225

226
```bash
227
# Express.js endpoint simulation
228
echo "\\int_0^\\infty e^{-x^2} dx" | \
229
  katex --display-mode --format html > /tmp/math.html
230

231
# Static site generation
232
for markdown in content/*.md; do
233
  # Extract math blocks and render them
234
  sed -n '/```math/,/```/p' "$markdown" | \
235
    sed '1d;$d' | \
236
    katex --display-mode --output "${markdown%.md}-math.html"
237
done
238
```