0
# Core Compilation
1

2
Core markdown parsing and JSX compilation functionality for converting markdown strings to React elements with extensive configuration options.
3

4
## Capabilities
5

6
### Compiler Function
7

8
Main compilation function that converts markdown strings to React JSX elements with optional configuration.
9

10
```typescript { .api }
11
/**
12
 * Converts markdown string to React JSX elements
13
 * @param markdown - The markdown string to compile (defaults to empty string)
14
 * @param options - Configuration options for parsing and rendering
15
 * @returns React JSX element representing the compiled markdown
16
 */
17
function compiler(
18
  markdown?: string,
19
  options?: MarkdownToJSX.Options
20
): React.JSX.Element;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { compiler } from "markdown-to-jsx";
27

28
// Basic compilation
29
const basicJsx = compiler("# Hello World\n\nThis is **bold** text.");
30

31
// With options
32
const customJsx = compiler("# Custom Title", {
33
  forceBlock: true,
34
  overrides: {
35
    h1: { props: { className: "custom-heading" } }
36
  }
37
});
38

39
// Complex markdown with all features
40
const complexMarkdown = `
41
# Main Title
42

43
## Features
44

45
- [x] Task lists
46
- [ ] Pending item
47

48
| Feature | Status |
49
|---------|--------|
50
| Tables  | ✓      |
51
| Links   | ✓      |
52

53
\`\`\`javascript
54
const code = "syntax highlighting";
55
\`\`\`
56

57
> Blockquotes with **formatting**
58

59
![Image](https://example.com/image.jpg "Title")
60

61
[Link text](https://example.com)
62

63
Footnote reference[^1]
64

65
[^1]: This is a footnote
66
`;
67

68
const result = compiler(complexMarkdown, {
69
  enforceAtxHeadings: true,
70
  overrides: {
71
    pre: {
72
      component: ({ children }) => (
73
        <pre className="syntax-highlighted">{children}</pre>
74
      )
75
    }
76
  }
77
});
78
```
79

80
### Options Configuration
81

82
Comprehensive configuration interface for controlling all aspects of markdown parsing and rendering.
83

84
```typescript { .api }
85
interface MarkdownToJSX.Options {
86
  /** Custom React.createElement function */
87
  createElement?: (
88
    tag: Parameters<CreateElement>[0],
89
    props: React.JSX.IntrinsicAttributes,
90
    ...children: React.ReactNode[]
91
  ) => React.ReactNode;
92
  
93
  /** Disable automatic URL linking */
94
  disableAutoLink?: boolean;
95
  
96
  /** Disable HTML parsing into JSX */
97
  disableParsingRawHTML?: boolean;
98
  
99
  /** Require space after # in headings per CommonMark spec */
100
  enforceAtxHeadings?: boolean;
101
  
102
  /** Force block-level wrapper element */
103
  forceBlock?: boolean;
104
  
105
  /** Force inline wrapper element */
106
  forceInline?: boolean;
107
  
108
  /** Always wrap content even for single elements */
109
  forceWrapper?: boolean;
110
  
111
  /** Custom HTML entity to unicode mappings */
112
  namedCodesToUnicode?: { [key: string]: string };
113
  
114
  /** Component and prop overrides for HTML tags */
115
  overrides?: Overrides;
116
  
117
  /** Custom rendering function for complete control */
118
  renderRule?: (
119
    next: () => React.ReactNode,
120
    node: ParserResult,
121
    renderChildren: RuleOutput,
122
    state: State
123
  ) => React.ReactNode;
124
  
125
  /** Custom URL/content sanitizer function */
126
  sanitizer?: (
127
    value: string,
128
    tag: HTMLTags,
129
    attribute: string
130
  ) => string | null;
131
  
132
  /** Custom slug generation for heading IDs */
133
  slugify?: (
134
    input: string,
135
    defaultFn: (input: string) => string
136
  ) => string;
137
  
138
  /** Wrapper element type or null for no wrapper */
139
  wrapper?: React.ElementType | null;
140
}
141
```
142

143
### Parsing Features
144

145
Comprehensive markdown feature support including GFM extensions and custom markdown elements.
146

147
**Supported Markdown Elements:**
148

149
- **Headings**: ATX (`# Title`) and Setext (`Title\n=====`) style headings
150
- **Text Formatting**: Bold (`**text**`), italic (`*text*`), strikethrough (`~~text~~`), marked (`==text==`)
151
- **Lists**: Ordered (`1. item`) and unordered (`- item`) lists with nesting
152
- **Links**: Inline (`[text](url)`), reference (`[text][ref]`), and autolinks
153
- **Images**: Inline (`![alt](src)`) and reference (`![alt][ref]`) images
154
- **Code**: Inline (`` `code` ``) and fenced (``` ``` ```) code blocks with language highlighting
155
- **Tables**: GFM-style tables with alignment support
156
- **Blockquotes**: Standard (`> quote`) and GitHub alert style
157
- **Task Lists**: GFM task lists (`- [x] completed`, `- [ ] pending`)
158
- **HTML**: Raw HTML parsing with JSX conversion
159
- **Footnotes**: Reference-style footnotes (`[^ref]` and `[^ref]: content`)
160
- **Line Breaks**: Hard breaks (`  \n`) and thematic breaks (`---`)
161

162
**Usage Examples:**
163

164
```typescript
165
// GFM Task Lists
166
const taskList = compiler(`
167
- [x] Completed task
168
- [ ] Pending task
169
- [x] Another completed task
170
`);
171

172
// Tables with alignment
173
const table = compiler(`
174
| Left | Center | Right |
175
|------|:------:|------:|
176
| L1   |   C1   |    R1 |
177
| L2   |   C2   |    R2 |
178
`);
179

180
// Footnotes
181
const footnotes = compiler(`
182
Here's a sentence with a footnote[^1].
183

184
[^1]: This is the footnote content.
185
`);
186

187
// Mixed HTML and Markdown
188
const mixed = compiler(`
189
# Title
190

191
<div class="custom">
192
  This is **markdown** inside HTML.
193
</div>
194

195
Regular markdown continues here.
196
`);
197
```
198

199
### Error Handling
200

201
The compiler handles malformed markdown gracefully, falling back to safe rendering for problematic content.
202

203
```typescript
204
// Invalid markdown is handled gracefully
205
const result = compiler(`
206
# Incomplete [link](
207
**Unclosed bold
208
\`\`\`unclosed-code
209
`);
210

211
// Malicious content is sanitized
212
const sanitized = compiler(`
213
[Click me](javascript:alert('xss'))
214
<script>alert('xss')</script>
215
`);
216
```