0
# MDX Integration
1

2
Enhanced MDX components and utilities for creating long-form documentation with embedded stories, interactive elements, and seamless integration with Storybook's component ecosystem.
3

4
## Capabilities
5

6
### MDX Component Utilities  
7

8
Core utilities for enhancing MDX rendering with Storybook-specific functionality.
9

10
```typescript { .api }
11
/**
12
 * Validates story functions in MDX contexts
13
 * @param storyFn - Function to validate
14
 * @throws Error if not a valid story function
15
 */
16
function assertIsFn(storyFn: any): asserts storyFn is Function;
17

18
/**
19
 * Context provider for MDX rendering with Storybook integration
20
 * @param props - Context provider props
21
 * @returns React context provider for MDX
22
 */
23
function AddContext(props: AddContextProps): React.ReactElement;
24

25
interface AddContextProps {
26
  children: React.ReactNode;
27
  context: any;
28
}
29
```
30

31
### Enhanced MDX Components
32

33
Specialized components that extend standard MDX elements with Storybook-specific features.
34

35
```typescript { .api }
36
/**
37
 * Renders code blocks in MDX with proper formatting and syntax highlighting
38
 * @param props - Code block configuration
39
 * @returns React component with formatted code
40
 */
41
function CodeOrSourceMdx(props: CodeOrSourceMdxProps): React.ReactElement;
42

43
interface CodeOrSourceMdxProps {
44
  /** Code content to display */
45
  children: string;
46
  /** Programming language for syntax highlighting */
47
  className?: string;
48
  /** Enable line numbers */
49
  showLineNumbers?: boolean;
50
  /** Code formatting options */
51
  format?: boolean | string;
52
}
53

54
/**
55
 * Enhanced anchor links with auto-generated IDs for navigation
56
 * @param props - Anchor configuration
57
 * @returns React component with enhanced anchor
58
 */
59
function AnchorMdx(props: AnchorMdxProps): React.ReactElement;
60

61
interface AnchorMdxProps {
62
  /** Anchor ID for linking */
63
  id: string;
64
  /** Link content */
65
  children: React.ReactNode;
66
  /** CSS class name */
67
  className?: string;
68
}
69

70
/**
71
 * Header components with automatic anchor generation and TOC integration
72
 * @param props - Header configuration
73
 * @returns React component with enhanced header
74
 */
75
function HeaderMdx(props: HeaderMdxProps): React.ReactElement;
76

77
interface HeaderMdxProps {
78
  /** Header level */
79
  as: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
80
  /** Header content */
81
  children: React.ReactNode;
82
  /** CSS class name */
83
  className?: string;
84
  /** Custom ID for anchor */
85
  id?: string;
86
}
87
```
88

89
### Header Component Map
90

91
Pre-configured header components for direct use in MDX documents.
92

93
```typescript { .api }
94
/**
95
 * Map of header components (h1-h6) for MDX rendering
96
 */
97
const HeadersMdx: HeadersMdxMap;
98

99
interface HeadersMdxMap {
100
  h1: React.FC<HeaderProps>;
101
  h2: React.FC<HeaderProps>;
102
  h3: React.FC<HeaderProps>;
103
  h4: React.FC<HeaderProps>;
104
  h5: React.FC<HeaderProps>;
105
  h6: React.FC<HeaderProps>;
106
}
107

108
interface HeaderProps {
109
  children: React.ReactNode;
110
  id?: string;
111
  className?: string;
112
}
113
```
114

115
**Usage Examples:**
116

117
```mdx
118
import { HeadersMdx, CodeOrSourceMdx, AnchorMdx } from "@storybook/addon-docs/blocks";
119

120
# My Documentation
121
<HeadersMdx.h1>Enhanced Header with Auto-Anchor</HeadersMdx.h1>
122

123
## Code Example
124
<CodeOrSourceMdx className="language-typescript">
125
{`
126
function myComponent() {
127
  return <div>Hello World</div>;
128
}
129
`}
130
</CodeOrSourceMdx>
131

132
<AnchorMdx id="custom-section">Jump to this section</AnchorMdx>
133
```
134

135
### MDX React Shim
136

137
Re-export of @mdx-js/react for framework compatibility and consistent MDX rendering.
138

139
```typescript { .api }
140
/**
141
 * Complete re-export of @mdx-js/react for framework compatibility
142
 * Provides MDXProvider and other MDX utilities
143
 */
144
export * from "@mdx-js/react";
145

146
// Key exports include:
147
interface MDXProviderProps {
148
  /** Custom component mapping for MDX elements */
149
  components?: MDXComponents;
150
  /** Child content to wrap */
151
  children: React.ReactNode;
152
}
153

154
interface MDXComponents {
155
  /** HTML element mappings */
156
  h1?: React.ComponentType<any>;
157
  h2?: React.ComponentType<any>;
158
  h3?: React.ComponentType<any>;
159
  h4?: React.ComponentType<any>;
160
  h5?: React.ComponentType<any>;
161
  h6?: React.ComponentType<any>;
162
  p?: React.ComponentType<any>;
163
  a?: React.ComponentType<any>;
164
  code?: React.ComponentType<any>;
165
  pre?: React.ComponentType<any>;
166
  [key: string]: React.ComponentType<any> | undefined;
167
}
168

169
/**
170
 * MDX Provider for custom component mapping
171
 */
172
const MDXProvider: React.FC<MDXProviderProps>;
173

174
/**
175
 * Hook for accessing MDX components within MDX context
176
 */
177
function useMDXComponents(): MDXComponents;
178
```
179

