# CKEditor 5 Classic with Mention Plugin

> Ready-to-use CKEditor 5 Classic build with integrated @mention functionality

[![npm version](https://img.shields.io/npm/v/ckeditor5-build-classic-mention)](https://www.npmjs.com/package/ckeditor5-build-classic-mention)
[![npm downloads](https://img.shields.io/npm/dw/ckeditor5-build-classic-mention)](https://www.npmjs.com/package/ckeditor5-build-classic-mention)
[![License: GPL-2.0](https://img.shields.io/badge/License-GPL%202.0-blue.svg)](https://opensource.org/licenses/GPL-2.0)

## Why This Package?

The official CKEditor 5 Classic build doesn't include the Mention plugin by default. This package provides a **pre-configured build** with mention/autocomplete functionality ready to use out of the box.

Perfect for applications that need:
- 🏷️ @mentions for users, tags, or custom entities
- ⚡ Quick autocomplete without complex setup
- 📦 Drop-in replacement for standard Classic build

## Installation

```bash
npm install ckeditor5-build-classic-mention
```

## Usage

### With Module Bundler (Webpack, Vite, Rollup, etc.)

```javascript
import ClassicEditor from 'ckeditor5-build-classic-mention';

ClassicEditor
  .create(document.querySelector('#editor'), {
    mention: {
      feeds: [{
        marker: '@',
        feed: ['@Alice', '@Bob', '@Charlie', '@David']
      }]
    }
  })
  .then(editor => {
    console.log('Editor ready!', editor);
  })
  .catch(error => {
    console.error('Error:', error);
  });
```

### Direct Browser Usage (No Bundler)

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>CKEditor 5 with Mention</title>
</head>
<body>
  <div id="editor">
    <p>Type @ to mention someone!</p>
  </div>

  <script src="./node_modules/ckeditor5-build-classic-mention/build/ckeditor.js"></script>
  <script>
    ClassicEditor
      .create(document.querySelector('#editor'), {
        mention: {
          feeds: [{
            marker: '@',
            feed: ['@John', '@Sarah', '@Mike']
          }]
        }
      })
      .then(editor => {
        console.log('Editor ready!', editor);
      })
      .catch(error => {
        console.error('Error:', error);
      });
  </script>
</body>
</html>
```

### Advanced Configuration

```javascript
ClassicEditor
  .create(document.querySelector('#editor'), {
    mention: {
      feeds: [
        {
          marker: '@',
          feed: getFeedItems,
          itemRenderer: customItemRenderer,
          minimumCharacters: 1
        },
        {
          marker: '#',
          feed: ['#javascript', '#react', '#vue', '#angular']
        }
      ]
    }
  });

// Dynamic feed from API
function getFeedItems(queryText) {
  return fetch(`/api/users?search=${queryText}`)
    .then(response => response.json())
    .then(users => users.map(user => ({
      id: `@${user.username}`,
      name: user.fullName
    })));
}

// Custom item renderer
function customItemRenderer(item) {
  const span = document.createElement('span');
  span.classList.add('mention-item');
  span.textContent = `${item.id}`;
  if (item.name) {
    span.textContent += ` (${item.name})`;
  }
  return span;
}
```

## Features Included

All standard CKEditor 5 Classic features:
- **Bold, Italic** and other text formatting
- Headings (H1-H6)
- Lists (Bullet, Numbered)
- Block quotes
- Links
- Images (upload, insert)
- Tables
- Media embed
- **+ Mention Plugin** ← The key addition!

## Configuration Options

### Mention Feed Options

| Option | Type | Description |
|--------|------|-------------|
| `marker` | `string` | Character that triggers mentions (e.g., `@`, `#`) |
| `feed` | `Array\|Function` | Static array or function returning items |
| `minimumCharacters` | `number` | Min characters before showing suggestions (default: 0) |
| `itemRenderer` | `Function` | Custom function to render suggestion items |

For complete options, see [CKEditor 5 Mention API](https://ckeditor.com/docs/ckeditor5/latest/api/module_mention_mention-MentionConfig.html).

## Important Notes

⚠️ **Maintenance Status**: CKEditor 5 predefined builds [have been deprecated](https://ckeditor.com/docs/ckeditor5/latest/updating/nim-migration/predefined-builds.html) by the CKEditor team. For new projects, consider using [CKEditor 5 from source](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/quick-start.html).

This package is maintained for:
- Legacy projects that rely on predefined builds
- Quick prototyping and testing
- Developers who need mention functionality without build setup

## Documentation & Resources

- **Mention Plugin**: [CKEditor 5 Mention Documentation](https://ckeditor.com/docs/ckeditor5/latest/features/mentions.html)
- **Configuration**: [CKEditor 5 Configuration Guide](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/configuration.html)
- **API Reference**: [ClassicEditor API](https://ckeditor.com/docs/ckeditor5/latest/api/module_editor-classic_classiceditor-ClassicEditor.html)
- **Examples**: [Official Mention Examples](https://ckeditor.com/docs/ckeditor5/latest/features/mentions.html#examples)

## Alternatives for New Projects

If you're starting a new project, consider these modern approaches:
- [CKEditor 5 from source](https://ckeditor.com/docs/ckeditor5/latest/installation/getting-started/quick-start.html) - Official recommended way
- [CKEditor 5 Online Builder](https://ckeditor.com/ckeditor-5/builder/) - Custom build creator with GUI
- [CKEditor 5 React/Vue/Angular integrations](https://ckeditor.com/docs/ckeditor5/latest/installation/frameworks/overview.html) - Framework-specific packages

## Troubleshooting

### Module resolution errors
If you encounter `Cannot find module 'ckeditor5-build-classic-mention'`:
1. Ensure the package is installed: `npm install ckeditor5-build-classic-mention`
2. Clear node_modules and reinstall: `rm -rf node_modules && npm install`

### Mention not appearing
1. Check that `marker` is configured correctly
2. Ensure `feed` array/function returns valid items
3. Verify `minimumCharacters` setting (default is 0)

## License

**GPL-2.0-or-later**

This package is licensed under the GNU General Public License Version 2 or later. For full details, see [LICENSE.md](LICENSE.md) or [CKEditor OSS License](https://ckeditor.com/legal/ckeditor-oss-license).

## Author & Contributing

Created and maintained by **Artem Bilenko** ([@Brilux](https://github.com/Brilux))

Issues and pull requests are welcome!

1. [Report bugs or request features](https://github.com/Brilux/ckeditor5-build-classic-mention/issues)
2. Submit pull requests
3. Star the repo if you find it useful ⭐

---

**Built with** ❤️ **for developers who need mention functionality without the build complexity**