0
# Instance Configuration
1

2
Methods for managing options on individual Converter instances, allowing per-instance customization that overrides global settings.
3

4
## Capabilities
5

6
### setOption
7

8
Sets an option for a specific Converter instance.
9

10
```javascript { .api }
11
/**
12
 * Set option for this converter instance
13
 * @param key - Option name
14
 * @param value - Option value
15
 * @returns Converter instance for chaining
16
 */
17
converter.setOption(key: string, value: any): showdown.Converter
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const converter = new showdown.Converter();
24

25
// Set instance-specific options
26
converter.setOption('tables', true);
27
converter.setOption('strikethrough', true);
28

29
// Chaining is supported
30
converter
31
  .setOption('emoji', true)
32
  .setOption('ghMentions', true)
33
  .setOption('tasklists', true);
34

35
// This converter now has these options enabled
36
const html = converter.makeHtml('| Column 1 | Column 2 |\n|----------|----------|');
37
```
38

39
### getOption
40

41
Gets the value of an option for a specific Converter instance.
42

43
```javascript { .api }
44
/**
45
 * Get option value for this converter instance
46
 * @param key - Option name
47
 * @returns Option value
48
 */
49
converter.getOption(key: string): any
50
```
51

52
**Usage Examples:**
53

54
```javascript
55
const converter = new showdown.Converter({ tables: true });
56

57
// Get instance option
58
const tablesEnabled = converter.getOption('tables');
59
console.log(tablesEnabled); // true
60

61
// Check if option is set
62
if (converter.getOption('strikethrough')) {
63
  console.log('Strikethrough is enabled for this converter');
64
}
65

66
// Compare with global option
67
const globalTables = showdown.getOption('tables');
68
const instanceTables = converter.getOption('tables');
69
console.log('Global vs instance:', globalTables, instanceTables);
70
```
71

72
### getOptions
73

74
Gets all options for a specific Converter instance.
75

76
```javascript { .api }
77
/**
78
 * Get all options for this converter instance
79
 * @returns Object containing all converter options
80
 */
81
converter.getOptions(): ConverterOptions
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
const converter = new showdown.Converter({
88
  tables: true,
89
  strikethrough: true,
90
  ghCodeBlocks: true
91
});
92

93
// Get all instance options
94
const options = converter.getOptions();
95
console.log(options);
96

97
// Check multiple options
98
const opts = converter.getOptions();
99
if (opts.tables && opts.strikethrough) {
100
  console.log('This converter supports GitHub-style tables and strikethrough');
101
}
102

103
// Create another converter with same options
104
const converter2 = new showdown.Converter(converter.getOptions());
105
```
106

107
### setFlavor
108

109
Sets the flavor for a specific Converter instance.
110

111
```javascript { .api }
112
/**
113
 * Set flavor for this converter instance
114
 * @param name - Flavor name
115
 * @returns Converter instance for chaining
116
 */
117
converter.setFlavor(name: string): showdown.Converter
118
```
119

120
**Usage Examples:**
121

122
```javascript
123
const converter = new showdown.Converter();
124

125
// Set GitHub flavor for this instance
126
converter.setFlavor('github');
127

128
// Chaining with other operations
129
converter
130
  .setFlavor('github')
131
  .setOption('emoji', false); // Override flavor setting
132

133
// Multiple converters with different flavors
134
const githubConverter = new showdown.Converter().setFlavor('github');
135
const originalConverter = new showdown.Converter().setFlavor('original');
136
const ghostConverter = new showdown.Converter().setFlavor('ghost');
137
```
138

139
### getFlavor
140

141
Gets the flavor for a specific Converter instance.
142

143
```javascript { .api }
144
/**
145
 * Get flavor for this converter instance
146
 * @returns Current flavor name for this instance
147
 */
148
converter.getFlavor(): string
149
```
150

151
**Usage Examples:**
152

153
```javascript
154
const converter = new showdown.Converter();
155
converter.setFlavor('github');
156

157
// Get instance flavor
158
const flavor = converter.getFlavor();
159
console.log('Converter flavor:', flavor); // 'github'
160

161
// Conditional processing based on flavor
162
if (converter.getFlavor() === 'github') {
163
  console.log('Using GitHub-compatible converter');
164
} else if (converter.getFlavor() === 'original') {
165
  console.log('Using original Markdown converter');
166
}
167
```
168

