|
| 1 | +# storybook-llms-extractor |
| 2 | + |
| 3 | +A CLI tool that extracts documentation from Storybook builds and converts it to LLM-friendly formats, following the [llmstxt.org](https://llmstxt.org/) specification. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This tool processes Storybook production builds to generate comprehensive documentation in plain text format that's optimized for Large Language Models (LLMs). It extracts component documentation, props, examples, and MDX content to create structured documentation files. |
| 8 | + |
| 9 | +## Features |
| 10 | + |
| 11 | +- **Component Documentation**: Extracts props, descriptions, and type information from React components |
| 12 | +- **Story Examples**: Captures all story variations with source code |
| 13 | +- **MDX Support**: Processes MDX documentation pages and converts HTML to Markdown |
| 14 | +- **Subcomponents**: Handles complex components with subcomponents |
| 15 | +- **LLMs.txt Format**: Generates summary files following the llmstxt.org specification |
| 16 | +- **Static File Serving**: Uses Playwright routing instead of Express for better reliability |
| 17 | +- **Flexible Configuration**: Supports CLI arguments and config files |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +```bash |
| 22 | +npm install @fluentui/storybook-llms-extractor |
| 23 | +# or |
| 24 | +yarn add @fluentui/storybook-llms-extractor |
| 25 | +``` |
| 26 | + |
| 27 | +## Usage |
| 28 | + |
| 29 | +### Basic Usage |
| 30 | + |
| 31 | +Extract documentation from a Storybook build: |
| 32 | + |
| 33 | +```bash |
| 34 | +storybook-llms-extractor --distPath "storybook-static" --summaryBaseUrl "https://storybook.example.com" |
| 35 | +``` |
| 36 | + |
| 37 | +### CLI Options |
| 38 | + |
| 39 | +| Option | Type | Required | Default | Description | |
| 40 | +| ---------------------- | ------ | -------- | --------- | -------------------------------------------------- | |
| 41 | +| `--distPath` | string | Yes | - | Relative path to the Storybook distribution folder | |
| 42 | +| `--summaryBaseUrl` | string | No | `/` | Base URL for the Storybook docs | |
| 43 | +| `--summaryTitle` | string | No | `Summary` | Title for the summary file | |
| 44 | +| `--summaryDescription` | string | No | `""` | Description for the summary file | |
| 45 | +| `--refs` | array | No | `[]` | Array of composed Storybook refs | |
| 46 | + |
| 47 | +### Configuration File |
| 48 | + |
| 49 | +You can use a configuration file (e.g., `llms.config.js`) for complex setups: |
| 50 | + |
| 51 | +```javascript |
| 52 | +module.exports = { |
| 53 | + distPath: 'storybook-static', |
| 54 | + summaryBaseUrl: 'https://react.fluentui.dev', |
| 55 | + summaryTitle: 'Fluent UI React v9', |
| 56 | + summaryDescription: 'Fluent UI React components documentation', |
| 57 | + refs: [ |
| 58 | + { |
| 59 | + title: 'Charts v9', |
| 60 | + url: 'https://charts.fluentui.dev', |
| 61 | + }, |
| 62 | + ], |
| 63 | +}; |
| 64 | +``` |
| 65 | + |
| 66 | +Then run: |
| 67 | + |
| 68 | +```bash |
| 69 | +storybook-llms-extractor --config llms.config.js |
| 70 | +``` |
| 71 | + |
| 72 | +## Output Structure |
| 73 | + |
| 74 | +The tool generates the following files in your Storybook dist directory: |
| 75 | + |
| 76 | +``` |
| 77 | +storybook-static/ |
| 78 | +├── llms.txt # Main summary file (llmstxt.org format) |
| 79 | +└── llms/ |
| 80 | + ├── component-button.txt # Individual component docs |
| 81 | + ├── component-accordion.txt |
| 82 | + └── concepts-introduction.txt # MDX page docs |
| 83 | +``` |
| 84 | + |
| 85 | +### Summary File (`llms.txt`) |
| 86 | + |
| 87 | +The main summary file follows the [llmstxt.org](https://llmstxt.org/) specification: |
| 88 | + |
| 89 | +``` |
| 90 | +# Fluent UI React v9 |
| 91 | +
|
| 92 | +> **Note:** This is a summary overview using the LLMs.txt format... |
| 93 | +
|
| 94 | +- [Components/Button](https://example.com/llms/components-button.txt): A button component |
| 95 | +- [Components/Accordion](https://example.com/llms/components-accordion.txt): An accordion component |
| 96 | +``` |
| 97 | + |
| 98 | +### Individual Component Files |
| 99 | + |
| 100 | +Each component gets its own detailed documentation file: |
| 101 | + |
| 102 | +```` |
| 103 | +# Components/Button |
| 104 | +
|
| 105 | +A button triggers an action or event. |
| 106 | +
|
| 107 | +## Props |
| 108 | +
|
| 109 | +| Name | Type | Required | Default | Description | |
| 110 | +|------|------|----------|---------|-------------| |
| 111 | +| `appearance` | `"primary" | "secondary"` | No | `"secondary"` | Button appearance | |
| 112 | +
|
| 113 | +## Examples |
| 114 | +
|
| 115 | +### Primary Button |
| 116 | +```tsx |
| 117 | +<Button appearance="primary">Click me</Button> |
| 118 | +```` |
| 119 | + |
| 120 | +```` |
| 121 | +
|
| 122 | +## How It Works |
| 123 | +
|
| 124 | +1. **Static File Routing**: Uses Playwright to serve Storybook files without needing a web server |
| 125 | +2. **Story Extraction**: Accesses Storybook's internal story store to get all component metadata |
| 126 | +3. **Content Processing**: Converts HTML documentation to clean Markdown format |
| 127 | +4. **Documentation Generation**: Creates structured text files optimized for LLM consumption |
| 128 | +
|
| 129 | +## Integration Examples |
| 130 | +
|
| 131 | +### GitHub Actions |
| 132 | +
|
| 133 | +```yaml |
| 134 | +- name: Build Storybook |
| 135 | + run: npm run build-storybook |
| 136 | +
|
| 137 | +- name: Generate LLM Docs |
| 138 | + run: npx storybook-llms-extractor --distPath storybook-static --summaryBaseUrl ${{ env.DEPLOY_URL }} |
| 139 | +```` |
| 140 | + |
| 141 | +### With Composed Storybooks |
| 142 | + |
| 143 | +If you have multiple Storybook instances, you can reference them: |
| 144 | + |
| 145 | +```bash |
| 146 | +storybook-llms-extractor \ |
| 147 | + --distPath "storybook-static" \ |
| 148 | + --summaryBaseUrl "https://main.storybook.dev" \ |
| 149 | + --refs '{"title":"Charts","url":"https://charts.storybook.dev"}' \ |
| 150 | + --refs '{"title":"Icons","url":"https://icons.storybook.dev"}' |
| 151 | +``` |
| 152 | + |
| 153 | +## Development |
| 154 | + |
| 155 | +### Building |
| 156 | + |
| 157 | +```bash |
| 158 | +nx build storybook-llms-extractor |
| 159 | +``` |
| 160 | + |
| 161 | +### Testing |
| 162 | + |
| 163 | +```bash |
| 164 | +nx test storybook-llms-extractor |
| 165 | +``` |
| 166 | + |
| 167 | +### Local Development |
| 168 | + |
| 169 | +```bash |
| 170 | +# Link the package locally |
| 171 | +npm link |
| 172 | + |
| 173 | +# Use in another project |
| 174 | +cd /path/to/your/storybook |
| 175 | +npm link @fluentui/storybook-llms-extractor |
| 176 | +storybook-llms-extractor --distPath storybook-static |
| 177 | +``` |
| 178 | + |
| 179 | +## Requirements |
| 180 | + |
| 181 | +- Node.js 16+ |
| 182 | +- Storybook 7+ (supports both Storybook 7 and 8) |
| 183 | +- Built Storybook static files |
| 184 | + |
| 185 | +## Supported Formats |
| 186 | + |
| 187 | +- **Components**: React components with TypeScript props |
| 188 | +- **Stories**: CSF (Component Story Format) stories |
| 189 | +- **MDX**: Documentation pages written in MDX |
| 190 | +- **Subcomponents**: Complex component hierarchies |
| 191 | + |
| 192 | +## Troubleshooting |
| 193 | + |
| 194 | +### Common Issues |
| 195 | + |
| 196 | +**"Unable to find Storybook story store"** |
| 197 | + |
| 198 | +- Ensure your Storybook build is complete and contains the necessary metadata |
| 199 | +- Check that you're pointing to the correct `distPath` |
| 200 | + |
| 201 | +**HTML content not converting properly** |
| 202 | + |
| 203 | +- The tool handles most HTML-to-Markdown conversions automatically |
| 204 | +- Complex HTML structures might need manual review |
| 205 | + |
| 206 | +**Missing component props** |
| 207 | + |
| 208 | +- Ensure your components have proper TypeScript definitions |
| 209 | +- Check that Storybook's docgen is working correctly |
| 210 | + |
| 211 | +## Contributing |
| 212 | + |
| 213 | +This tool is part of the Fluent UI project. Please see the main repository for contribution guidelines. |
| 214 | + |
| 215 | +## License |
| 216 | + |
| 217 | +MIT - see the main Fluent UI repository for details. |
0 commit comments