0
# Advanced Configuration
1
2
Advanced parsing options including custom createElement behavior, HTML parsing control, and heading formatting rules.
3
4
## Capabilities
5
6
### Custom createElement
7
8
Override React's createElement function to customize how all elements are created and rendered.
9
10
```typescript { .api }
11
/**
12
* Custom element creation function
13
* Called for every JSX element created by the compiler
14
*/
15
type CreateElementFunction = (
16
tag: Parameters<React.createElement>[0],
17
props: React.JSX.IntrinsicAttributes,
18
...children: React.ReactNode[]
19
) => React.ReactNode;
20
21
interface CreateElementOptions {
22
createElement?: CreateElementFunction;
23
}
24
```
25
26
**Usage Examples:**
27
28
```typescript
29
import { compiler } from "markdown-to-jsx";
30
import { createElement } from "react";
31
32
// Custom createElement with global props injection
33
const customCreateElement = (tag, props, ...children) => {
34
// Add data attributes to all elements
35
const enhancedProps = {
36
...props,
37
'data-markdown': 'true',
38
'data-tag': typeof tag === 'string' ? tag : tag.name
39
};
40
41
return createElement(tag, enhancedProps, ...children);
42
};
43
44
// Custom createElement with element tracking
45
const trackingCreateElement = (tag, props, ...children) => {
46
// Track which elements are being created
47
console.log(`Creating element: ${tag}`, props);
48
49
return createElement(tag, props, ...children);
50
};
51
52
// Custom createElement for different React-like libraries
53
const preactCreateElement = (tag, props, ...children) => {
54
// Adapt for Preact or other React-like libraries
55
return h(tag, props, ...children);
56
};
57
58
const options = {
59
createElement: customCreateElement
60
};
61
62
const result = compiler("# Hello **World**", options);
63
```
64
65
### HTML Parsing Control
66
67
Control how raw HTML in markdown is processed and converted to JSX.
68
69
```typescript { .api }
70
interface HTMLParsingOptions {
71
/** Disable parsing of raw HTML tags into JSX */
72
disableParsingRawHTML?: boolean;
73
}
74
```
75
76
**Usage Examples:**
77
78
```typescript
79
// Allow HTML parsing (default behavior)
80
const htmlContent = `
81
# Title
82
83
<div class="custom">
84
This **markdown** works inside HTML.
85
<span style="color: red;">Styled text</span>
86
</div>
87
88
Regular markdown continues.
89
`;
90
91
const withHTML = compiler(htmlContent, {
92
disableParsingRawHTML: false // default
93
});
94
95
// Disable HTML parsing (treat as literal text)
96
const withoutHTML = compiler(htmlContent, {
97
disableParsingRawHTML: true
98
});
99
// HTML tags become literal text instead of JSX elements
100
101
// Security consideration - disable HTML for untrusted content
102
const userContent = getUserMarkdown(); // potentially unsafe
103
const safeResult = compiler(userContent, {
104
disableParsingRawHTML: true // prevents HTML injection
105
});
106
```
107
108
### Auto-linking Control
109
110
Control automatic conversion of URLs to clickable links.
111
112
```typescript { .api }
113
interface AutoLinkOptions {
114
/** Disable automatic URL linking */
115
disableAutoLink?: boolean;
116
}
117
```
118
119
**Usage Examples:**
120
121
```typescript
122
const contentWithURLs = `
123
Check out https://example.com for more info.
124
125
Also see http://another-site.com and https://third-site.com.
126
`;
127
128
// With auto-linking (default)
129
const withLinks = compiler(contentWithURLs, {
130
disableAutoLink: false // default
131
});
132
// URLs become clickable <a> tags
133
134
// Without auto-linking
135
const withoutLinks = compiler(contentWithURLs, {
136
disableAutoLink: true
137
});
138
// URLs remain as plain text
139
```
140
141
### Heading Format Control
142
143
Enforce strict CommonMark compliance for heading syntax.
144
145
```typescript { .api }
146
interface HeadingOptions {
147
/** Require space after # characters in ATX headings */
148
enforceAtxHeadings?: boolean;
149
}
150
```
151
152
**Usage Examples:**
153
154
```typescript
155
const headingContent = `
156
#NoSpace
157
# With Space
158
##AlsoNoSpace
159
## Also With Space
160
`;
161
162
// Lenient parsing (default)
163
const lenient = compiler(headingContent, {
164
enforceAtxHeadings: false // default
165
});
166
// Both styles work: "#NoSpace" and "# With Space"
167
168
// Strict CommonMark compliance
169
const strict = compiler(headingContent, {
170
enforceAtxHeadings: true
171
});
172
// Only "# With Space" becomes heading, "#NoSpace" remains text
173
```
174
175
### Wrapper Element Control
176
177
Control how content is wrapped in container elements.
178
179
```typescript { .api }
180
interface WrapperOptions {
181
/** Force block-level wrapper regardless of content */
182
forceBlock?: boolean;
183
184
/** Force inline wrapper regardless of content */
185
forceInline?: boolean;
186
187
/** Always wrap content even for single elements */
188
forceWrapper?: boolean;
189
190
/** Custom wrapper element type or null for no wrapper */
191
wrapper?: React.ElementType | null;
192
}
193
```
194
195
**Usage Examples:**
196
197
```typescript
198
const singleParagraph = "Just a simple paragraph.";
199
const multipleElements = "# Title\n\nParagraph content.";
200
201
// Force block wrapper
202
const forceBlock = compiler(singleParagraph, {
203
forceBlock: true
204
});
205
// Wrapped in <div> even though content is inline
206
207
// Force inline wrapper
208
const forceInline = compiler(multipleElements, {
209
forceInline: true
210
});
211
// Wrapped in <span> even though content has block elements
212
213
// Always force wrapper
214
const alwaysWrap = compiler(singleParagraph, {
215
forceWrapper: true
216
});
217
// Single paragraph still gets wrapper element
218
219
// Custom wrapper element
220
const customWrapper = compiler(multipleElements, {
221
wrapper: "article"
222
});
223
// Content wrapped in <article> instead of <div>
224
225
// No wrapper (returns array)
226
const noWrapper = compiler(multipleElements, {
227
wrapper: null
228
});
229
// Returns [<h1>...</h1>, <p>...</p>] instead of wrapped content
230
231
// React Fragment wrapper
232
const fragmentWrapper = compiler(multipleElements, {
233
wrapper: React.Fragment
234
});
235
// Wrapped in <React.Fragment>
236
```
237
238
### Entity Decoding Control
239
240
Customize HTML entity to Unicode character mappings.
241
242
```typescript { .api }
243
interface EntityOptions {
244
/** Custom HTML entity mappings */
245
namedCodesToUnicode?: { [key: string]: string };
246
}
247
```
248
249
**Usage Examples:**
250
251
```typescript
252
const contentWithEntities = `
253
Standard entities: & < > " '
254
255
Custom entities: &heart; ☆ &arrow;
256
`;
257
258
// Default entity mappings
259
const defaultEntities = compiler(contentWithEntities);
260
// Only standard entities are decoded
261
262
// Custom entity mappings
263
const customEntities = compiler(contentWithEntities, {
264
namedCodesToUnicode: {
265
// Extend default mappings
266
heart: "❤️",
267
star: "⭐",
268
arrow: "→",
269
// Override defaults
270
amp: "＆", // Use full-width ampersand
271
}
272
});
273
// Custom entities are decoded along with defaults
274
```
275
276
### Complete Advanced Configuration
277
278
Combine multiple advanced options for complex use cases.
279
280
**Usage Examples:**
281
282
```typescript
283
import { compiler } from "markdown-to-jsx";
284
import { trackElementCreation } from "./analytics";
285
286
const advancedOptions = {
287
// Custom element creation with analytics
288
createElement: (tag, props, ...children) => {
289
trackElementCreation(tag, props);
290
return React.createElement(tag, props, ...children);
291
},
292
293
// Security settings
294
disableParsingRawHTML: true,
295
disableAutoLink: false,
296
297
// Strict markdown compliance
298
enforceAtxHeadings: true,
299
300
// Custom wrapper for semantic HTML
301
wrapper: "main",
302
forceWrapper: true,
303
304
// Extended entity support
305
namedCodesToUnicode: {
306
copyright: "©",
307
trademark: "™",
308
registered: "®"
309
}
310
};
311
312
const secureResult = compiler(userMarkdownContent, advancedOptions);
313
```