storybook/zed-storybook/README.md

# Storybook Extension for Zed

This extension provides language support for the Storybook narrative DSL in [Zed](https://zed.dev).

## Features

- **Syntax highlighting** for all Storybook constructs
- **Markdown support** in prose blocks (inline markdown highlighting)
- **Document outline** showing characters, templates, relationships, etc.
- **Bracket matching** including special `---` prose block markers
- **Auto-indentation** with proper block handling
- **LSP integration** (when storybook-lsp is installed)
  - Real-time diagnostics
  - Hover documentation
  - Go-to-definition
  - Find references
  - Autocomplete
  - Document formatting

## Installation

### For Development (from this repository)

1. Build the extension (includes LSP server):
   ```bash
   cd zed-storybook
   ./build-extension.sh
   ```

2. Install the extension in Zed:
   - Open Zed
   - Run command: `zed: install dev extension` (Cmd+Shift+P)
   - Select the `zed-storybook` directory

3. Test:
   - Open a `.sb` file in Zed
   - The LSP should activate automatically
   - Try hovering over symbols to see rich information!

**Note:** The `build-extension.sh` script builds the LSP server and copies the binary into `bin/storybook-lsp` for local testing. The extension will automatically find it there.

### For Users (once published)

1. Open Zed
2. Open the command palette (Cmd+Shift+P)
3. Search for "Extensions: Install Extensions"
4. Search for "Storybook"
5. Click Install

## Usage

Once installed, the extension will automatically activate for `.sb` files.

### Syntax Highlighting

The extension provides rich syntax highlighting:
- **Keywords** (character, template, relationship, etc.) in purple
- **Strings** in yellow
- **Numbers** in light purple
- **Comments** in gray
- **Prose blocks** with Markdown syntax highlighting inside

### Prose Blocks with Markdown

Prose blocks support full Markdown syntax:

```storybook
character Alice {
    ---backstory
    Alice was a **curious** girl who loved:
    - Reading books
    - Asking questions
    - *Adventures*

    She often wondered about the world.
    ---
}
```

The markdown inside prose blocks will be highlighted appropriately.

### LSP Features

If you have `storybook-lsp` installed, you'll get:

- **Real-time validation** - Errors and warnings as you type
- **Hover information** - Documentation and type info on hover
- **Go to definition** - Jump to character/template definitions
- **Find references** - See where entities are used
- **Autocomplete** - Suggestions for field names, entity names, etc.

## Configuration

The extension uses these default settings:
- Tab size: 4 spaces
- Line comments: `//`
- Block comments: `/* */`
- Auto-close brackets: Yes

You can customize these in Zed's settings.

## Language Server

The extension looks for `storybook-lsp` in your PATH. To install it:

```bash
# From the storybook repository
cargo install --path storybook --bin storybook-lsp
```

## File Association

The extension automatically activates for files with the `.sb` extension.

## Troubleshooting

### Extension not loading

1. Check that the extension is in `~/.local/share/zed/extensions/installed/storybook`
2. Restart Zed
3. Check the Zed log for errors (Zed > View > Toggle Terminal > "Extensions" tab)

### LSP not working

1. Verify `storybook-lsp` is in your PATH:
   ```bash
   which storybook-lsp
   ```
2. Check Zed's LSP log for errors
3. Ensure you have the latest version installed

### Syntax highlighting issues

1. Ensure the file has the `.sb` extension
2. Try reloading the window (Cmd+Shift+P > "Reload Window")
3. Check that the grammar is correctly installed

## Development

To modify or contribute to this extension:

1. Clone the repository
2. Make your changes
3. Test with `cargo build`
4. Submit a pull request

## License

MIT