0
# marked-terminal
1

2
marked-terminal is a custom renderer for the marked markdown parser that enables rendering markdown content directly to the terminal with rich formatting and styling. It provides comprehensive terminal output capabilities including syntax highlighting, customizable color schemes, table rendering, emoji support, and configurable text reflow.
3

4
## Package Information
5

6
- **Package Name**: marked-terminal  
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install marked marked-terminal` (marked is a required peer dependency)
10

11
## Core Imports
12

13
marked-terminal provides dual package exports supporting both ESM and CommonJS:
14

15
**ESM (ES modules):**
16
```javascript
17
import { marked } from 'marked';
18
import { markedTerminal } from 'marked-terminal';
19
// For direct Renderer class usage:
20
import TerminalRenderer from 'marked-terminal';
21
```
22

23
**CommonJS:**
24
```javascript
25
const { marked } = require('marked');
26
const { markedTerminal } = require('marked-terminal');
27
// For legacy Renderer class usage:
28
const TerminalRenderer = require('marked-terminal').default;
29
```
30

31
## Basic Usage
32

33
```javascript
34
import { marked } from 'marked';
35
import { markedTerminal } from 'marked-terminal';
36

37
// Modern approach with marked.use()
38
marked.use(markedTerminal());
39

40
// Render markdown to terminal
41
const output = marked.parse('# Hello \nThis is **markdown** printed in the `terminal`');
42
console.log(output);
43
```
44

45
Legacy usage with Renderer class:
46

47
```javascript
48
import TerminalRenderer from 'marked-terminal';
49
import { marked } from 'marked';
50

51
marked.setOptions({
52
  renderer: new TerminalRenderer()
53
});
54

55
console.log(marked.parse('# Hello \nThis is **markdown** printed in the `terminal`'));
56
```
57

58
## Architecture
59

60
marked-terminal provides two main interfaces:
61

62
- **Modern Extension**: `markedTerminal()` function creates a marked extension for use with `marked.use()`
63
- **Legacy Renderer**: `Renderer` class that can be used directly with `marked.setOptions()`
64
- **Rendering Engine**: Comprehensive set of renderer methods for all markdown elements
65
- **Styling System**: Chalk-based color and formatting with extensive customization options
66
- **Plugin Integration**: Built-in support for syntax highlighting (cli-highlight), tables (cli-table3), and emojis
67

68
## Capabilities
69

70
### Core Rendering
71

72
Main rendering functionality that converts markdown elements to styled terminal output.
73

74
```javascript { .api }
75
/**
76
 * Creates a marked extension for rendering markdown to terminal
77
 * @param options - Renderer configuration options
78
 * @param highlightOptions - Syntax highlighting options passed to cli-highlight
79
 * @returns Marked extension object for use with marked.use()
80
 */
81
function markedTerminal(options?: RendererOptions, highlightOptions?: HighlightOptions): MarkedExtension;
82

83
/**
84
 * Terminal renderer class for marked markdown parser
85
 * @param options - Renderer configuration options  
86
 * @param highlightOptions - Syntax highlighting options passed to cli-highlight
87
 */
88
class Renderer {
89
  constructor(options?: RendererOptions, highlightOptions?: HighlightOptions);
90
}
91

92
interface MarkedExtension {
93
  renderer: Record<string, Function>;
94
  useNewRenderer: boolean;
95
}
96
```
97

98
[Configuration & Options](./configuration.md)
99

100
### Text and Inline Elements
101

102
Rendering methods for text content and inline markdown elements.
103

104
```javascript { .api }
105
// Text rendering
106
text(text: string | {text: string}): string;
107
strong(text: string | {tokens: any[]}): string;
108
em(text: string | {tokens: any[]}): string;
109
codespan(text: string | {text: string}): string;
110
del(text: string | {tokens: any[]}): string;
111
br(): string;
112

113
// Link and image rendering  
114
link(href: string | {href: string, title?: string, tokens?: any[]}, title?: string, text?: string): string;
115
image(href: string | {href: string, title?: string, text?: string}, title?: string, text?: string): string;
116
```
117

118
### Block Elements
119

120
Rendering methods for block-level markdown elements.
121

122
```javascript { .api }
123
// Headings and paragraphs
124
heading(text: string | {depth: number, tokens: any[]}, level?: number): string;
125
paragraph(text: string | {tokens: any[]}): string;
126
hr(): string;
127

128
// Code blocks
129
code(code: string | {text: string, lang?: string, escaped?: boolean}, lang?: string, escaped?: boolean): string;
130

131
// Blockquotes
132
blockquote(quote: string | {tokens: any[]}): string;
133

134
// HTML
135
html(html: string | {text: string}): string;
136
```
137

138
### Lists and Tables
139

140
Rendering methods for structured content like lists and tables.
141

142
```javascript { .api }
143
// List rendering
144
list(body: string | {ordered: boolean, start?: number, loose?: boolean, items: any[]}, ordered?: boolean): string;
145
listitem(text: string | {task?: boolean, checked?: boolean, loose?: boolean, tokens: any[]}): string;
146
checkbox(checked: boolean | {checked: boolean}): string;
147

148
// Table rendering
149
table(header: string | {header: any[], rows: any[][]}, body?: string): string;
150
tablerow(content: string | {text: string}): string;
151
tablecell(content: string | {tokens: any[]}): string;
152
```
153

154
### Utility Methods
155

156
Helper methods for text processing and measurement available on Renderer instances.
157

158
```javascript { .api }
159
/**
160
 * Calculate text length excluding ANSI escape codes (static method on Renderer class)
161
 * @param str - Input string that may contain ANSI codes
162
 * @returns Length of visible text characters
163
 */
164
Renderer.prototype.textLength(str: string): number;
165

166
/**
167
 * Returns empty string for spacing in renderer
168
 * @returns Empty string
169
 */
170
space(): string;
171
```
172

173
## Types
174

175
```javascript { .api }
176
interface RendererOptions {
177
  // Color and styling functions
178
  code?: ChalkFunction;
179
  blockquote?: ChalkFunction;
180
  html?: ChalkFunction;
181
  heading?: ChalkFunction;
182
  firstHeading?: ChalkFunction;
183
  hr?: ChalkFunction;
184
  listitem?: ChalkFunction;
185
  table?: ChalkFunction;
186
  paragraph?: ChalkFunction;
187
  strong?: ChalkFunction;
188
  em?: ChalkFunction;
189
  codespan?: ChalkFunction;
190
  del?: ChalkFunction;
191
  link?: ChalkFunction;
192
  href?: ChalkFunction;
193
  text?: (text: string) => string;
194

195
  // List formatting function
196
  list?: (body: string, ordered: boolean, indent: string) => string;
197

198
  // Text processing options
199
  width?: number;
200
  reflowText?: boolean;
201
  showSectionPrefix?: boolean;
202
  unescape?: boolean;
203
  emoji?: boolean;
204
  tab?: number | string;
205

206
  // Table configuration
207
  tableOptions?: Record<string, any>;
208

209
  // Custom image handler
210
  image?: (href: string, title?: string, text?: string) => string;
211
}
212

213
interface HighlightOptions {
214
  language?: string;
215
  theme?: string;
216
  [key: string]: any;
217
}
218

219
type ChalkFunction = (text: string) => string;
220
```