0
# markdown-to-jsx
1
2
markdown-to-jsx is a lightweight, customizable React markdown component that converts Markdown strings to JSX elements. It provides a safer alternative to dangerouslySetInnerHTML by parsing arbitrary HTML into proper JSX representations, offering extensive configuration options for component overrides, custom rendering, and advanced markdown features like GFM task lists, tables, and footnotes.
3
4
## Package Information
5
6
- **Package Name**: markdown-to-jsx
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install markdown-to-jsx`
10
11
## Core Imports
12
13
```typescript
14
import Markdown, { compiler, RuleType, slugify, sanitizer } from "markdown-to-jsx";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const Markdown = require("markdown-to-jsx");
21
const { compiler, RuleType } = Markdown;
22
// Note: slugify and sanitizer are only available in ESM imports
23
```
24
25
## Basic Usage
26
27
```typescript
28
import Markdown from "markdown-to-jsx";
29
import React from "react";
30
31
// Component usage
32
function App() {
33
return (
34
<Markdown>
35
# Hello World
36
37
This is **bold** and this is *italic*.
38
39
- List item 1
40
- List item 2
41
</Markdown>
42
);
43
}
44
45
// Direct compilation
46
import { compiler } from "markdown-to-jsx";
47
48
const jsx = compiler("# Title\n\nSome content with **formatting**.");
49
```
50
51
## Architecture
52
53
markdown-to-jsx is built around several key components:
54
55
- **Markdown Component**: High-level React component that accepts markdown as children
56
- **Compiler Function**: Core parsing and compilation engine that converts markdown to JSX
57
- **Rule System**: Extensible parser with 30+ built-in rules for different markdown elements
58
- **Override System**: Flexible component replacement mechanism for any HTML tag
59
- **Type System**: Comprehensive TypeScript definitions with generic type preservation
60
- **Sanitization**: Built-in URL and content sanitizer for security
61
62
## Capabilities
63
64
### Core Compilation
65
66
Essential markdown parsing and JSX compilation functionality for converting markdown strings to React elements.
67
68
```typescript { .api }
69
function compiler(
70
markdown?: string,
71
options?: MarkdownToJSX.Options
72
): React.JSX.Element;
73
74
interface MarkdownToJSX.Options {
75
createElement?: CreateElement;
76
disableAutoLink?: boolean;
77
disableParsingRawHTML?: boolean;
78
enforceAtxHeadings?: boolean;
79
forceBlock?: boolean;
80
forceInline?: boolean;
81
forceWrapper?: boolean;
82
namedCodesToUnicode?: { [key: string]: string };
83
overrides?: Overrides;
84
renderRule?: RenderRuleFunction;
85
sanitizer?: SanitizerFunction;
86
slugify?: SlugifyFunction;
87
wrapper?: React.ElementType | null;
88
}
89
```
90
91
[Core Compilation](./core-compilation.md)
92
93
### Component Interface
94
95
React component wrapper providing convenient JSX integration with markdown content and configuration options.
96
97
```typescript { .api }
98
interface MarkdownProps {
99
children: string;
100
options?: MarkdownToJSX.Options;
101
}
102
103
const Markdown: React.FC<MarkdownProps & React.HTMLAttributes<Element>>;
104
```
105
106
[Component Interface](./component-interface.md)
107
108
### Component Overrides
109
110
Powerful system for replacing any HTML tag with custom React components, including props injection and component mapping.
111
112
```typescript { .api }
113
interface Override {
114
component?: React.ElementType;
115
props?: object;
116
}
117
118
type Overrides = {
119
[tag in HTMLTags]?: Override | React.ElementType;
120
} & {
121
[customComponent: string]: Override | React.ElementType;
122
};
123
```
124
125
[Component Overrides](./component-overrides.md)
126
127
### Advanced Configuration
128
129
Advanced parsing options including custom createElement behavior, HTML parsing control, and heading formatting rules.
130
131
```typescript { .api }
132
interface AdvancedOptions {
133
createElement?: (
134
tag: Parameters<CreateElement>[0],
135
props: React.JSX.IntrinsicAttributes,
136
...children: React.ReactNode[]
137
) => React.ReactNode;
138
disableAutoLink?: boolean;
139
disableParsingRawHTML?: boolean;
140
enforceAtxHeadings?: boolean;
141
forceBlock?: boolean;
142
forceInline?: boolean;
143
forceWrapper?: boolean;
144
wrapper?: React.ElementType | null;
145
}
146
```
147
148
[Advanced Configuration](./advanced-configuration.md)
149
150
### Custom Rendering
151
152
Complete control over individual rule rendering through custom render functions and rule system integration.
153
154
```typescript { .api }
155
type RenderRuleFunction = (
156
next: () => React.ReactNode,
157
node: ParserResult,
158
renderChildren: RuleOutput,
159
state: State
160
) => React.ReactNode;
161
162
const RuleType: {
163
readonly blockQuote: "0";
164
readonly breakLine: "1";
165
readonly breakThematic: "2";
166
readonly codeBlock: "3";
167
readonly codeFenced: "4";
168
readonly codeInline: "5";
169
// ... 28 more rule types
170
};
171
```
172
173
[Custom Rendering](./custom-rendering.md)
174
175
### Utility Functions
176
177
Helper functions for content sanitization, slug generation, and other common markdown processing tasks.
178
179
```typescript { .api }
180
function sanitizer(input: string): string | null;
181
182
function slugify(str: string): string;
183
```
184
185
[Utility Functions](./utility-functions.md)
186
187
## Types
188
189
```typescript { .api }
190
type CreateElement = typeof React.createElement;
191
192
type HTMLTags = keyof React.JSX.IntrinsicElements;
193
194
interface State {
195
inAnchor?: boolean;
196
inHTML?: boolean;
197
inline?: boolean;
198
inTable?: boolean;
199
key?: React.Key;
200
list?: boolean;
201
prevCapture?: string;
202
simple?: boolean;
203
}
204
205
type ParserResult =
206
| BlockQuoteNode
207
| HeadingNode
208
| LinkNode
209
| ImageNode
210
| CodeBlockNode
211
| TextNode
212
// ... union of 30+ node types
213
214
type SanitizerFunction = (
215
value: string,
216
tag: HTMLTags,
217
attribute: string
218
) => string | null;
219
220
type SlugifyFunction = (
221
input: string,
222
defaultFn: (input: string) => string
223
) => string;
224
225
type RuleOutput = (
226
ast: ParserResult | ParserResult[],
227
state: State
228
) => React.JSX.Element;
229
```