0
# Initialization and Configuration
1

2
MathJax provides comprehensive initialization and configuration capabilities for both browser and Node.js environments, with extensive customization options and component loading.
3

4
## Capabilities
5

6
### Initialization
7

8
Initialize MathJax with custom configuration and component loading.
9

10
```javascript { .api }
11
/**
12
 * Initialize MathJax with configuration
13
 * @param config - Configuration object for MathJax
14
 * @returns Promise that resolves to the configured MathJax instance
15
 */
16
function init(config?: Configuration): Promise<MathJax>;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const MathJax = require('mathjax');
23

24
// Basic initialization
25
const mjx = await MathJax.init();
26

27
// Initialize with TeX input and SVG output
28
const mjx = await MathJax.init({
29
  loader: {
30
    load: ['input/tex', 'output/svg']
31
  }
32
});
33

34
// Initialize with complete configuration
35
const mjx = await MathJax.init({
36
  loader: {
37
    load: ['input/tex', '[tex]/ams', 'output/chtml'],
38
    paths: {
39
      mathjax: 'path/to/mathjax'
40
    }
41
  },
42
  tex: {
43
    packages: ['base', 'ams', 'color'],
44
    macros: {
45
      R: '{\\mathbb{R}}',
46
      bold: ['{\\bf #1}', 1]
47
    }
48
  },
49
  chtml: {
50
    fontURL: 'https://cdn.jsdelivr.net/npm/mathjax@4/fonts/woff-v2',
51
    adaptiveCSS: true
52
  }
53
});
54
```
55

56
### Component Loader
57

58
Load and manage MathJax components dynamically.
59

60
```javascript { .api }
61
/**
62
 * Load specified components
63
 * @param components - List of component names to load
64
 * @returns Promise that resolves when all components are loaded
65
 */
66
function load(...components: string[]): Promise<any[]>;
67

68
/**
69
 * Wait for components to be ready
70
 * @param components - List of component names to wait for
71
 * @returns Promise that resolves when components are ready
72
 */
73
function ready(...components: string[]): Promise<any[]>;
74

75
/**
76
 * Mark components as pre-loaded
77
 * @param components - List of component names to mark as loaded
78
 */
79
function preLoaded(...components: string[]): void;
80

81
/**
82
 * Check component version compatibility
83
 * @param component - Component name
84
 * @param version - Required version
85
 * @param name - Component display name
86
 * @returns Whether version is compatible
87
 */
88
function checkVersion(component: string, version: string, name: string): boolean;
89

90
/**
91
 * Get root path for component loading
92
 * @returns Root path string
93
 */
94
function getRoot(): string;
95
```
96

97
**Usage Examples:**
98

99
```javascript
100
// Load additional components
101
await MathJax.loader.load('input/asciimath', '[tex]/color', 'a11y/semantic-enrich');
102

103
// Wait for specific components
104
await MathJax.loader.ready('input/tex', 'output/svg');
105

106
// Mark components as pre-loaded
107
MathJax.loader.preLoaded('startup', 'core');
108

109
// Check version compatibility
110
const isCompatible = MathJax.loader.checkVersion('input/tex', '4.0.0', 'TeX Input');
111

112
// Get component root path
113
const rootPath = MathJax.loader.getRoot();
114
```
115

116
### Core Global Objects
117

118
Access to MathJax's core global objects and namespaces.
119

120
```javascript { .api }
121
/**
122
 * MathJax version string
123
 */
124
const version: string;
125

126
/**
127
 * Internal utilities and components namespace
128
 */
129
const _: {
130
  core: CoreUtilities;
131
  util: UtilityFunctions;
132
  adaptors: AdaptorClasses;
133
  components: ComponentClasses;
134
};
135

136
/**
137
 * Core MathJax engine object
138
 */
139
const mathjax: {
140
  version: string;
141
  handlers: HandlerList;
142
  document: (doc: any, options: any) => MathDocument;
143
};
144
```
145

146
**Usage Examples:**
147

