# Storybook Mdx Conversion

> Converts a standalone Markdown document to Storybook MDX by adding the imports and Meta tag and converting HTML comments to JSX comments, without altering any other content. Use when asked to convert a .md file to .mdx by hand, outside the automated contributor-docs pipeline.

- Skill: `adobe/storybook-mdx-conversion` (Agent Skill)
- Install (CLI): `npx get-skill add adobe/storybook-mdx-conversion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/adobe/storybook-mdx-conversion/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Adobe (https://skillmd.com/u/adobe)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/adobe/storybook-mdx-conversion

---


# Storybook MDX conversion

Converts markdown files to MDX format compatible with Storybook rendering.

> **Relationship to `generate-contributor-docs.mjs`:** the entire `CONTRIBUTOR-DOCS/` tree is already converted to Storybook `.mdx` automatically by `yarn generate:contributor-docs` (`gen2/packages/swc/.storybook/scripts/generate-contributor-docs.mjs`), which also runs before every `yarn storybook` / `yarn storybook:build`. That script's output is regenerated wholesale and not meant to be hand-edited. This skill is for everything that script doesn't cover: converting a standalone `.md` file to `.mdx` by hand (e.g. a one-off doc outside `CONTRIBUTOR-DOCS/`, or manual spot-conversion during authoring) using the same conventions.

## When to apply

- Converting a standalone `.md` file to `.mdx` by hand, outside the automated `generate-contributor-docs.mjs` pipeline
- Asked explicitly, for example "convert this doc to MDX"

## Conversion steps

### 1. File extension and imports

- Change file extension from `.md` to `.mdx`
- Add Storybook imports at the top of the file:

```typescript
import { Meta } from '@storybook/addon-docs/blocks';
```

- Add a blank line after imports

### 2. Meta tag

- Add a `<Meta title="Your Title Here" />` tag after the imports
- The title should match the document's main heading
- Add a blank line after the Meta tag

### 3. Convert HTML comments to JSX comments

Replace HTML comments with JSX-style comments:

**Before (Markdown):**

```markdown
<!-- Document title (editable) -->
```

**After (MDX):**

```mdx
{/* Document title (editable) */}
```

### 4. Preserve all other content

- Keep all markdown syntax as-is (headings, lists, links, code blocks, etc.)
- Keep all `<details>` and `<summary>` HTML elements unchanged
- Keep all list formatting and indentation unchanged
- Preserve all relative link paths (e.g., `./01_contributor-guides/README.md`)
- Do not modify any content within `<details>` blocks or navigation lists

## Example transformation

**Before (README.md):**

```markdown
<!-- Document title (editable) -->

# Contributor Documentation

<!-- Generated TOC - DO NOT EDIT -->

<details open>
<summary><strong>In this doc</strong></summary>

- [About Spectrum Web Components](#about-spectrum-web-components)

</details>

<!-- Document content (editable) -->

## About Spectrum Web Components

Content here...
```

**After (README.mdx):**

```mdx
import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Contributor Documentation" />
{/* Document title (editable) */}

# Contributor Documentation

{/* Generated TOC - DO NOT EDIT */}

<details open>
<summary><strong>In this doc</strong></summary>

- [About Spectrum Web Components](#about-spectrum-web-components)

</details>

{/* Document content (editable) */}

## About Spectrum Web Components

Content here...
```

## Critical rules

1. **Only add imports and Meta tag** - Do not modify any other structural elements
2. **Preserve exact formatting** - Keep all whitespace, indentation, and line breaks
3. **Convert ALL HTML comments** - Every `<!-- comment -->` must become `{/* comment */}`
4. **Keep markdown links** - Do not convert `.md` links to `.mdx` (Storybook may need the original paths)
5. **Blank lines matter** - Maintain blank line after imports and after Meta tag

## Common mistakes to avoid

❌ Don't change the document's heading structure
❌ Don't modify navigation lists or TOC content
❌ Don't convert markdown to JSX (keep lists as markdown lists)
❌ Don't add extra formatting or styling
❌ Don't forget to convert ALL HTML comments to JSX comments

