0
# Markdown Components
1

2
Custom markdown components for rich text documentation display within story info panels, providing styled rendering of markdown content with full customization support.
3

4
## Capabilities
5

6
### Heading Components
7

8
Styled heading components for markdown text hierarchy and structure.
9

10
```javascript { .api }
11
/**
12
 * Heading level 1 component
13
 * @param {Object} props - Heading component props
14
 */
15
function H1(props);
16

17
/**
18
 * Heading level 2 component  
19
 * @param {Object} props - Heading component props
20
 */
21
function H2(props);
22

23
/**
24
 * Heading level 3 component
25
 * @param {Object} props - Heading component props
26
 */
27
function H3(props);
28

29
/**
30
 * Heading level 4 component
31
 * @param {Object} props - Heading component props
32
 */
33
function H4(props);
34

35
/**
36
 * Heading level 5 component
37
 * @param {Object} props - Heading component props
38
 */
39
function H5(props);
40

41
/**
42
 * Heading level 6 component
43
 * @param {Object} props - Heading component props
44
 */
45
function H6(props);
46

47
interface HeadingProps {
48
  /** Optional ID attribute for the heading */
49
  id?: string;
50
  /** Heading content */
51
  children?: React.ReactNode;
52
}
53
```
54

55
**Usage in Markdown:**
56

57
```markdown
58
# This renders as H1
59
## This renders as H2
60
### This renders as H3
61
#### This renders as H4
62
##### This renders as H5
63
###### This renders as H6
64
```
65

66
### Text Components
67

68
Basic text and formatting components for paragraph content and inline elements.
69

70
```javascript { .api }
71
/**
72
 * Paragraph component for text blocks
73
 * @param {Object} props - Paragraph component props
74
 */
75
function P(props);
76

77
/**
78
 * Anchor link component with external link styling
79
 * @param {Object} props - Anchor component props
80
 */
81
function A(props);
82

83
/**
84
 * List item component
85
 * @param {Object} props - List item component props
86
 */
87
function LI(props);
88

89
/**
90
 * Unordered list component
91
 * @param {Object} props - List component props
92
 */
93
function UL(props);
94

95
interface TextComponentProps {
96
  /** Component content */
97
  children?: React.ReactNode;
98
}
99

100
interface AnchorProps extends TextComponentProps {
101
  /** Required href attribute for the link */
102
  href: string;
103
}
104
```
105

106
**Usage in Markdown:**
107

108
```markdown
109
This is a paragraph that renders as P component.
110

111
[This is a link](https://example.com) that renders as A component.
112

113
- This list item renders as LI
114
- Inside a UL component
115
```
116

117
### Code Components
118

119
Specialized components for displaying code blocks and inline code with syntax highlighting.
120

121
```javascript { .api }
122
/**
123
 * Code component with syntax highlighting using Storybook's SyntaxHighlighter
124
 * @param {Object} props - Code component props
125
 */
126
function Code(props);
127

128
interface CodeProps {
129
  /** Code content to display */
130
  code: string;
131
  /** Programming language for syntax highlighting */
132
  language?: string;
133
}
134

135
/**
136
 * Preformatted text block component with copy functionality
137
 * @param {Object} props - Pre component props
138
 */
139
function Pre(props);
140

141
interface PreProps {
142
  /** Content to display in pre block */
143
  children?: React.ReactNode;
144
  /** Theme object with pre styling */
145
  theme?: {
146
    pre?: Object;
147
  };
148
}
149

150
/**
151
 * Blockquote component for quoted text with special styling
152
 * @param {Object} props - Blockquote component props
153
 */
154
function Blockquote(props);
155

156
interface BlockquoteProps {
157
  /** Quote content */
158
  children?: React.ReactNode;
159
}
160
```
161

162
**Usage in Markdown:**
163

164
```markdown
165
Here is some `inline code` that uses the Code component.
166

167
```javascript
168
// This code block uses the Code component with language="javascript"
169
function example() {
170
  return "formatted code";
171
}
172
\```
173
```
174

175
### Default Component Mapping  
176

177
Standard mapping of markdown elements to React components used by the marksy renderer.
178

179
```javascript { .api }
180
const defaultComponents = {
181
  h1: H1,
182
  h2: H2, 
183
  h3: H3,
184
  h4: H4,
185
  h5: H5,
186
  h6: H6,
187
  code: Code,
188
  p: P,
189
  a: A,
190
  li: LI,
191
  ul: UL,
192
  blockquote: Blockquote,
193
};
194
```
195

196
## Customization
197

198
### Custom Component Override
199

200
Replace default markdown components with custom implementations:
201