148
```javascript
149
// Access version information
150
console.log('MathJax version:', MathJax.version);
151

152
// Access internal utilities
153
const utilities = MathJax._.util;
154
const coreModules = MathJax._.core;
155

156
// Access core engine
157
const engine = MathJax.mathjax;
158
const document = engine.document(htmlDoc, options);
159
```
160

161
### Startup System
162

163
Control MathJax startup and component initialization.
164

165
```javascript { .api }
166
/**
167
 * Register a constructor for a component
168
 * @param name - Component name
169
 * @param constructor - Constructor function
170
 */
171
function registerConstructor(name: string, constructor: any): void;
172

173
/**
174
 * Set the document handler
175
 * @param name - Handler name
176
 * @param force - Whether to force replacement
177
 */
178
function useHandler(name: string, force?: boolean): void;
179

180
/**
181
 * Set the DOM adaptor
182
 * @param name - Adaptor name  
183
 * @param force - Whether to force replacement
184
 */
185
function useAdaptor(name: string, force?: boolean): void;
186

187
/**
188
 * Add an input processor
189
 * @param name - Input processor name
190
 * @param force - Whether to force replacement
191
 */
192
function useInput(name: string, force?: boolean): void;
193

194
/**
195
 * Set the output processor
196
 * @param name - Output processor name
197
 * @param force - Whether to force replacement
198
 */
199
function useOutput(name: string, force?: boolean): void;
200

201
/**
202
 * Extend the document handler with additional functionality
203
 * @param extension - Extension function
204
 * @param priority - Priority level for execution order
205
 */
206
function extendHandler(extension: Function, priority?: number): void;
207
```
208

209
**Usage Examples:**
210

211
```javascript
212
// Register custom constructor
213
MathJax.startup.registerConstructor('customInput', MyCustomInputJax);
214

215
// Set components
216
MathJax.startup.useHandler('HTMLHandler');
217
MathJax.startup.useAdaptor('liteAdaptor'); 
218
MathJax.startup.useInput('tex');
219
MathJax.startup.useOutput('svg');
220
```
221

222
## Configuration Options
223

224
### Loader Configuration
225

226
```javascript { .api }
227
interface LoaderOptions {
228
  /** Components to load automatically */
229
  load?: string[];
230
  /** Component dependencies */
231
  dependencies?: Record<string, string[]>;
232
  /** Path mappings for component loading */
233
  paths?: Record<string, string>;
234
  /** Source file mappings */
235
  source?: Record<string, string>;
236
  /** Components provided by other components */
237
  provides?: Record<string, string[]>;
238
  /** Ready callback */
239
  ready?: () => void;
240
  /** Failure callback */
241
  failed?: (error: Error) => void;
242
  /** Custom require function */
243
  require?: (file: string) => any;
244
  /** Path filter functions */
245
  pathFilters?: Array<Function | [Function, number]>;
246
  /** Show version warnings */
247
  versionWarnings?: boolean;
248
}
249
```
250

251
### Startup Configuration
252

253
```javascript { .api }
254
interface StartupOptions {
255
  /** Input format names */
256
  input?: string[];
257
  /** Output format name */
258
  output?: string;
259
  /** Document handler name */
260
  handler?: string | null;
261
  /** DOM adaptor name */
262
  adaptor?: string | null;
263
  /** Document or document selector */
264
  document?: string | Document;
265
  /** Elements to process */
266
  elements?: Element[] | null;
267
  /** Auto-typeset on ready */
268
  typeset?: boolean;
269
  /** Ready callback */
270
  ready?: () => void;
271
  /** Page ready callback */
272
  pageReady?: () => void;
273
}
274
```
275

276
### Global Options
277

278
```javascript { .api }
279
interface GlobalOptions {
280
  /** Enable assistive MathML */
281
  enableAssistiveMml?: boolean;
282
  /** Enable interactive explorer */
283
  enableExplorer?: boolean;
284
  /** Compile error handler */
285
  compileError?: (doc: any, math: any, error: Error) => void;
286
  /** Typeset error handler */
287
  typesetError?: (doc: any, math: any, error: Error) => void;
288
  /** Accessibility options */
289
  a11y?: AccessibilityOptions;
290
}
291
```
292