169
## Instance vs Global Configuration
170

171
Instance options override global options:
172

173
```javascript
174
// Set global option
175
showdown.setOption('tables', false);
176

177
// Create converter with global settings
178
const converter1 = new showdown.Converter();
179
console.log(converter1.getOption('tables')); // false
180

181
// Override for specific instance
182
const converter2 = new showdown.Converter({ tables: true });
183
console.log(converter2.getOption('tables')); // true
184

185
// Global setting unchanged
186
console.log(showdown.getOption('tables')); // false
187
```
188

189
## Configuration Inheritance
190

191
Options are inherited from global settings at creation time:
192

193
```javascript
194
// Set global options
195
showdown.setOption('strikethrough', true);
196
showdown.setOption('tables', true);
197

198
// Create converter (inherits global options)
199
const converter = new showdown.Converter();
200
console.log(converter.getOption('strikethrough')); // true
201
console.log(converter.getOption('tables')); // true
202

203
// Change global options
204
showdown.setOption('strikethrough', false);
205

206
// Existing converter retains its options
207
console.log(converter.getOption('strikethrough')); // true (unchanged)
208

209
// New converter inherits current global options
210
const newConverter = new showdown.Converter();
211
console.log(newConverter.getOption('strikethrough')); // false
212
```
213

214
## Constructor Options
215

216
Options can be set during construction:
217

218
```javascript
219
// Single option
220
const converter = new showdown.Converter({ tables: true });
221

222
// Multiple options
223
const converter2 = new showdown.Converter({
224
  tables: true,
225
  strikethrough: true,
226
  ghCodeBlocks: true,
227
  tasklists: true,
228
  emoji: true
229
});
230

231
// Combining with extensions
232
const converter3 = new showdown.Converter({
233
  tables: true,
234
  extensions: ['highlight', 'mentions']
235
});
236
```
237

238
## Dynamic Configuration
239

240
Options can be changed after creation:
241

242
```javascript
243
const converter = new showdown.Converter();
244

245
// Initial conversion
246
let html = converter.makeHtml('~~strikethrough~~');
247
console.log(html); // <p>~~strikethrough~~</p>
248

249
// Enable strikethrough
250
converter.setOption('strikethrough', true);
251

252
// Same text now processes differently
253
html = converter.makeHtml('~~strikethrough~~');
254
console.log(html); // <p><del>strikethrough</del></p>
255
```
256

257
## Option Validation
258

259
Invalid options are generally ignored:
260

261
```javascript
262
const converter = new showdown.Converter();
263

264
// Invalid option name (ignored silently)
265
converter.setOption('nonExistentOption', true);
266

267
// Invalid option value (type coercion may occur)
268
converter.setOption('tables', 'yes'); // Treated as truthy
269

270
// Getting invalid option returns undefined
271
console.log(converter.getOption('nonExistentOption')); // undefined
272
```
273

274
## Performance Considerations
275

276
```javascript
277
// Efficient: Set options once
278
const converter = new showdown.Converter({
279
  tables: true,
280
  strikethrough: true,
281
  ghCodeBlocks: true
282
});
283

284
// Use for multiple conversions
285
const html1 = converter.makeHtml(markdown1);
286
const html2 = converter.makeHtml(markdown2);
287

288
// Less efficient: Changing options frequently
289
converter.setOption('tables', false);
290
const html3 = converter.makeHtml(markdown3);
291
converter.setOption('tables', true);
292
const html4 = converter.makeHtml(markdown4);
293
```
294

295
## Instance Extension Methods
296

297
### addExtension
298

299
Adds an extension to a specific Converter instance.
300

301
```javascript { .api }
302
/**
303
 * Add extension to this converter instance
304
 * @param extension - Extension object or array of extensions
305
 * @param name - Optional extension name
306
 * @returns Converter instance for chaining
307
 */
308
converter.addExtension(extension: Extension, name?: string): showdown.Converter
309
```
310

311
**Usage Examples:**
312

