0
# Input Processing
1

2
MathJax supports three mathematical notation formats: TeX/LaTeX, MathML, and AsciiMath. Each input processor provides conversion to various output formats with extensive customization options.
3

4
## Capabilities
5

6
### TeX/LaTeX Input
7

8
Process TeX and LaTeX mathematical notation with support for packages, macros, and environments.
9

10
```javascript { .api }
11
/**
12
 * Convert TeX to SVG output
13
 * @param tex - TeX/LaTeX string to convert
14
 * @param options - Conversion options
15
 * @returns SVG element containing the rendered mathematics
16
 */
17
function tex2svg(tex: string, options?: ConversionOptions): Element;
18

19
/**
20
 * Convert TeX to CommonHTML output
21
 * @param tex - TeX/LaTeX string to convert
22
 * @param options - Conversion options
23
 * @returns HTML element containing the rendered mathematics
24
 */
25
function tex2chtml(tex: string, options?: ConversionOptions): Element;
26

27
/**
28
 * Convert TeX to MathML
29
 * @param tex - TeX/LaTeX string to convert
30
 * @param options - Conversion options
31
 * @returns MathML string representation
32
 */
33
function tex2mml(tex: string, options?: ConversionOptions): string;
34

35
/**
36
 * Convert TeX to SVG (Promise-based)
37
 * @param tex - TeX/LaTeX string to convert
38
 * @param options - Conversion options
39
 * @returns Promise resolving to SVG element
40
 */
41
function tex2svgPromise(tex: string, options?: ConversionOptions): Promise<Element>;
42

43
/**
44
 * Convert TeX to CommonHTML (Promise-based)
45
 * @param tex - TeX/LaTeX string to convert
46
 * @param options - Conversion options
47
 * @returns Promise resolving to HTML element
48
 */
49
function tex2chtmlPromise(tex: string, options?: ConversionOptions): Promise<Element>;
50

51
/**
52
 * Convert TeX to MathML (Promise-based)
53
 * @param tex - TeX/LaTeX string to convert
54
 * @param options - Conversion options
55
 * @returns Promise resolving to MathML string
56
 */
57
function tex2mmlPromise(tex: string, options?: ConversionOptions): Promise<string>;
58

59
/**
60
 * Reset TeX input processor
61
 * @param args - Reset arguments
62
 */
63
function texReset(...args: any[]): void;
64
```
65

66
**Usage Examples:**
67

68
```javascript
69
// Basic TeX conversion
70
const svg = MathJax.tex2svg('E = mc^2');
71
const html = MathJax.tex2chtml('\\frac{x^2}{2}');
72
const mml = MathJax.tex2mml('\\sum_{i=1}^n x_i');
73

74
// With display options
75
const displayMath = MathJax.tex2svg('\\int_0^\\infty e^{-x} dx', {
76
  display: true,
77
  em: 16,
78
  ex: 8
79
});
80

81
// Inline math
82
const inlineMath = MathJax.tex2chtml('x^2 + y^2 = z^2', {
83
  display: false
84
});
85

86
// Promise-based conversion
87
const result = await MathJax.tex2svgPromise('\\begin{matrix} a & b \\\\ c & d \\end{matrix}');
88
```
89

90
### MathML Input
91

92
Process MathML (Mathematical Markup Language) with support for both presentation and content MathML.
93

94
```javascript { .api }
95
/**
96
 * Convert MathML to SVG output
97
 * @param mathml - MathML string to convert
98
 * @param options - Conversion options
99
 * @returns SVG element containing the rendered mathematics
100
 */
101
function mml2svg(mathml: string, options?: ConversionOptions): Element;
102

103
/**
104
 * Convert MathML to CommonHTML output
105
 * @param mathml - MathML string to convert
106
 * @param options - Conversion options
107
 * @returns HTML element containing the rendered mathematics
108
 */
109
function mml2chtml(mathml: string, options?: ConversionOptions): Element;
110

111
/**
112
 * Convert MathML to SVG (Promise-based)
113
 * @param mathml - MathML string to convert
114
 * @param options - Conversion options
115
 * @returns Promise resolving to SVG element
116
 */
117
function mml2svgPromise(mathml: string, options?: ConversionOptions): Promise<Element>;
118

119
/**
120
 * Convert MathML to CommonHTML (Promise-based)
121
 * @param mathml - MathML string to convert
122
 * @param options - Conversion options
123
 * @returns Promise resolving to HTML element
124
 */
125
function mml2chtmlPromise(mathml: string, options?: ConversionOptions): Promise<Element>;
126

127
/**
128
 * Reset MathML input processor
129
 * @param args - Reset arguments
130
 */
131
function mmlReset(...args: any[]): void;
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
// Basic MathML conversion
138
const mathml = '<math><mfrac><mi>x</mi><mi>y</mi></mfrac></math>';
139
const svg = MathJax.mml2svg(mathml);
140
const html = MathJax.mml2chtml(mathml);
141

142
// Complex MathML
143
const complexMml = `
144
  <math display="block">