293
## Component Loading
294

295
### Available Components
296

297
**Input Components:**
298
- `input/tex` - TeX/LaTeX input processor
299
- `input/tex-base` - Base TeX functionality
300
- `input/mml` - MathML input processor  
301
- `input/asciimath` - AsciiMath input processor
302

303
**Output Components:**
304
- `output/chtml` - CommonHTML output processor
305
- `output/svg` - SVG output processor
306

307
**TeX Extensions (30+ available):**
308
- `[tex]/ams` - AMS math extensions
309
- `[tex]/color` - Color support
310
- `[tex]/mhchem` - Chemistry notation
311
- `[tex]/physics` - Physics notation
312
- `[tex]/cancel` - Cancel expressions
313
- `[tex]/bbox` - Bounding boxes
314
- And many more...
315

316
**Accessibility Components:**
317
- `a11y/semantic-enrich` - Semantic enhancement
318
- `a11y/speech` - Speech generation
319
- `a11y/explorer` - Interactive exploration
320
- `a11y/assistive-mml` - Assistive MathML
321

322
**UI Components:**
323
- `ui/menu` - Context menu
324
- `ui/lazy` - Lazy loading
325
- `ui/safe` - Safe mode
326

327
### Component Combinations
328

329
Pre-built component combinations for common use cases:
330

331
- `tex-chtml` - TeX input + CommonHTML output
332
- `tex-svg` - TeX input + SVG output
333
- `mml-chtml` - MathML input + CommonHTML output
334
- `mml-svg` - MathML input + SVG output
335
- `tex-mml-chtml` - TeX + MathML inputs + CommonHTML output
336
- `tex-mml-svg` - TeX + MathML inputs + SVG output
337

338
Each available with `-nofont` variants.
339

340
## Environment-Specific Configuration
341

342
### Browser Configuration
343

344
For browser environments, configuration is typically set globally:
345

346
```javascript
347
window.MathJax = {
348
  tex: {
349
    inlineMath: [['$', '$'], ['\\(', '\\)']],
350
    displayMath: [['$$', '$$'], ['\\[', '\\]']]
351
  },
352
  chtml: {
353
    fontURL: 'https://cdn.jsdelivr.net/npm/mathjax@4/fonts/woff-v2'
354
  }
355
};
356
```
357

358
### Node.js Configuration
359

360
For Node.js environments, configuration is passed to `init()`:
361

362
```javascript
363
const config = {
364
  loader: {
365
    require: require,
366
    paths: {
367
      mathjax: 'node_modules/mathjax'
368
    }
369
  },
370
  startup: {
371
    typeset: false  // Don't auto-typeset in Node.js
372
  }
373
};
374

375
const MathJax = await require('mathjax').init(config);
376
```
377

378
## Error Handling
379

380
### Loader Errors
381

382
```javascript
383
MathJax.config.loader.failed = (error) => {
384
  console.error('Component failed to load:', error.message);
385
  // Handle component loading failure
386
};
387
```
388

389
### Initialization Errors
390

391
```javascript
392
try {
393
  const MathJax = await require('mathjax').init(config);
394
} catch (error) {
395
  console.error('MathJax initialization failed:', error.message);
396
  // Handle initialization failure
397
}
398
```
399

400
## Advanced Configuration
401

402
### Custom Path Filters
403

404
```javascript
405
MathJax.config.loader.pathFilters.push([
406
  (data) => {
407
    // Custom path transformation
408
    if (data.name.startsWith('custom/')) {
409
      data.name = 'https://my-cdn.com/' + data.name;
410
    }
411
    return true;
412
  },
413
  15  // Priority
414
]);
415
```
416

417
### Custom Components
418

419
```javascript
420
// Register custom input processor
421
MathJax.startup.registerConstructor('myInput', MyInputProcessor);
422

423
// Use custom component
424
MathJax.startup.useInput('myInput');
425
```