0
# Configuration & Options
1

2
Comprehensive configuration options for customizing marked-terminal's output styling, formatting, and behavior.
3

4
## Capabilities
5

6
### Basic Configuration
7

8
Simple configuration for common use cases.
9

10
```javascript { .api }
11
/**
12
 * Creates a marked extension for rendering markdown to terminal with custom styling
13
 * @param options - Renderer configuration options for colors, formatting, and behavior
14
 * @param highlightOptions - Syntax highlighting options passed to cli-highlight
15
 * @returns Marked extension object for use with marked.use()
16
 */
17
function markedTerminal(options?: RendererOptions, highlightOptions?: HighlightOptions): MarkedExtension;
18

19
/**
20
 * Creates a terminal renderer instance with custom options (legacy usage)
21
 * @param options - Renderer configuration options for colors, formatting, and behavior
22
 * @param highlightOptions - Syntax highlighting options passed to cli-highlight
23
 */
24
class Renderer {
25
  constructor(options?: RendererOptions, highlightOptions?: HighlightOptions);
26
}
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import { marked } from 'marked';
33
import { markedTerminal } from 'marked-terminal';
34
import chalk from 'chalk';
35

36
// Custom styling
37
marked.use(markedTerminal({
38
  code: chalk.yellow,
39
  heading: chalk.green.bold,
40
  strong: chalk.bold,
41
  em: chalk.italic,
42
  codespan: chalk.yellow,
43
  link: chalk.blue,
44
  href: chalk.blue.underline
45
}));
46

47
// With syntax highlighting options
48
marked.use(markedTerminal({
49
  code: chalk.yellow
50
}, {
51
  language: 'javascript',
52
  theme: 'github'
53
}));
54
```
55

56
### Color and Styling Options
57

58
Customization of colors and text styles for different markdown elements.
59

60
```javascript { .api }
61
interface StyleOptions {
62
  /** Code block styling function */
63
  code?: ChalkFunction;
64
  /** Blockquote styling function */
65
  blockquote?: ChalkFunction;
66
  /** HTML element styling function */
67
  html?: ChalkFunction;
68
  /** General heading (h2-h6) styling function */
69
  heading?: ChalkFunction;
70
  /** First heading (h1) styling function */
71
  firstHeading?: ChalkFunction;
72
  /** Horizontal rule styling function */
73
  hr?: ChalkFunction;
74
  /** List item styling function */
75
  listitem?: ChalkFunction;
76
  /** Table styling function */
77
  table?: ChalkFunction;
78
  /** Paragraph styling function */
79
  paragraph?: ChalkFunction;
80
  /** Bold text styling function */
81
  strong?: ChalkFunction;
82
  /** Italic text styling function */
83
  em?: ChalkFunction;
84
  /** Inline code styling function */
85
  codespan?: ChalkFunction;
86
  /** Strikethrough text styling function */
87
  del?: ChalkFunction;
88
  /** Link text styling function */
89
  link?: ChalkFunction;
90
  /** Link URL styling function */
91
  href?: ChalkFunction;
92
  /** Plain text processing function */
93
  text?: (text: string) => string;
94
}
95

96
type ChalkFunction = (text: string) => string;
97
```
98

99
**Default Style Values:**
100

101
```javascript
102
const defaultStyles = {
103
  code: chalk.yellow,
104
  blockquote: chalk.gray.italic,
105
  html: chalk.gray,
106
  heading: chalk.green.bold,
107
  firstHeading: chalk.magenta.underline.bold,
108
  hr: chalk.reset,
109
  listitem: chalk.reset,
110
  table: chalk.reset,
111
  paragraph: chalk.reset,
112
  strong: chalk.bold,
113
  em: chalk.italic,
114
  codespan: chalk.yellow,
115
  del: chalk.dim.gray.strikethrough,
116
  link: chalk.blue,
117
  href: chalk.blue.underline,
118
  text: (str) => str
119
};
120
```
121

122
### Text Processing Options
123

124
Options that control text flow, formatting, and processing behavior.
125

126
```javascript { .api }
127
interface TextProcessingOptions {
128
  /** Terminal width for text reflow (default: 80) */
129
  width?: number;
130
  /** Enable text reflow to fit terminal width (default: false) */
131
  reflowText?: boolean;
132
  /** Show section prefix (### ) for headings (default: true) */
133
  showSectionPrefix?: boolean;
134
  /** Unescape HTML entities (& -> &) (default: true) */
135
  unescape?: boolean;
136
  /** Convert emoji codes (:smile:) to emojis (default: true) */
137
  emoji?: boolean;
138
  /** Tab size as number of spaces or tab character (default: 4) */
139
  tab?: number | string;
140
}
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
// Text reflow configuration
147
marked.use(markedTerminal({
148
  width: 120,
149
  reflowText: true,
150
  showSectionPrefix: false,
151
  tab: 2
152
}));
153

154
// Disable emoji and HTML unescaping
155
marked.use(markedTerminal({
156
  emoji: false,
157
  unescape: false
158
}));
159
```
160

161
### List Formatting
162

163
Custom list formatting function for controlling list appearance.
164

165
```javascript { .api }
166
interface ListOptions {
167
  /** Custom list formatting function */
168
  list?: (body: string, ordered: boolean, indent: string) => string;
169
}
170
```
171

172
**Usage Example:**
173