145
    <mrow>
146
      <mi>x</mi>
147
      <mo>=</mo>
148
      <mfrac>
149
        <mrow>
150
          <mo>-</mo>
151
          <mi>b</mi>
152
          <mo>±</mo>
153
          <msqrt>
154
            <msup><mi>b</mi><mn>2</mn></msup>
155
            <mo>-</mo>
156
            <mn>4</mn>
157
            <mi>a</mi>
158
            <mi>c</mi>
159
          </msqrt>
160
        </mrow>
161
        <mrow>
162
          <mn>2</mn>
163
          <mi>a</mi>
164
        </mrow>
165
      </mfrac>
166
    </mrow>
167
  </math>
168
`;
169
const result = MathJax.mml2svg(complexMml, { display: true });
170

171
// Promise-based conversion
172
const asyncResult = await MathJax.mml2chtmlPromise(mathml);
173
```
174

175
### AsciiMath Input
176

177
Process AsciiMath notation, a simple text-based format for mathematical expressions.
178

179
```javascript { .api }
180
/**
181
 * Convert AsciiMath to SVG output
182
 * @param ascii - AsciiMath string to convert
183
 * @param options - Conversion options
184
 * @returns SVG element containing the rendered mathematics
185
 */
186
function asciimath2svg(ascii: string, options?: ConversionOptions): Element;
187

188
/**
189
 * Convert AsciiMath to CommonHTML output
190
 * @param ascii - AsciiMath string to convert
191
 * @param options - Conversion options
192
 * @returns HTML element containing the rendered mathematics
193
 */
194
function asciimath2chtml(ascii: string, options?: ConversionOptions): Element;
195

196
/**
197
 * Convert AsciiMath to SVG (Promise-based)
198
 * @param ascii - AsciiMath string to convert
199
 * @param options - Conversion options
200
 * @returns Promise resolving to SVG element
201
 */
202
function asciimath2svgPromise(ascii: string, options?: ConversionOptions): Promise<Element>;
203

204
/**
205
 * Convert AsciiMath to CommonHTML (Promise-based)
206
 * @param ascii - AsciiMath string to convert
207
 * @param options - Conversion options
208
 * @returns Promise resolving to HTML element
209
 */
210
function asciimath2chtmlPromise(ascii: string, options?: ConversionOptions): Promise<Element>;
211

212
/**
213
 * Reset AsciiMath input processor
214
 * @param args - Reset arguments
215
 */
216
function asciimathReset(...args: any[]): void;
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
// Basic AsciiMath conversion
223
const svg = MathJax.asciimath2svg('x^2 + y^2 = z^2');
224
const html = MathJax.asciimath2chtml('sum_(i=1)^n x_i');
225

226
// Complex expressions
227
const integral = MathJax.asciimath2svg('int_0^oo e^(-x) dx');
228
const matrix = MathJax.asciimath2chtml('[[a,b],[c,d]]');
229
const fraction = MathJax.asciimath2svg('(x^2)/(2a)');
230
```
231

232
## Configuration Options
233

234
### TeX Configuration
235

236
```javascript { .api }
237
interface TexOptions {
238
  /** Extension packages to load */
239
  packages?: string[];
240
  /** Custom macro definitions */
241
  macros?: Record<string, string | [string, number]>;
242
  /** Custom environment definitions */
243
  environments?: Record<string, any>;
244
  /** Process backslash escapes in text */
245
  processEscapes?: boolean;
246
  /** Process LaTeX environments */
247
  processEnvironments?: boolean;
248
  /** Process equation references */
249
  processRefs?: boolean;
250
  /** Pattern for digit recognition */
251
  digits?: RegExp;
252
  /** Equation tag format */
253
  tags?: 'none' | 'ams' | 'all';
254
  /** Tag placement side */
255
  tagSide?: 'right' | 'left';
256
  /** Tag indentation */
257
  tagIndent?: string;
258
  /** Use label IDs for references */
259
  useLabelIds?: boolean;
260
  /** Inline math delimiters */
261
  inlineMath?: Array<[string, string]>;
262
  /** Display math delimiters */
263
  displayMath?: Array<[string, string]>;
264
  /** Skip tags for certain elements */
265
  skipTags?: string[];
266
  /** Ignore HTML classes */
267
  ignoreClass?: RegExp | string;
268
  /** Process HTML classes */
269
  processClass?: RegExp | string;
270
}
271
```
272