202
```javascript
203
import { withInfo } from "@storybook/addon-info";
204

205
// Custom heading component
206
const CustomH1 = ({ children }) => (
207
  <h1 style={{ color: 'red', fontSize: '2rem' }}>
208
    🎯 {children}
209
  </h1>
210
);
211

212
// Custom code component
213
const CustomCode = ({ children, language }) => (
214
  <pre style={{ backgroundColor: '#f5f5f5', padding: '1rem' }}>
215
    <code className={`language-${language}`}>
216
      {children}
217
    </code>
218
  </pre>
219
);
220

221
// Use custom components
222
addDecorator(
223
  withInfo({
224
    components: {
225
      h1: CustomH1,
226
      code: CustomCode,
227
    },
228
  })
229
);
230
```
231

232
### Per-Story Component Override
233

234
```javascript
235
export const StoryWithCustomMarkdown = () => <Component />;
236
StoryWithCustomMarkdown.story = {
237
  parameters: {
238
    info: {
239
      text: `
240
        # Custom Styled Heading
241
        
242
        This story uses \`custom components\` for rendering.
243
      `,
244
      components: {
245
        h1: ({ children }) => (
246
          <h1 style={{ borderBottom: '2px solid blue' }}>
247
            {children}
248
          </h1>
249
        ),
250
        code: ({ children }) => (
251
          <code style={{ backgroundColor: 'yellow' }}>
252
            {children}
253
          </code>
254
        ),
255
      },
256
    },
257
  },
258
};
259
```
260

261
## Markdown Processing
262

263
### Marksy Integration
264

265
The addon uses marksy for converting markdown to React components:
266

267
```javascript { .api }
268
// Internal marksy configuration
269
const marksy = require('marksy')({
270
  createElement: React.createElement,
271
  elements: customComponents,
272
});
273

274
// Processes markdown text into React elements
275
const processedContent = marksy(markdownText).tree;
276
```
277

278
### Supported Markdown Features
279

280
The addon supports standard CommonMark markdown features:
281

282
**Headers:**
283
```markdown
284
# H1 Header
285
## H2 Header  
286
### H3 Header
287
```
288

289
**Text Formatting:**
290
```markdown
291
**Bold text**
292
*Italic text*
293
`Inline code`
294
```
295

296
**Lists:**
297
```markdown
298
- Unordered list item
299
- Another item
300

301
1. Ordered list item
302
2. Another ordered item
303
```
304

305
**Links:**
306
```markdown
307
[Link text](https://example.com)
308
```
309

310
**Code Blocks:**
311
````markdown
312
```javascript
313
function example() {
314
  return "code block";
315
}
316
```
317
````
318
319
### Advanced Markdown Usage
320

321
**Multi-line Documentation:**
322

323
```javascript
324
export const DocumentedComponent = () => <Component />;
325
DocumentedComponent.story = {
326
  parameters: {
327
    info: {
328
      text: `
329
        # Component Documentation
330
        
331
        This component provides advanced functionality for data processing.
332
        
333
        ## Usage Examples
334
        
335
        Basic usage:
336
        \`\`\`javascript
337
        <Component data={[1, 2, 3]} />
338
        \`\`\`
339
        
340
        With options:
341
        \`\`\`javascript
342
        <Component 
343
          data={complexData}
344
          options={{ format: 'json' }}
345
          onComplete={handleComplete}
346
        />
347
        \`\`\`
348
        
349
        ## Important Notes
350
        
351
        - Always provide the \`data\` prop
352
        - The \`onComplete\` callback is optional
353
        - Use \`options.format\` to control output format
354
      `,
355
    },
356
  },
357
};
358
```
359

360
**Dynamic Content:**
361

362
```javascript
363
// React elements can be used directly instead of markdown strings
364
const dynamicInfo = (
365
  <div>
366
    <h2>Dynamic Documentation</h2>
367
    <p>This content is generated dynamically.</p>
368
    <button onClick={() => alert('Interactive!')}>
369
      Click me
370
    </button>
371
  </div>
372
);
373

374
export const DynamicExample = () => <Component />;
375
DynamicExample.story = {
376
  parameters: {
377
    info: dynamicInfo,
378
  },
379
};
380
```
381

382
## Legacy Support
383

384
### Deprecated marksyConf Option
385

386
```javascript { .api }
387
// DEPRECATED: Use 'components' instead
388
interface DeprecatedOptions {
389
  /** @deprecated Use 'components' instead */
390
  marksyConf?: { [key: string]: React.ComponentType };
391
}
392
```
393

394
**Migration:**
395

396
```javascript
397
// OLD (deprecated)
398
withInfo({
399
  marksyConf: {
400
    h1: CustomH1,
401
    code: CustomCode,
402
  },
403
});
404

405
// NEW (recommended)
406
withInfo({
407
  components: {
408
    h1: CustomH1, 
409
    code: CustomCode,
410
  },
411
});
412
```