LLMDX

Transform Storybook MDX documentation into LLM-friendly Markdown and llms.txt files

LLMDX is a CLI tool that parses Storybook MDX documentation files and converts them into structured, navigable Markdown documentation optimized for Large Language Model consumption. It extracts component examples, code snippets, and prop documentation from your Storybook stories into static documentation that can be easily indexed and referenced by LLMs.

Features

• MDX to Markdown Conversion: Transforms Storybook MDX files into clean Markdown
• Code Snippet Extraction: Automatically extracts component usage examples from story files
• Smart Navigation: Generates llms.txt index files with hierarchical navigation
• Component Props Documentation: Converts interactive Controls into Markdown tables
• AST-Based Transformation: Uses unified/remark for reliable MDX parsing
• Babel-Powered Analysis: Extracts real code examples from TypeScript/JavaScript story files
• Zero Runtime Dependencies: Bundled with esbuild - single 8MB executable with everything included
• Fast Installation: No dependency tree to download at install time

Installation

npm install -g llmdx

Or use directly with npx:

npx llmdx -i ./docs -o ./llms-output

Zero Runtime Dependencies: LLMDX is bundled with all dependencies included. Installation requires no additional packages.

Usage

Basic Usage

llmdx -i <input-directory> -o <output-directory>

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --input <dir> | -i | MDX source directory | ./ | | --output <dir> | -o | Output directory | ./llms-output | | --project-name <name> | | Project name for root index | Directory name | | --format <type> | | Output format (currently only markdown) | markdown | | --include-meta | | Include metadata in output | false | | --verbose | -v | Enable verbose logging | false |

Examples

Convert current directory:

llmdx -i . -o ./docs-output --project-name "My Design System" -v

Process specific documentation folder:

llmdx -i ./storybook-docs -o ./llm-docs --verbose

How It Works

LLMDX processes your Storybook documentation through a multi-stage pipeline:

1. Scanner: Discovers all MDX files in your documentation directory
2. Parser: Parses MDX files using unified/remark into an Abstract Syntax Tree
3. Transformer: Converts Storybook-specific components into standard Markdown:
   • <Canvas> → Code blocks with extracted component usage
   • <Source> → Fenced code blocks
   • <Controls> → Markdown tables of props
   • <Title>, <Subtitle>, <Description> → Headings
4. Story Analyzer: Uses Babel to parse .stories files and extract real code examples
5. Generator: Writes Markdown files and creates navigation structure with llms.txt indexes

Input Format

LLMDX expects Storybook MDX files following standard conventions:

import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

<Title>Button Component</Title>

<Description>
  A customizable button component with multiple variants.
</Description>

<Canvas of={ButtonStories.Primary} />

<Controls of={ButtonStories} />

Output Structure

Generated documentation maintains your directory structure with added navigation:

llms-output/
├── llms.txt                    # Root index with full table of contents
├── components/
│   ├── llms.txt               # Components section index
│   ├── Button.md              # Converted Button documentation
│   └── Input.md               # Converted Input documentation
└── hooks/
    ├── llms.txt               # Hooks section index
    └── useTheme.md            # Converted hook documentation

Each llms.txt file includes:

• Links to all documentation in that directory
• Links to child directories
• Parent directory navigation
• Full table of contents at root level

Requirements

• Node.js 16 or higher
• Storybook documentation in MDX format
• Story files in TypeScript or JavaScript

Use Cases

• LLM Context: Provide your design system documentation to AI coding assistants
• Documentation Generation: Create static documentation from Storybook
• Knowledge Base: Build searchable, navigable documentation for your components
• CI/CD Integration: Automatically generate documentation on each deploy

Limitations

Storybook Doc Block Support

LLMDX focuses on static documentation generation, so some interactive Storybook components are not supported or have limited functionality:

| Doc Block | Support | Notes | |-----------|---------|-------| | <Title> | ✅ Full | Converted to Markdown heading (h1) | | <Subtitle> | ✅ Full | Converted to Markdown heading (h2) | | <Description> | ✅ Full | Converted to Markdown heading (h3) | | <Meta> | ✅ Partial | Removed from output (metadata only) | | <Canvas> | ✅ Full | Extracts code from story files or inline source | | <Source> | ✅ Full | Converts to fenced code blocks | | <Controls> | ⚠️ Limited | Static extraction only; runtime-only controls show placeholder | | <ArgTypes> | ⚠️ Limited | Runtime-only information shows placeholder table | | <Markdown> | ✅ Full | Preserved as-is | | <Stories> | ❌ None | Interactive component list not supported | | <Primary> | ❌ None | Story rendering not supported | | <Story> | ❌ None | Individual story embedding not supported | | <Docs> | ❌ None | Container component not needed | | <Unstyled> | ❌ None | Styling control not applicable | | <ColorPalette> | ❌ None | Design token display not supported | | <IconGallery> | ❌ None | Icon showcase not supported | | <Typeset> | ❌ None | Typography display not supported |

Known Constraints

1. Static Analysis Only

   • Only statically analyzable code is extracted
   • Dynamic imports and runtime computations are not supported
   • MDX expressions requiring execution are omitted

2. Story File Requirements

   • Story files must be in TypeScript or JavaScript (.ts, .tsx, .js, .jsx, .mjs, .cjs)
   • Stories must follow standard Storybook CSF (Component Story Format) conventions
   • Custom render functions must return JSX elements

3. Component Props Extraction

   • Props are extracted from argTypes and args in story meta
   • TypeScript type information is not automatically inferred
   • Complex prop types may not display correctly

4. Output Format

   • Only Markdown output is currently supported
   • Other formats (HTML, JSON) are not implemented

5. Navigation Structure

   • Directory structure must be hierarchical
   • Symlinks may cause unexpected behavior
   • Very deep directory nesting may impact performance

Building from Source

LLMDX uses esbuild to create a standalone executable:

# Clone the repository
git clone https://github.com/selenehyun/llmdx.git
cd llmdx

# Install development dependencies
npm install

# Build the bundle
npm run build

# Run the bundled CLI
./dist/index.cjs --help

Bundle Details:

• Bundle Size: 5.0MB minified (includes all dependencies)
• npm Package: 1.5MB compressed
• Format: CommonJS for maximum Node.js compatibility
• Dependencies Bundled: Babel (parser + traverse + generator), unified/remark, prettier, fast-glob, fs-extra
• Runtime Dependencies: Zero - everything is bundled
• Optimization: Minified with whitespace + syntax optimization
• Target: Node.js 16+

The build process:

1. Bundles all source files and dependencies with esbuild
2. Converts ESM to CommonJS
3. Includes import.meta.url shim for CJS compatibility
4. Adds executable shebang
5. Generates detailed bundle analysis

Testing

LLMDX uses Vitest for behavior-driven testing:

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Test Coverage:

• ✅ 90 test cases across 6 test suites
• ✅ Unit tests (64): utilities, parsers, transformers, doc block handlers
• ✅ Integration tests (26): real-world usage scenarios with actual story files
• ✅ BDD-style with Given-When-Then patterns
• ✅ Validates: Story file parsing, code extraction, props tables, navigation, standalone guides

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Security

For security concerns, please see our Security Policy.