273
**Configuration Example:**
274

275
```javascript
276
MathJax.config.tex = {
277
  packages: ['base', 'ams', 'color', 'physics'],
278
  macros: {
279
    R: '{\\mathbb{R}}',
280
    C: '{\\mathbb{C}}',
281
    bold: ['{\\mathbf{#1}}', 1],
282
    vec: ['{\\boldsymbol{#1}}', 1]
283
  },
284
  environments: {
285
    braced: ['\\left\\{', '\\right\\}']
286
  },
287
  inlineMath: [['$', '$'], ['\\(', '\\)']],
288
  displayMath: [['$$', '$$'], ['\\[', '\\]']],
289
  processEscapes: true,
290
  tags: 'ams',
291
  tagSide: 'right'
292
};
293
```
294

295
### MathML Extensions
296

297
MathML input supports the MML3 extension for MathML 3.0 features.
298

299
**Available MML Extensions:**
300
- **`[mml]/mml3`** - MathML 3.0 features and elements
301

302
**Extension Usage:**
303

304
```javascript
305
// Load MML3 extension
306
MathJax.config.loader.load.push('[mml]/mml3');
307

308
// Configure MML3 options
309
MathJax.config.mml = {
310
  packages: ['base', 'mml3']
311
};
312
```
313

314
### MathML Configuration
315

316
```javascript { .api }
317
interface MMLOptions {
318
  /** Parsing mode */
319
  parseAs?: 'html' | 'xml';
320
  /** Force reparsing of MathML */
321
  forceReparse?: boolean;
322
  /** Parse error handler */
323
  parseError?: (error: Error) => void;
324
  /** Verify MathML tree structure */
325
  verifyTree?: boolean;
326
}
327
```
328

329
**Configuration Example:**
330

331
```javascript
332
MathJax.config.mml = {
333
  parseAs: 'html',
334
  forceReparse: true,
335
  verifyTree: true,
336
  parseError: (error) => {
337
    console.warn('MathML parse error:', error.message);
338
  }
339
};
340
```
341

342
### AsciiMath Configuration
343

344
```javascript { .api }
345
interface AsciiMathOptions {
346
  /** Fix phi symbol rendering */
347
  fixphi?: boolean;
348
  /** Use display style for all expressions */
349
  displaystyle?: boolean;
350
  /** Decimal separator character */
351
  decimalsign?: string;
352
}
353
```
354

355
**Configuration Example:**
356

357
```javascript
358
MathJax.config.asciimath = {
359
  fixphi: true,
360
  displaystyle: false,
361
  decimalsign: '.'
362
};
363
```
364

365
## TeX Extensions
366

367
MathJax provides 30+ TeX extensions for specialized mathematical notation:
368

369
### Core Extensions
370

371
- **`ams`** - AMS math environments and symbols
372
- **`amscd`** - Commutative diagrams
373
- **`color`** - Color support for text and backgrounds
374
- **`newcommand`** - Define custom commands and environments
375

376
### Specialized Extensions
377

378
- **`mhchem`** - Chemistry notation and equations
379
- **`physics`** - Physics notation and operators
380
- **`braket`** - Dirac bra-ket notation
381
- **`cancel`** - Cancel expressions with lines
382
- **`bbox`** - Bounding boxes and backgrounds
383
- **`boldsymbol`** - Bold mathematical symbols
384

385
### Formatting Extensions
386

387
- **`enclose`** - Enclose expressions with lines/boxes
388
- **`textmacros`** - Text formatting commands
389
- **`unicode`** - Unicode character support
390
- **`verb`** - Verbatim text rendering
391

392
**Extension Usage:**
393

394
```javascript
395
// Load extensions
396
MathJax.config.loader.load.push('[tex]/ams', '[tex]/color', '[tex]/mhchem');
397

398
// Configure extension options
399
MathJax.config.tex = {
400
  packages: ['base', 'ams', 'color', 'mhchem'],
401
  color: {
402
    padding: '2px',
403
    borderWidth: '1px'
404
  }
405
};
406

407
// Use extension features
408
const coloredMath = MathJax.tex2svg('\\color{red}{x^2} + \\color{blue}{y^2}');
409
const chemistry = MathJax.tex2svg('\\ce{H2O + CO2 -> H2CO3}');
410
const physics = MathJax.tex2svg('\\bra{\\psi}\\hat{H}\\ket{\\psi}');
411
```
412

