0
# Processor Creation
1

2
Advanced processor creation for building custom MDX transformation pipelines with full control over the unified processor chain. This allows for fine-grained control over the parsing, transformation, and code generation phases.
3

4
## Capabilities
5

6
### CreateProcessor Function
7

8
Creates a unified processor instance configured to compile markdown or MDX to JavaScript.
9

10
```typescript { .api }
11
/**
12
 * Create a processor to compile markdown or MDX to JavaScript
13
 * @param options - Optional processor configuration  
14
 * @returns Configured unified processor instance
15
 */
16
function createProcessor(options?: ProcessorOptions): Processor<Root, Program, Program, Program, string>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { createProcessor } from "@mdx-js/mdx";
23

24
// Basic processor
25
const processor = createProcessor();
26
const result = await processor.process('# Hello World');
27

28
// Custom processor with plugins
29
const processor = createProcessor({
30
  format: 'mdx',
31
  remarkPlugins: ['remark-gfm'],
32
  rehypePlugins: ['rehype-highlight']
33
});
34

35
// Process multiple files
36
const files = ['intro.mdx', 'guide.mdx'];
37
const results = await Promise.all(
38
  files.map(file => processor.process(file))
39
);
40
```
41

42
## Configuration
43

44
### ProcessorOptions Interface
45

46
Comprehensive configuration options for processor creation.
47

48
```typescript { .api }
49
interface ProcessorOptions {
50
  /** Format of input files */
51
  format?: 'md' | 'mdx';
52
  
53
  /** Whether to keep JSX instead of compiling it away */
54
  jsx?: boolean;
55
  
56
  /** JSX runtime to use */
57
  jsxRuntime?: 'automatic' | 'classic';
58
  
59
  /** Where to import automatic JSX runtime from */
60
  jsxImportSource?: string;
61
  
62
  /** Whether to add development info and use jsxDEV */
63
  development?: boolean;
64
  
65
  /** Output format for generated code */
66
  outputFormat?: 'program' | 'function-body';
67
  
68
  /** Base URL for resolving imports and export statements */
69
  baseUrl?: URL | string;
70
  
71
  /** Source map generator class for debugging */
72
  SourceMapGenerator?: typeof SourceMapGenerator;
73
  
74
  /** Attribute name casing for HTML elements */
75
  elementAttributeNameCase?: 'react' | 'html';
76
  
77
  /** Style property name casing for style objects */
78
  stylePropertyNameCase?: 'dom' | 'css';
79
  
80
  /** Convert obsolete align attributes to CSS styles */
81
  tableCellAlignToStyle?: boolean;
82
  
83
  /** List of markdown file extensions */
84
  mdExtensions?: ReadonlyArray<string>;
85
  
86
  /** List of MDX file extensions */  
87
  mdxExtensions?: ReadonlyArray<string>;
88
  
89
  /** Provider import source for component context */
90
  providerImportSource?: string;
91
  
92
  /** Remark plugins for markdown processing phase */
93
  remarkPlugins?: PluggableList;
94
  
95
  /** Rehype plugins for HTML processing phase */
96
  rehypePlugins?: PluggableList;
97
  
98
  /** Recma plugins for JavaScript generation phase */
99
  recmaPlugins?: PluggableList;
100
  
101
  /** Options passed to remark-rehype transformation */
102
  remarkRehypeOptions?: RemarkRehypeOptions;
103
}
104
```
105

106
## Plugin System
107

108
### Plugin Types
109

110
The processor supports three plugin phases:
111

112
```typescript { .api }
113
type PluggableList = Array<Pluggable>;
114
type Pluggable = Plugin | [Plugin, ...Parameters<Plugin>] | Preset;
115
```
116

117
**Remark Plugins** (Markdown phase):
118
- Process the markdown AST (mdast)
119
- Examples: remark-gfm, remark-toc, remark-breaks
120

121
**Rehype Plugins** (HTML phase):  
122
- Process the HTML AST (hast)
123
- Examples: rehype-highlight, rehype-slug, rehype-autolink-headings
124