313
```javascript
314
const converter = new showdown.Converter();
315

316
// Add extension object directly
317
const highlightExt = {
318
  type: 'output',
319
  regex: /<pre><code>/g,
320
  replace: '<pre class="highlighted"><code>'
321
};
322
converter.addExtension(highlightExt, 'highlight');
323

324
// Add registered extension by name
325
converter.addExtension('my-registered-extension');
326

327
// Chaining
328
converter
329
  .addExtension(ext1, 'ext1')
330
  .addExtension(ext2, 'ext2');
331
```
332

333
### useExtension
334

335
Uses a globally registered extension in this converter instance.
336

337
```javascript { .api }
338
/**
339
 * Use a globally registered extension
340
 * @param extensionName - Name of registered extension
341
 * @returns Converter instance for chaining
342
 */
343
converter.useExtension(extensionName: string): showdown.Converter
344
```
345

346
**Usage Examples:**
347

348
```javascript
349
// Register extension globally first
350
showdown.extension('highlight', highlightExtension);
351

352
// Use in specific converter instance
353
const converter = new showdown.Converter();
354
converter.useExtension('highlight');
355

356
// Multiple extensions
357
converter
358
  .useExtension('highlight')
359
  .useExtension('mentions')
360
  .useExtension('alerts');
361
```
362

363
### removeExtension
364

365
Removes an extension from this converter instance.
366

367
```javascript { .api }
368
/**
369
 * Remove extension from this converter instance
370
 * @param extension - Extension object, name, or array
371
 * @returns Converter instance for chaining
372
 */
373
converter.removeExtension(extension: Extension | string): showdown.Converter
374
```
375

376
**Usage Examples:**
377

378
```javascript
379
const converter = new showdown.Converter();
380
converter.addExtension(someExtension, 'temp');
381

382
// Remove by name
383
converter.removeExtension('temp');
384

385
// Remove by extension object
386
converter.removeExtension(someExtension);
387
```
388

389
### getAllExtensions
390

391
Gets all extensions for this converter instance.
392

393
```javascript { .api }
394
/**
395
 * Get all extensions for this converter instance
396
 * @returns Array of extensions
397
 */
398
converter.getAllExtensions(): Extension[]
399
```
400

401
**Usage Examples:**
402

403
```javascript
404
const converter = new showdown.Converter();
405
converter.addExtension(ext1, 'ext1');
406
converter.addExtension(ext2, 'ext2');
407

408
// Get all extensions
409
const extensions = converter.getAllExtensions();
410
console.log('Converter has', extensions.length, 'extensions');
411

412
// Check if specific extension is loaded
413
const hasHighlight = converter.getAllExtensions().some(ext => ext.name === 'highlight');
414
```
415

416
## Instance Metadata Methods
417

418
### getMetadata
419

420
Gets document metadata parsed during conversion.
421

422
```javascript { .api }
423
/**
424
 * Get document metadata
425
 * @param raw - If true, returns raw metadata string
426
 * @returns Parsed metadata object or raw string
427
 */
428
converter.getMetadata(raw?: boolean): any
429
```
430

431
**Usage Examples:**
432

433
```javascript
434
const converter = new showdown.Converter({ metadata: true });
435

436
const markdown = `---
437
title: My Document
438
author: John Doe
439
date: 2023-01-01
440
---
441

442
# Content`;
443

444
const html = converter.makeHtml(markdown);
445

446
// Get parsed metadata
447
const metadata = converter.getMetadata();
448
console.log(metadata); // { title: 'My Document', author: 'John Doe', date: '2023-01-01' }
449

450
// Get raw metadata
451
const rawMetadata = converter.getMetadata(true);
452
console.log(rawMetadata); // "title: My Document\nauthor: John Doe\ndate: 2023-01-01"
453
```
454

455
### getMetadataFormat
456

457
Gets the format of the metadata (e.g., 'yaml', 'json').
458

459
```javascript { .api }
460
/**
461
 * Get metadata format
462
 * @returns Metadata format string
463
 */
464
converter.getMetadataFormat(): string
465
```
466

467
**Usage Examples:**
468

469
```javascript
470
const converter = new showdown.Converter({ metadata: true });
471

472
// Convert document with YAML frontmatter
473
const html = converter.makeHtml(markdownWithYamlFrontmatter);
474

475
// Check metadata format
476
const format = converter.getMetadataFormat();
477
console.log('Metadata format:', format); // 'yaml'
478
```