mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
119 lines
3.9 KiB
Plaintext
119 lines
3.9 KiB
Plaintext
export const metadata = {
|
|
title: "Custom Emojis Extension",
|
|
description: "The Custom Emojis extension adds support for custom emojis in notes.",
|
|
}
|
|
|
|
# Custom Emojis Extension
|
|
|
|
The Custom Emojis extension adds support for adding personalized emojis to federated data. {{ className: 'lead' }}
|
|
|
|
## Structure Definition
|
|
|
|
<Row>
|
|
<Col>
|
|
<Properties name="CustomEmoji">
|
|
<Property name="name" type="string" required={true}>
|
|
Emoji name, surrounded by identification characters (for example, colons: `:happy_face:`).
|
|
|
|
Name must match the regex `^[a-zA-Z0-9_-]+$`.
|
|
|
|
Identification characters must not match the name regex (must not be alphanumeric/underscore/hyphen). There may only be two identification characters, one at the beginning and one at the end.
|
|
</Property>
|
|
<Property name="content" type="ContentFormat" required={true} typeLink="/structures/content-format">
|
|
Emoji content. Must be an image format (`image/*`).
|
|
</Property>
|
|
</Properties>
|
|
</Col>
|
|
|
|
<Col sticky>
|
|
|
|
```jsonc {{ 'title': 'Example Emoji' }}
|
|
{
|
|
"name": ":happy_face:",
|
|
"content": {
|
|
"image/webp": {
|
|
"content": "https://cdn.example.com/emojis/happy_face.webp",
|
|
"remote": true,
|
|
"description": "A happy emoji smiling.",
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</Col>
|
|
</Row>
|
|
|
|
## Rendering
|
|
|
|
To render custom emojis, clients **should** perform the following steps:
|
|
1. Find all instances of custom emoji names in the text content.
|
|
2. Replace the custom emoji names with the corresponding emoji images in text.
|
|
|
|
If custom emojis are not supported, clients **should** leave the custom emoji names as-is. Images **should** have any associated `alt` text for accessibility.
|
|
|
|
```html {{ 'title': 'Example HTML/CSS' }}
|
|
<style>
|
|
img.emoji {
|
|
display: inline;
|
|
height: 1em;
|
|
}
|
|
</style>
|
|
|
|
<p>
|
|
Hello, world! <img src="https://cdn.example.com/emojis/happy_face.webp" alt="A happy emoji smiling." class="emoji" />!
|
|
</p>
|
|
```
|
|
|
|
Emojis **should** be displayed at a fixed height (such as `1em`), but their width **should** be allowed to be flexible.
|
|
|
|
## Extension Definition
|
|
|
|
Custom Emojis can be added to any entity with text content. The extension ID is `pub.versia:custom_emojis`.
|
|
|
|
<Row>
|
|
<Col>
|
|
<Properties name="CustomEmojisExtension">
|
|
<Property name="emojis" type="CustomEmoji[]" required={true} typeLink="/extensions/custom-emoji#structure-definition">
|
|
[Custom emojis](/extensions/custom-emoji#structure-definition) to be added to the note.
|
|
</Property>
|
|
</Properties>
|
|
</Col>
|
|
|
|
<Col sticky>
|
|
|
|
```jsonc {{ 'title': 'Example Usage' }}
|
|
{
|
|
"id": "456df8ed-daf1-4062-abab-491071c7b8dd",
|
|
"type": "Note",
|
|
"uri": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd",
|
|
"created_at": "2024-04-09T01:38:51.743Z",
|
|
"collections": {
|
|
"replies": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd/replies",
|
|
"quotes": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd/quotes"
|
|
},
|
|
"content": {
|
|
"text/plain": {
|
|
"content": "Hello, world :happy_face:!"
|
|
}
|
|
},
|
|
"extensions": { // [!code focus:16]
|
|
"pub.versia:custom_emojis": {
|
|
"emojis": [
|
|
{
|
|
"name": ":happy_face:",
|
|
"content": {
|
|
"image/webp": {
|
|
"content": "https://cdn.example.com/emojis/happy_face.webp",
|
|
"remote": true,
|
|
"description": "A happy emoji smiling.",
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</Col>
|
|
</Row> |