180
## Integration Patterns
181

182
### Story Embedding
183

184
Embedding Storybook stories directly in MDX documents with full interactivity.
185

186
```mdx
187
import { Canvas, Story } from "@storybook/addon-docs/blocks";
188
import * as ButtonStories from "./Button.stories";
189

190
# Button Documentation
191

192
Here's our primary button:
193

194
<Canvas of={ButtonStories.Primary} />
195

196
You can also embed stories inline:
197

198
<Story of={ButtonStories.Secondary} inline />
199
```
200

201
### Custom Component Integration
202

203
Creating custom MDX components that integrate with Storybook's ecosystem.
204

205
```typescript
206
// Custom MDX component
207
function CustomMDXBlock({ children, highlight = false }) {
208
  return (
209
    <div className={`custom-block ${highlight ? 'highlighted' : ''}`}>
210
      {children}
211
    </div>
212
  );
213
}
214

215
// Use in MDX
216
import { CustomMDXBlock } from "./CustomComponents";
217

218
<CustomMDXBlock highlight>
219
This is a custom highlighted block in MDX!
220
</CustomMDXBlock>
221
```
222

223
### Advanced MDX Configuration
224

225
Configuring MDX with custom components and enhanced rendering.
226

227
```typescript
228
// .storybook/main.js MDX configuration
229
export default {
230
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx|mdx)"],
231
  addons: ["@storybook/addon-docs"],
232
  docs: {
233
    defaultName: "Documentation",
234
    autodocs: true
235
  },
236
  // MDX configuration
237
  features: {
238
    modern: true
239
  }
240
};
241

242
// Custom MDX components mapping
243
const mdxComponents = {
244
  h1: HeadersMdx.h1,
245
  h2: HeadersMdx.h2,
246
  h3: HeadersMdx.h3,
247
  h4: HeadersMdx.h4,
248
  h5: HeadersMdx.h5,
249
  h6: HeadersMdx.h6,
250
  code: CodeOrSourceMdx,
251
  a: AnchorMdx
252
};
253
```
254

255
### MDX with TypeScript
256

257
Type-safe MDX component development with full TypeScript integration.
258

259
```typescript
260
// Types for MDX components
261
interface MDXContentProps {
262
  children?: React.ReactNode;
263
  components?: MDXComponents;
264
}
265

266
// Custom typed MDX component
267
const TypedMDXComponent: React.FC<MDXContentProps> = ({ 
268
  children, 
269
  components = {} 
270
}) => {
271
  const mergedComponents = {
272
    ...HeadersMdx,
273
    ...components
274
  };
275
  
276
  return (
277
    <MDXProvider components={mergedComponents}>
278
      {children}
279
    </MDXProvider>
280
  );
281
};
282
```
283

284
## Error Handling
285

286
MDX integration includes robust error handling for invalid story references and component errors.
287

288
```typescript { .api }
289
/**
290
 * Error boundary specifically for MDX content rendering
291
 */
292
class MDXErrorBoundary extends React.Component {
293
  constructor(props: { children: React.ReactNode });
294
  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
295
  render(): React.ReactNode;
296
}
297

298
/**
299
 * Error display component for MDX parsing errors
300
 */
301
function MDXError(props: MDXErrorProps): React.ReactElement;
302

303
interface MDXErrorProps {
304
  /** Error object */
305
  error: Error;
306
  /** Additional error context */
307
  context?: string;
308
  /** Retry handler */
309
  onRetry?: () => void;
310
}
311
```
312

313
**Usage Examples:**
314

315
```mdx
316
import { Canvas, Story, Meta } from "@storybook/addon-docs/blocks";
317
import { HeadersMdx, CodeOrSourceMdx } from "@storybook/addon-docs/blocks";
318
import * as ComponentStories from "./Component.stories";
319

320
<Meta of={ComponentStories} />
321

322
<HeadersMdx.h1>Component Documentation</HeadersMdx.h1>
323

324
<HeadersMdx.h2>Overview</HeadersMdx.h2>
325

326
This component provides enhanced functionality with the following features:
327

328
<Canvas of={ComponentStories.Default} />
329

330
<HeadersMdx.h2>API Reference</HeadersMdx.h2>
331

332
<CodeOrSourceMdx className="language-typescript">
333
{`
334
interface ComponentProps {
335
  title: string;
336
  variant: 'primary' | 'secondary';
337
  disabled?: boolean;
338
}
339
`}
340
</CodeOrSourceMdx>
341

342
<HeadersMdx.h2>Examples</HeadersMdx.h2>
343

344
<Story of={ComponentStories.Primary} />
345
<Story of={ComponentStories.Secondary} />
346
```