0
# Remarkable
1

2
Remarkable is a high-performance Markdown parser with full CommonMark compliance and extensive syntax extensions. It provides a modular architecture with configurable rule systems for block parsing, inline parsing, and rendering, supporting advanced features like footnotes, tables, strikethrough, and typographic enhancements.
3

4
## Package Information
5

6
- **Package Name**: remarkable
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6)
9
- **Installation**: `npm install remarkable`
10

11
## Core Imports
12

13
```javascript
14
import { Remarkable, utils } from "remarkable";
15
import { linkify } from "remarkable/linkify";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Remarkable, utils } = require("remarkable");
22
const { linkify } = require("remarkable/linkify");
23
```
24

25
For UMD (browser):
26

27
```javascript
28
const { Remarkable, linkify, utils } = window.remarkable;
29
```
30

31
## Basic Usage
32

33
```javascript
34
import { Remarkable } from "remarkable";
35

36
// Create parser with default preset
37
const md = new Remarkable();
38

39
// Parse markdown to HTML
40
const html = md.render('# Hello World\n\nThis is **bold** text.');
41
// Output: <h1>Hello World</h1><p>This is <strong>bold</strong> text.</p>
42

43
// Use preset with options
44
const mdFull = new Remarkable('full', {
45
  html: true,
46
  typographer: true,
47
  breaks: true
48
});
49

50
const result = mdFull.render('# Title\n\nText with "smart quotes" and...');
51
```
52

53
## Architecture
54

55
Remarkable is built around several key components:
56

57
- **Parser Core**: Central processing engine that coordinates all parsing operations
58
- **Rule-based System**: Modular parsing rules for blocks, inline elements, and core processing
59
- **Three-stage Pipeline**: Block parsing → Inline parsing → HTML rendering
60
- **Preset Configurations**: Pre-configured rule sets (default, full, commonmark)
61
- **Plugin System**: Extensible architecture for adding custom functionality
62
- **Renderer**: Configurable HTML output generation with customizable rules
63

64
## Capabilities
65

66
### Core Parser
67

68
Main parser functionality for converting markdown to HTML with configurable presets and options.
69

70
```javascript { .api }
71
class Remarkable {
72
  constructor(preset?: string, options?: RemarkableOptions);
73
  render(markdown: string, env?: object): string;
74
  parse(markdown: string, env?: object): Token[];
75
  renderInline(markdown: string, env?: object): string;
76
  parseInline(markdown: string, env?: object): Token[];
77
  set(options: RemarkableOptions): void;
78
  configure(presets: PresetConfig): void;
79
  use(plugin: PluginFunction, options?: object): Remarkable;
80
  
81
  // Parser components access
82
  core: ParserCore;
83
  block: ParserBlock;
84
  inline: ParserInline;
85
  renderer: Renderer;
86
  ruler: Ruler;
87
  options: RemarkableOptions;
88
}
89

90
interface RemarkableOptions {
91
  html?: boolean;
92
  xhtmlOut?: boolean;
93
  breaks?: boolean;
94
  langPrefix?: string;
95
  linkTarget?: string;
96
  typographer?: boolean;
97
  quotes?: string;
98
  highlight?: (str: string, lang: string) => string;
99
  maxNesting?: number;
100
}
101
```
102

103
[Core Parser](./core-parser.md)
104

105
### Rule System & Configuration
106

107
Advanced rule management and preset configuration for customizing parser behavior.
108

109
```javascript { .api }
110
interface PresetConfig {
111
  options?: RemarkableOptions;
112
  components?: {
113
    core?: { rules: string[] };
114
    block?: { rules: string[] };
115
    inline?: { rules: string[] };
116
  };
117
}
118

119
class Ruler {
120
  push(name: string, fn: RuleFunction, options?: RuleOptions): void;
121
  before(beforeName: string, ruleName: string, fn: RuleFunction, options?: RuleOptions): void;
122
  after(afterName: string, ruleName: string, fn: RuleFunction, options?: RuleOptions): void;
123
  at(name: string, fn: RuleFunction, options?: RuleOptions): void;
124
  enable(names: string | string[], ignoreInvalid?: boolean): string[];
125
  disable(names: string | string[], ignoreInvalid?: boolean): string[];
126
  getRules(chainName: string): RuleFunction[];
127
}
128
```
129

130
[Rule System](./rule-system.md)
131

132
### Rendering & Output
133

134
Customizable HTML rendering system with extensible rule-based output generation.
135

