Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve emoji's docs. #17968

Open
wants to merge 2 commits into
base: stable
Choose a base branch
from
+21 −7
Open

Improve emoji's docs. #17968

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1240a48
Improve emoji's docs.
Witoso Feb 20, 2025
d586084
Docs: a review. [short flow]
godai78 Feb 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 17 additions & 5 deletions packages/ckeditor5-emoji/docs/features/emoji.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ The feature can be configured via the {@link module:emoji/emojiconfig~EmojiConfi
.catch( /* ... */ );
```

* `version` – the emoji database version.
* `version` – the emoji database version. By default, version 16 is used. This option is ignored if the `definitionsUrl` setting is provided.

```js
ClassicEditor
Expand All @@ -134,11 +134,23 @@ The feature can be configured via the {@link module:emoji/emojiconfig~EmojiConfi
.catch( /* ... */ );
```

<info-box info>
The emoji feature uses the `:` marker that opens a panel with a table of selectable emojis. If you are using {@link features/mentions mentions} or {@link features/merge-fields merge fields} features, they can also show UI panels by pressing a pre-configured key, and it may conflict with the emoji feature. In such a case, the {@link module:emoji/emojimention~EmojiMention} plugin will not integrate the autocompletion mechanism.
### Emoji source

To prevent conflicts, make sure that {@link module:mention/mentionconfig~MentionFeed#marker mention's `marker`} and {@link module:merge-fields/mergefieldsconfig~MergeFieldsConfig#prefix merge field's `prefix`} configuration options are defined differently than `:`.
</info-box>
The database of English emoji is loaded by default from our CDN. Make sure that your {@link getting-started/setup/csp CSP rules} are correctly set up.

If you do not want to use our distribution and prefer to self-host emoji, you can use the {@link module:emoji/emojiconfig~EmojiConfig#definitionsUrl `definitionsUrl`} option. You can download the data directly from the package mentioned above or from our CDN, and place it under a static assets URL, for example:

1. Download the latest emoji database from [https://cdn.ckeditor.com/ckeditor5/data/emoji/16/en.json](https://cdn.ckeditor.com/ckeditor5/data/emoji/16/en.json), or download version 15 for older Unicode versions.
2. Place the downloaded file in your application's assets folder, for example `public/emoji/en.json`. The specific location may vary depending on your framework and setup.
3. Update the configuration option `definitionsUrl` to point to the URL of your assets, for example: `https://example.com/emoji/en.json`.

You can prepare your own database with a different emoji set, but it must have an identical structure as ours. Otherwise, the emoji feature will not work.

### Marker conflicts

The emoji feature uses the `:` marker that opens a panel with a table of selectable emojis. If you are using the {@link features/mentions mentions} or {@link features/merge-fields merge fields} features, they can also show UI panels by pressing a pre-configured key, and it may conflict with the emoji feature. In such a case, the {@link module:emoji/emojimention~EmojiMention} plugin will not integrate the autocompletion mechanism.

To prevent conflicts, make sure that the {@link module:mention/mentionconfig~MentionFeed#marker mention's `marker`} and {@link module:merge-fields/mergefieldsconfig~MergeFieldsConfig#prefix merge field's `prefix`} configuration options are not defined as `:`.

## Related features

Expand Down
6 changes: 4 additions & 2 deletions packages/ckeditor5-emoji/src/emojirepository.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,8 +270,10 @@ export default class EmojiRepository extends Plugin {
}

/**
* By default, the Emoji plugin fetches the emoji repository from CKEditor 5 CDN. To avoid this,
* you can use the {@link module:emoji/emojiconfig~EmojiConfig#definitionsUrl `emoji.definitionsUrl`}
* It was detected that your installation uses a commercial self-hosted license key,
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pomek is this factually correct?

* and the default {@glink features/emoji#emoji-source CKEditor CDN for Emoji plugin data}.
*
* To avoid this, you can use the {@link module:emoji/emojiconfig~EmojiConfig#definitionsUrl `emoji.definitionsUrl`}
* configuration option to provide a URL to your own emoji repository.
*
* If you only want to suppress this warning, set this configuration option to `cdn`.
Expand Down