413
## Error Handling
414

415
### Input Processing Errors
416

417
```javascript
418
// Configure error handling for TeX
419
MathJax.config.tex.formatError = (jax, error) => {
420
  return jax.formatError(error);
421
};
422

423
// Configure error handling for MathML
424
MathJax.config.mml.parseError = (error) => {
425
  console.error('MathML parsing failed:', error.message);
426
  return error.message;
427
};
428

429
// Global error handling
430
MathJax.config.options.compileError = (doc, math, error) => {
431
  console.error('Math compilation failed:', error.message);
432
  math.typesetRoot.innerHTML = '<span style="color:red">[Math Error]</span>';
433
};
434
```
435

436
### Input Validation
437

438
```javascript
439
// Validate TeX input
440
function validateTeX(tex) {
441
  try {
442
    MathJax.tex2mml(tex);
443
    return true;
444
  } catch (error) {
445
    console.error('Invalid TeX:', error.message);
446
    return false;
447
  }
448
}
449

450
// Validate MathML input
451
function validateMathML(mathml) {
452
  try {
453
    MathJax.mml2svg(mathml);
454
    return true;
455
  } catch (error) {
456
    console.error('Invalid MathML:', error.message);
457
    return false;
458
  }
459
}
460
```
461

462
## Advanced Features
463

464
### Custom Macros and Environments
465

466
```javascript
467
// Define custom TeX macros
468
MathJax.config.tex.macros = {
469
  // Simple substitution
470
  R: '{\\mathbb{R}}',
471
  
472
  // Macro with parameters
473
  norm: ['{\\left\\|#1\\right\\|}', 1],
474
  
475
  // Multi-parameter macro
476
  frac: ['{\\dfrac{#1}{#2}}', 2],
477
  
478
  // Conditional macro
479
  abs: ['{\\left|#1\\right|}', 1]
480
};
481

482
// Define custom environments
483
MathJax.config.tex.environments = {
484
  braced: ['\\left\\{', '\\right\\}'],
485
  bracketed: ['\\left[', '\\right]']
486
};
487
```
488

489
### Processing Control
490

491
```javascript
492
// Control which elements to process
493
MathJax.config.tex.processClass = 'tex2jax_process';
494
MathJax.config.tex.ignoreClass = 'tex2jax_ignore';
495

496
// Custom delimiters
497
MathJax.config.tex.inlineMath = [
498
  ['$', '$'],
499
  ['\\(', '\\)'],
500
  ['\\begin{math}', '\\end{math}']
501
];
502

503
MathJax.config.tex.displayMath = [
504
  ['$$', '$$'],
505
  ['\\[', '\\]'],
506
  ['\\begin{displaymath}', '\\end{displaymath}']
507
];
508
```
509

510
## Performance Optimization
511

512
### Input Processor Reset
513

514
Reset input processors to clear caches and state:
515

516
```javascript
517
// Reset TeX processor
518
MathJax.texReset();
519

520
// Reset MathML processor  
521
MathJax.mmlReset();
522

523
// Reset AsciiMath processor
524
MathJax.asciimathReset();
525
```
526

527
### Conversion Options
528

529
```javascript { .api }
530
interface ConversionOptions {
531
  /** Display math (true) vs inline math (false) */
532
  display?: boolean;
533
  /** Em size in pixels */
534
  em?: number;
535
  /** Ex height in pixels */
536
  ex?: number;
537
  /** Container width for line breaking */
538
  containerWidth?: number;
539
  /** Scale factor for output */
540
  scale?: number;
541
  /** Font family for measurements */
542
  family?: string;
543
  /** Input format name */
544
  format?: string;
545
  /** Processing end state */
546
  end?: number;
547
  /** Font family for mtext elements */
548
  mtextFamily?: string;
549
  /** Font family for merror elements */
550
  merrorFamily?: string;
551
  /** Line width for line breaking */
552
  lineWidth?: number;
553
  /** Enable automatic line breaking */
554
  linebreaks?: boolean;
555
}
556
```
557

558
**Optimization Examples:**
559

560
```javascript
561
// Optimize for performance
562
const options = {
563
  em: 16,
564
  ex: 8,
565
  containerWidth: 1280,
566
  scale: 1.0
567
};
568

569
// Batch processing
570
const expressions = ['x^2', 'y^2', 'z^2'];
571
const results = expressions.map(expr => MathJax.tex2svg(expr, options));
572

573
// Async batch processing
574
const asyncResults = await Promise.all(
575
  expressions.map(expr => MathJax.tex2svgPromise(expr, options))
576
);
577
```