125
**Recma Plugins** (JavaScript phase):
126
- Process the JavaScript AST (esast) 
127
- Examples: Custom code transformations, import rewriting
128

129
### Plugin Configuration Examples
130

131
```typescript
132
import { createProcessor } from "@mdx-js/mdx";
133

134
// GitHub Flavored Markdown
135
const processor = createProcessor({
136
  remarkPlugins: [
137
    'remark-gfm', // Tables, strikethrough, task lists
138
    ['remark-toc', { heading: 'contents', tight: true }]
139
  ]
140
});
141

142
// Syntax highlighting
143
const processor = createProcessor({
144
  rehypePlugins: [
145
    ['rehype-highlight', { languages: { typescript: 'ts' } }],
146
    'rehype-slug',
147
    ['rehype-autolink-headings', { behavior: 'wrap' }]
148
  ]
149
});
150

151
// Custom JavaScript transformations  
152
const processor = createProcessor({
153
  recmaPlugins: [
154
    function customTransform() {
155
      return (tree) => {
156
        // Transform JavaScript AST
157
      };
158
    }
159
  ]
160
});
161
```
162

163
## Advanced Usage
164

165
### Custom Pipeline Creation
166

167
```typescript
168
import { createProcessor } from "@mdx-js/mdx";
169
import { unified } from "unified";
170

171
// Extend processor with additional transformations
172
const processor = createProcessor({
173
  format: 'mdx',
174
  jsx: false
175
});
176

177
// Add custom processing steps
178
processor.use(function customPlugin() {
179
  return (tree, file) => {
180
    // Custom transformation logic
181
  };
182
});
183

184
// Process with custom pipeline
185
const result = await processor.process(mdxContent);
186
```
187

188
### Format-Specific Processing
189

190
```typescript
191
// Markdown-only processor
192
const markdownProcessor = createProcessor({
193
  format: 'md',
194
  jsx: false,
195
  remarkPlugins: ['remark-gfm']
196
});
197

198
// MDX-specific processor
199
const mdxProcessor = createProcessor({
200
  format: 'mdx', 
201
  jsx: false,
202
  jsxRuntime: 'automatic',
203
  providerImportSource: '@mdx-js/react'
204
});
205
```
206

207
### Runtime Configuration
208

209
```typescript
210
// Development configuration
211
const devProcessor = createProcessor({
212
  development: true,
213
  jsx: false,
214
  jsxRuntime: 'automatic',
215
  SourceMapGenerator: require('source-map').SourceMapGenerator
216
});
217

218
// Production configuration
219
const prodProcessor = createProcessor({
220
  development: false,
221
  jsx: false,
222
  jsxRuntime: 'automatic',
223
  outputFormat: 'program'
224
});
225
```
226

227
## Processor Instance Methods
228

229
The returned processor implements the unified Processor interface:
230

231
```typescript { .api }
232
interface Processor<Root, Program, Program, Program, string> {
233
  /** Process a file asynchronously */
234
  process(file: Compatible): Promise<VFile>;
235
  
236
  /** Process a file synchronously */
237
  processSync(file: Compatible): VFile;
238
  
239
  /** Parse input to AST */
240
  parse(file: Compatible): Root;
241
  
242
  /** Transform AST */
243
  run(tree: Root, file?: VFile): Promise<Program>;
244
  
245
  /** Compile AST to string */
246
  stringify(tree: Program, file?: VFile): string;
247
  
248
  /** Add a plugin */
249
  use<T extends any[]>(plugin: Plugin<T>, ...options: T): this;
250
}
251
```
252

253
## Error Handling
254

255
Processor creation and usage can throw errors for:
256

257
- **Invalid options**: Deprecated or unsupported configuration
258
- **Plugin errors**: Failed plugin loading or execution  
259
- **Format conflicts**: Using 'detect' format with createProcessor
260
- **Processing errors**: Syntax or transformation failures
261

262
```typescript
263
try {
264
  const processor = createProcessor({
265
    format: 'mdx',
266
    remarkPlugins: ['invalid-plugin']
267
  });
268
} catch (error) {
269
  console.error('Processor creation failed:', error.message);
270
}
271
```