0
# Core Parser
1

2
The Remarkable class provides the main parsing functionality for converting markdown to HTML with configurable presets and options.
3

4
## Capabilities
5

6
### Remarkable Constructor
7

8
Creates a new Remarkable parser instance with optional preset and configuration.
9

10
```javascript { .api }
11
/**
12
 * Create a new Remarkable parser instance
13
 * @param preset - Preset name: 'default', 'full', or 'commonmark'
14
 * @param options - Parser configuration options
15
 */
16
class Remarkable {
17
  constructor(preset?: string, options?: RemarkableOptions);
18
}
19

20
interface RemarkableOptions {
21
  /** Enable HTML tags in source (default: false) */
22
  html?: boolean;
23
  /** Use '/' to close single tags like <br /> (default: false) */
24
  xhtmlOut?: boolean;
25
  /** Convert '\n' in paragraphs into <br> (default: false) */
26
  breaks?: boolean;
27
  /** CSS language prefix for fenced blocks (default: 'language-') */
28
  langPrefix?: string;
29
  /** Target attribute for links (default: '') */
30
  linkTarget?: string;
31
  /** Enable typographic replacements (default: false) */
32
  typographer?: boolean;
33
  /** Quote replacement pairs when typographer enabled (default: '""''') */
34
  quotes?: string;
35
  /** Highlighter function for code blocks */
36
  highlight?: (str: string, lang: string) => string;
37
  /** Internal protection, recursion limit (default: 20) */
38
  maxNesting?: number;
39
}
40
```
41

42
**Usage Examples:**
43

44
```javascript
45
import { Remarkable } from "remarkable";
46

47
// Default configuration
48
const md = new Remarkable();
49

50
// With preset
51
const mdFull = new Remarkable('full');
52

53
// With preset and options
54
const mdCustom = new Remarkable('commonmark', {
55
  html: true,
56
  typographer: true,
57
  breaks: true,
58
  linkTarget: '_blank'
59
});
60
```
61

62
### Render Method
63

64
Main method to convert markdown to HTML.
65

66
```javascript { .api }
67
/**
68
 * Convert markdown string to HTML
69
 * @param markdown - Markdown source string
70
 * @param env - Environment object for storing references and metadata
71
 * @returns HTML string
72
 */
73
render(markdown: string, env?: object): string;
74
```
75

76
**Usage Examples:**
77

78
```javascript
79
const md = new Remarkable();
80

81
// Basic rendering
82
const html = md.render('# Hello\n\nThis is **bold**.');
83
// Output: '<h1>Hello</h1>\n<p>This is <strong>bold</strong>.</p>\n'
84

85
// With environment for references
86
const env = {};
87
const htmlWithRefs = md.render(`
88
# Title
89

90
[link][ref]
91

92
[ref]: https://example.com "Title"
93
`, env);
94

95
console.log(env.references); // Contains reference definitions
96
```
97

98
### Parse Method
99

100
Parse markdown and return tokens array without rendering to HTML.
101

102
```javascript { .api }
103
/**
104
 * Parse markdown string and return tokens array
105
 * @param markdown - Markdown source string
106
 * @param env - Environment object for storing references and metadata
107
 * @returns Array of tokens representing the parsed structure
108
 */
109
parse(markdown: string, env?: object): Token[];
110
```
111

112
**Usage Examples:**
113

114
```javascript
115
const md = new Remarkable();
116

117
const tokens = md.parse('# Hello\n\nThis is **bold**.');
118
// Returns array of Token objects representing the structure
119
```
120

121
### Inline Rendering Methods
122

123
Methods for parsing and rendering inline markdown without paragraph wrapping.
124

125
```javascript { .api }
126
/**
127
 * Render inline markdown without paragraph wrapping
128
 * @param markdown - Inline markdown string
129
 * @param env - Environment object
130
 * @returns HTML string without block-level wrapping
131
 */
132
renderInline(markdown: string, env?: object): string;
133

134
/**
135
 * Parse inline markdown and return tokens
136
 * @param markdown - Inline markdown string
137
 * @param env - Environment object
138
 * @returns Array of inline tokens
139
 */
140
parseInline(markdown: string, env?: object): Token[];
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
const md = new Remarkable();
147

148
// Inline rendering - no <p> tags
149
const inline = md.renderInline('This is **bold** and *italic*');
150
// Output: 'This is <strong>bold</strong> and <em>italic</em>'
151

152
// Parse inline tokens
153
const inlineTokens = md.parseInline('**bold** text');
154
```
155

156
### Configuration Methods
157

158
Methods for setting options and applying configurations after instantiation.
159