174
```javascript
175
marked.use(markedTerminal({
176
  list: function(body, ordered, indent) {
177
    // Custom list formatting logic
178
    const marker = ordered ? '1.' : '•';
179
    return body.split('\n')
180
      .map(line => line ? `${indent}${marker} ${line}` : line)
181
      .join('\n');
182
  }
183
}));
184
```
185

186
### Table Configuration
187

188
Options for customizing table appearance using cli-table3.
189

190
```javascript { .api }
191
interface TableConfiguration {
192
  /** Options passed directly to cli-table3 */
193
  tableOptions?: {
194
    /** Table border characters */
195
    chars?: {
196
      top?: string;
197
      'top-mid'?: string;
198
      'top-left'?: string;
199
      'top-right'?: string;
200
      bottom?: string;
201
      'bottom-mid'?: string;
202
      'bottom-left'?: string;
203
      'bottom-right'?: string;
204
      left?: string;
205
      'left-mid'?: string;
206
      mid?: string;
207
      'mid-mid'?: string;
208
      right?: string;
209
      'right-mid'?: string;
210
      middle?: string;
211
    };
212
    /** Table styling */
213
    style?: {
214
      'padding-left'?: number;
215
      'padding-right'?: number;
216
      head?: string[];
217
      border?: string[];
218
    };
219
    /** Column widths */
220
    colWidths?: number[];
221
    [key: string]: any;
222
  };
223
}
224
```
225

226
**Usage Example:**
227

228
```javascript
229
marked.use(markedTerminal({
230
  tableOptions: {
231
    chars: { 
232
      'top': '═', 
233
      'top-mid': '╤', 
234
      'top-left': '╔', 
235
      'top-right': '╗',
236
      'bottom': '═', 
237
      'bottom-mid': '╧', 
238
      'bottom-left': '╚', 
239
      'bottom-right': '╝',
240
      'left': '║', 
241
      'left-mid': '╟', 
242
      'mid': '─', 
243
      'mid-mid': '┼',
244
      'right': '║', 
245
      'right-mid': '╢', 
246
      'middle': '│'
247
    },
248
    style: { 
249
      'padding-left': 1, 
250
      'padding-right': 1,
251
      head: ['cyan'],
252
      border: ['grey']
253
    }
254
  }
255
}));
256
```
257

258
### Image Handling
259

260
Custom image rendering function for controlling how images are displayed.
261

262
```javascript { .api }
263
interface ImageOptions {
264
  /** Custom image rendering function */
265
  image?: (href: string, title?: string, text?: string) => string;
266
}
267
```
268

269
**Usage Example:**
270

271
```javascript
272
marked.use(markedTerminal({
273
  image: function(href, title, text) {
274
    let output = `![${text}]`;
275
    if (title) output += ` – ${title}`;
276
    output += `(${href})`;
277
    return output + '\n';
278
  }
279
}));
280
```
281

282
### Syntax Highlighting
283

284
Configuration options for code syntax highlighting using cli-highlight.
285

286
```javascript { .api }
287
interface HighlightOptions {
288
  /** Default language for code blocks without language specification */
289
  language?: string;
290
  /** Color theme for syntax highlighting */
291
  theme?: string;
292
  /** Ignore illegal syntax and continue highlighting */
293
  ignoreIllegals?: boolean;
294
  /** Language detection options */
295
  languageDetection?: boolean;
296
  /** Additional cli-highlight options */
297
  [key: string]: any;
298
}
299
```
300

301
**Usage Example:**
302

303
```javascript
304
// Syntax highlighting configuration
305
marked.use(markedTerminal({
306
  code: chalk.reset // Let cli-highlight handle colors
307
}, {
308
  theme: 'github',
309
  language: 'javascript',
310
  ignoreIllegals: true
311
}));
312
```
313

314
### Complete Configuration Example
315

316
```javascript
317
import { marked } from 'marked';
318
import { markedTerminal } from 'marked-terminal';
319
import chalk from 'chalk';
320

321
marked.use(markedTerminal({
322
  // Custom colors
323
  code: chalk.yellow,
324
  blockquote: chalk.gray.italic,
325
  heading: chalk.green.bold,
326
  firstHeading: chalk.magenta.underline.bold,
327
  strong: chalk.bold,
328
  em: chalk.italic,
329
  codespan: chalk.yellow,
330
  del: chalk.strikethrough,
331
  link: chalk.blue,
332
  href: chalk.blue.underline,
333
  
334
  // Text processing
335
  width: 100,
336
  reflowText: true,
337
  showSectionPrefix: true,
338
  unescape: true,
339
  emoji: true,
340
  tab: 2,
341
  
342
  // Table styling
343
  tableOptions: {
344
    style: { 
345
      head: ['cyan', 'bold'],
346
      border: ['grey'] 
347
    }
348
  },
349
  
350
  // Custom image handler
351
  image: (href, title, text) => {
352
    return chalk.dim(`[Image: ${text || 'image'}]`);
353
  }
354
}, {
355
  // Syntax highlighting
356
  theme: 'github',
357
  language: 'javascript'
358
}));
359

360
const markdown = `
361
# Example Document
362

363
This is a **bold** statement with *italic* text and \`inline code\`.
364

365
\`\`\`javascript
366
function hello() {
367
  console.log("Hello, world!");
368
}
369
\`\`\`
370

371
| Name | Age | City |
372
|------|-----|------|
373
| Alice | 25 | NYC |
374
| Bob | 30 | LA |
375
`;
376

377
console.log(marked.parse(markdown));
378
```