0
# @storybook/addon-mdx-gfm
1

2
A migration assistant addon that provides GitHub Flavored Markdown (GFM) support for Storybook documentation by automatically configuring the MDX compiler to include the remark-gfm plugin.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-mdx-gfm
7
- **Package Type**: npm (Storybook addon)
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/addon-mdx-gfm`
10

11
## Core Imports
12

13
```typescript
14
import { mdxLoaderOptions } from "@storybook/addon-mdx-gfm";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { mdxLoaderOptions } = require("@storybook/addon-mdx-gfm");
21
```
22

23
Preset import (for Storybook configuration):
24

25
```javascript
26
// .storybook/main.js
27
module.exports = {
28
  addons: ["@storybook/addon-mdx-gfm"]
29
};
30
```
31

32
Note: The addon uses a preset.js file that re-exports the main distribution file, enabling Storybook's addon system to automatically discover and integrate the MDX loader configuration.
33

34
## Basic Usage
35

36
This addon is designed to be used automatically by Storybook when added to the addons list. It integrates with Storybook's MDX compilation pipeline through the preset system, requiring no manual configuration or function calls.
37

38
```javascript
39
// .storybook/main.js
40
module.exports = {
41
  addons: [
42
    "@storybook/addon-docs",
43
    "@storybook/addon-mdx-gfm"  // Add this addon
44
  ]
45
};
46
```
47

48
When registered, Storybook automatically calls the addon's `mdxLoaderOptions` function during MDX compilation to configure the remark-gfm plugin. This enables GitHub Flavored Markdown features in your Storybook documentation, including:
49
- Tables
50
- Strikethrough text
51
- Task lists
52
- Autolinks
53
- And other GFM features
54

55
## Capabilities
56

57
### MDX Loader Configuration
58

59
Configures MDX loader options to include the remark-gfm plugin for GitHub Flavored Markdown support. This function is called internally by Storybook's build system when processing MDX files.
60

61
```typescript { .api }
62
/**
63
 * Configures MDX loader options to include remark-gfm plugin
64
 * @param config - The existing MDX configuration object passed by Storybook's build system
65
 * @returns Promise resolving to the modified configuration with remark-gfm plugin added
66
 */
67
function mdxLoaderOptions(config: MdxLoaderConfig): Promise<MdxLoaderConfig>;
68

69
interface MdxLoaderConfig {
70
  mdxCompileOptions: {
71
    remarkPlugins?: any[];
72
    [key: string]: any;
73
  };
74
  [key: string]: any;
75
}
76
```
77

78
**Implementation Details:**
79
- Called automatically by Storybook during MDX compilation process
80
- Initializes `config.mdxCompileOptions.remarkPlugins` as empty array if not already set
81
- Adds the `remark-gfm` plugin to the remarkPlugins array
82
- Returns the modified configuration object
83
- Executes deprecation warning on module import
84

85
**Note:** This function is not intended for direct use - it's automatically invoked by Storybook's addon system when the addon is registered in your Storybook configuration.
86

87
## Types
88

89
```typescript { .api }
90
// Configuration interface for MDX loader
91
interface MdxLoaderConfig {
92
  mdxCompileOptions: {
93
    remarkPlugins?: any[];
94
    [key: string]: any;
95
  };
96
  [key: string]: any;
97
}
98
```
99

100
## Important Notes
101

102
**Deprecation Warning**: This addon is intended as a migration assistant for Storybook 8.0 and will likely be removed in a future version. Upon import, it displays a deprecation warning directing users to configure their MDX setup properly.
103

104
**Migration Path**: Users should follow the documentation at https://storybook.js.org/docs/writing-docs/mdx#markdown-tables-arent-rendering-correctly to properly configure MDX with remark-gfm instead of relying on this addon.
105

106
**Dependencies**: 
107
- `remark-gfm` (^4.0.0): The actual GitHub Flavored Markdown plugin
108
- `ts-dedent` (^2.0.0): Used for formatting the deprecation warning message
109

110
## Error Handling
111

112
This addon does not throw errors under normal operation. If the MDX configuration object is malformed, standard JavaScript property access errors may occur.