160
```javascript { .api }
161
/**
162
 * Set parser options
163
 * @param options - Options to merge with current configuration
164
 */
165
set(options: RemarkableOptions): void;
166

167
/**
168
 * Apply preset configuration
169
 * @param presets - Preset configuration object
170
 */
171
configure(presets: PresetConfig): void;
172

173
interface PresetConfig {
174
  options?: RemarkableOptions;
175
  components?: {
176
    core?: { rules: string[] };
177
    block?: { rules: string[] };
178
    inline?: { rules: string[] };
179
  };
180
}
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
const md = new Remarkable();
187

188
// Update options
189
md.set({
190
  html: true,
191
  typographer: true
192
});
193

194
// Apply custom preset
195
md.configure({
196
  options: { breaks: true },
197
  components: {
198
    block: { rules: ['paragraph', 'heading', 'list'] },
199
    inline: { rules: ['text', 'emphasis'] }
200
  }
201
});
202
```
203

204
### Plugin System
205

206
Method for using plugins to extend functionality.
207

208
```javascript { .api }
209
/**
210
 * Use a plugin to extend functionality
211
 * @param plugin - Plugin function that modifies the parser
212
 * @param options - Options to pass to the plugin
213
 * @returns The Remarkable instance for chaining
214
 */
215
use(plugin: PluginFunction, options?: object): Remarkable;
216

217
type PluginFunction = (md: Remarkable, options?: object) => void;
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
import { Remarkable } from "remarkable";
224
import { linkify } from "remarkable/linkify";
225

226
const md = new Remarkable()
227
  .use(linkify)
228
  .use(customPlugin, { option: 'value' });
229

230
function customPlugin(md, options) {
231
  // Add custom rules or modify parser
232
  md.renderer.rules.custom_rule = function(tokens, idx) {
233
    return '<div class="custom">Content</div>';
234
  };
235
}
236
```
237

238
### Parser Components
239

240
Access to internal parser components for advanced customization.
241

242
```javascript { .api }
243
interface Remarkable {
244
  /** Core parser for processing phases */
245
  core: ParserCore;
246
  /** Block-level parser */
247
  block: ParserBlock;
248
  /** Inline parser */
249
  inline: ParserInline;
250
  /** HTML renderer */
251
  renderer: Renderer;
252
  /** Rule manager */
253
  ruler: Ruler;
254
  /** Current options */
255
  options: RemarkableOptions;
256
}
257

258
interface ParserCore {
259
  ruler: Ruler;
260
  process(state: StateCore): void;
261
}
262

263
interface ParserBlock {
264
  ruler: Ruler;
265
  tokenize(state: StateBlock, startLine: number, endLine: number): void;
266
  parse(str: string, options: RemarkableOptions, env: object, outTokens: Token[]): void;
267
}
268

269
interface ParserInline {
270
  ruler: Ruler;
271
  validateLink: (url: string) => boolean;
272
  skipToken(state: StateInline): void;
273
  tokenize(state: StateInline): void;
274
  parse(str: string, options: RemarkableOptions, env: object, outTokens: Token[]): void;
275
}
276

277
// State classes used in rule development
278
class StateCore {
279
  constructor(instance: Remarkable, str: string, env: object);
280
  src: string;
281
  env: object;
282
  options: RemarkableOptions;
283
  tokens: Token[];
284
  inlineMode: boolean;
285
  inline: ParserInline;
286
  block: ParserBlock;
287
  renderer: Renderer;
288
}
289
```
290

291
## Preset Configurations
292

293
### Default Preset
294

295
Basic markdown parsing with safe defaults.
296

297
```javascript
298
// Equivalent to:
299
const md = new Remarkable('default');
300
// or
301
const md = new Remarkable();
302
```
303

304
**Features:**
305
- Core parsing rules enabled
306
- HTML disabled for security
307
- Basic inline and block elements
308
- No advanced typography features
309

310
### Full Preset
311

312
All features enabled including advanced syntax extensions.
313

314
```javascript
315
const md = new Remarkable('full');
316
```
317

318
**Features:**
319
- All parsing rules enabled
320
- Advanced elements: tables, footnotes, definition lists
321
- Strikethrough, subscript, superscript, mark, insert
322
- Abbreviations and typographic replacements
323

324
### CommonMark Preset
325

326
Strict CommonMark specification compliance.
327

328
```javascript
329
const md = new Remarkable('commonmark');
330
```
331

332
**Features:**
333
- CommonMark specification compliance
334
- Minimal rule set for compatibility
335
- No syntax extensions
336
- Standard behavior for all elements