136
```javascript { .api }
137
class Renderer {
138
  render(tokens: Token[], options: RemarkableOptions, env: object): string;
139
  renderInline(tokens: Token[], options: RemarkableOptions, env: object): string;
140
  rules: RendererRules;
141
  getBreak: (tokens: Token[], idx: number) => string;
142
}
143

144
interface RendererRules {
145
  [ruleName: string]: (tokens: Token[], idx: number, options: RemarkableOptions, env: object, renderer: Renderer) => string;
146
}
147
```
148

149
[Rendering System](./rendering.md)
150

151
### Linkify Plugin
152

153
Optional plugin for automatic URL and email detection and conversion to links.
154

155
```javascript { .api }
156
function linkify(md: Remarkable): void;
157
```
158

159
[Linkify Plugin](./linkify.md)
160

161
### Utility Functions
162

163
Helper functions for custom rule development and text processing.
164

165
```javascript { .api }
166
interface Utils {
167
  isString(obj: any): boolean;
168
  has(object: object, key: string): boolean;
169
  assign(target: object, ...sources: object[]): object;
170
  unescapeMd(str: string): string;
171
  replaceEntities(str: string): string;
172
  escapeHtml(str: string): string;
173
}
174
```
175

176
[Utilities](./utilities.md)
177

178
## Types
179

180
```javascript { .api }
181
interface Token {
182
  type: string;
183
  tag?: string;
184
  attrs?: Array<[string, string]>;
185
  map?: [number, number];
186
  nesting?: number;
187
  level?: number;
188
  children?: Token[];
189
  content?: string;
190
  markup?: string;
191
  info?: string;
192
  meta?: any;
193
  block?: boolean;
194
  hidden?: boolean;
195
  
196
  // Token attribute methods
197
  attrGet(name: string): string | null;
198
  attrSet(name: string, value: string): void;
199
  attrPush(attr: [string, string]): void;
200
  attrJoin(name: string, value: string): void;
201
}
202

203
type RuleFunction = (state: StateCore | StateBlock | StateInline) => boolean | void;
204

205
type PluginFunction = (md: Remarkable, options?: object) => void;
206

207
interface RuleOptions {
208
  alt?: string[];
209
}
210

211
// Parser component interfaces
212
interface ParserCore {
213
  ruler: Ruler;
214
  process(state: StateCore): void;
215
}
216

217
interface ParserBlock {
218
  ruler: Ruler;
219
  tokenize(state: StateBlock, startLine: number, endLine: number): void;
220
  parse(str: string, options: RemarkableOptions, env: object, outTokens: Token[]): void;
221
}
222

223
interface ParserInline {
224
  ruler: Ruler;
225
  validateLink: (url: string) => boolean;
226
  skipToken(state: StateInline): void;
227
  tokenize(state: StateInline): void;
228
  parse(str: string, options: RemarkableOptions, env: object, outTokens: Token[]): void;
229
}
230

231
// State interfaces for rule development
232
interface StateCore {
233
  src: string;
234
  env: object;
235
  options: RemarkableOptions;
236
  tokens: Token[];
237
  inlineMode: boolean;
238
  inline: ParserInline;
239
  block: ParserBlock;
240
  renderer: Renderer;
241
}
242

243
interface StateBlock {
244
  src: string;
245
  md: Remarkable;
246
  env: object;
247
  tokens: Token[];
248
  bMarks: number[];
249
  eMarks: number[];
250
  tShift: number[];
251
  sCount: number[];
252
  blkIndent: number;
253
  line: number;
254
  lineMax: number;
255
  tight: boolean;
256
  parentType: string;
257
  ddIndent: number;
258
  getLines(begin: number, end: number, indent: number, keepLastLF: boolean): string;
259
  isEmpty(line: number): boolean;
260
  skipEmptyLines(from: number): number;
261
  skipSpaces(pos: number): number;
262
  skipChars(pos: number, code: number): number;
263
  skipCharsBack(pos: number, code: number, min: number): number;
264
  push(token: Token): void;
265
}
266

267
interface StateInline {
268
  src: string;
269
  env: object;
270
  md: Remarkable;
271
  tokens: Token[];
272
  pos: number;
273
  posMax: number;
274
  level: number;
275
  pending: string;
276
  pendingLevel: number;
277
  cache: object;
278
  delimiters: object[];
279
  push(token: Token): void;
280
  pushPending(): Token;
281
  scanDelims(start: number, canSplitWord: boolean): object;
282
  cacheGet(pos: number): number;
283
  cacheSet(pos: number, value: number): void;
284
}
285
```