spc-pleroma/docs/configuration/custom_emoji.md

# Custom Emoji

Before you add your own custom emoji, check if they are available in an existing pack.
See `Mix.Tasks.Pleroma.Emoji` for information about emoji packs.

To add custom emoji:

* Create the `STATIC-DIR/emoji/` directory if it doesn't exist
  (`STATIC-DIR` is configurable, `instance/static/` by default)
* Create a directory with whatever name you want (custom is a good name to show the purpose of it).
  This will create a local emoji pack.
* Put your `.png` emoji files in that directory. In case of conflicts, you can create an `emoji.txt`
  file in that directory and specify a custom shortcode using the following format:
  `shortcode, file-path, tag1, tag2, etc`. One emoji per line. Note that if you do so,
  you'll have to list all other emojis in the pack too.
* Either restart pleroma or connect to the iex session pleroma's running and
  run `Pleroma.Emoji.reload/0` in it.

Example:

image files (in `instance/static/emoji/custom`): `happy.png` and `sad.png`

content of `emoji.txt`:
```
happy, /emoji/custom/happy.png, Tag1,Tag2
sad, /emoji/custom/sad.png, Tag1
foo, /emoji/custom/foo.png
```

The files should be PNG (APNG is okay with `.png` for `image/png` Content-type) and under 50kb for compatibility with mastodon.

Default file extentions and locations for emojis are set in `config.exs`. To use different locations or file-extentions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extentions:
```elixir
config :pleroma, :emoji, shortcode_globs: ["/emoji/custom/**/*.png", "/emoji/custom/**/*.gif"]
```

## Emoji tags (groups)

Default tags are set in `config.exs`. To set your own tags, copy the structure to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it.
```elixir
config :pleroma, :emoji,
  shortcode_globs: ["/emoji/custom/**/*.png"],
  groups: [
    Finmoji: "/finmoji/128px/*-128.png",
    Custom: ["/emoji/*.png", "/emoji/custom/*.png"]
  ]
```

Order of the `groups` matters, so to override default tags just put your group on top of the list. E.g:
```elixir
config :pleroma, :emoji,
  shortcode_globs: ["/emoji/custom/**/*.png"],
  groups: [
    "Finmoji special": "/finmoji/128px/a_trusted_friend-128.png", # special file
    "Cirno": "/emoji/custom/cirno*.png", # png files in /emoji/custom/ which start with `cirno`
    "Special group": "/emoji/custom/special_folder/*.png", # png files in /emoji/custom/special_folder/
    "Another group": "/emoji/custom/special_folder/*/.png", # png files in /emoji/custom/special_folder/ subfolders
    Finmoji: "/finmoji/128px/*-128.png",
    Custom: ["/emoji/*.png", "/emoji/custom/*.png"]
  ]
```

Priority of tags assigns in emoji.txt and custom.txt:

`tag in file > special group setting in config.exs > default setting in config.exs`

Priority for globs:

`special group setting in config.exs > default setting in config.exs`
Move out of Gitlab Wiki I understand that this change is quite unreadable and hard to review, sorry for forgetting to do atomic commits. This patch does not change too much content wise, it just * Gets everything from gitlab wiki * Removes some specific gitlab hacks * Formats all documentation file names to be in snake case so they look the same way as our code does 2019-03-28 16:46:30 +00:00			`# Custom Emoji`
Fix headers and add !929 docs to extras [ci skip] 2019-03-15 09:58:15 +00:00
Document the pleroma.emoji task 2019-04-20 07:57:31 +00:00			`Before you add your own custom emoji, check if they are available in an existing pack.`
			See `Mix.Tasks.Pleroma.Emoji` for information about emoji packs.

robots.txt Add default robots.txt that allows bots access to all paths. Add mix task to generate robots.txt taht allows bots access to no paths. Document custom emojis, MRF and static_dir static_dir documentation includes docs for the robots.txt Mix task. 2019-01-20 01:44:00 +00:00			`To add custom emoji:`
MkDocs does not like if a paragraph doesn't have a newline after it 2019-10-03 08:02:07 +00:00
Document the pleroma.emoji task 2019-04-20 07:57:31 +00:00			* Create the `STATIC-DIR/emoji/` directory if it doesn't exist
			(`STATIC-DIR` is configurable, `instance/static/` by default)
			`* Create a directory with whatever name you want (custom is a good name to show the purpose of it).`
			`This will create a local emoji pack.`
			* Put your `.png` emoji files in that directory. In case of conflicts, you can create an `emoji.txt`
			`file in that directory and specify a custom shortcode using the following format:`
			`shortcode, file-path, tag1, tag2, etc`. One emoji per line. Note that if you do so,
			`you'll have to list all other emojis in the pack too.`
			`* Either restart pleroma or connect to the iex session pleroma's running and`
			run `Pleroma.Emoji.reload/0` in it.
robots.txt Add default robots.txt that allows bots access to all paths. Add mix task to generate robots.txt taht allows bots access to no paths. Document custom emojis, MRF and static_dir static_dir documentation includes docs for the robots.txt Mix task. 2019-01-20 01:44:00 +00:00
			`Example:`

Document the pleroma.emoji task 2019-04-20 07:57:31 +00:00			image files (in `instance/static/emoji/custom`): `happy.png` and `sad.png`
robots.txt Add default robots.txt that allows bots access to all paths. Add mix task to generate robots.txt taht allows bots access to no paths. Document custom emojis, MRF and static_dir static_dir documentation includes docs for the robots.txt Mix task. 2019-01-20 01:44:00 +00:00
Document the pleroma.emoji task 2019-04-20 07:57:31 +00:00			content of `emoji.txt`:
robots.txt Add default robots.txt that allows bots access to all paths. Add mix task to generate robots.txt taht allows bots access to no paths. Document custom emojis, MRF and static_dir static_dir documentation includes docs for the robots.txt Mix task. 2019-01-20 01:44:00 +00:00			```
Adding tag to emoji ets table changes in apis 2019-04-01 10:17:57 +00:00			`happy, /emoji/custom/happy.png, Tag1,Tag2`
			`sad, /emoji/custom/sad.png, Tag1`
			`foo, /emoji/custom/foo.png`
robots.txt Add default robots.txt that allows bots access to all paths. Add mix task to generate robots.txt taht allows bots access to no paths. Document custom emojis, MRF and static_dir static_dir documentation includes docs for the robots.txt Mix task. 2019-01-20 01:44:00 +00:00			```

			The files should be PNG (APNG is okay with `.png` for `image/png` Content-type) and under 50kb for compatibility with mastodon.
Adding tag to emoji ets table changes in apis 2019-04-01 10:17:57 +00:00
Add shortcode_globs setting to documentation 2019-04-22 09:17:53 +00:00			Default file extentions and locations for emojis are set in `config.exs`. To use different locations or file-extentions, add the `shortcode_globs` to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it. Note that not all fediverse-software will show emojis with other file extentions:
			```elixir
			`config :pleroma, :emoji, shortcode_globs: ["/emoji/custom/*/.png", "/emoji/custom/*/.gif"]`
			```

second level of headertext change in doc 2019-04-02 13:35:41 +00:00			`## Emoji tags (groups)`
Adding tag to emoji ets table changes in apis 2019-04-01 10:17:57 +00:00
Custom Emoji docs: Make it clear that config.exs is not for lewd. 2019-04-15 13:51:17 +00:00			Default tags are set in `config.exs`. To set your own tags, copy the structure to your secrets file (`prod.secret.exs` or `dev.secret.exs`) and edit it.
syntax highlighting 2019-04-02 13:32:37 +00:00			```elixir
updating custom_emoji docs 2019-04-02 08:57:57 +00:00			`config :pleroma, :emoji,`
			`shortcode_globs: ["/emoji/custom/*/.png"],`
			`groups: [`
			`Finmoji: "/finmoji/128px/*-128.png",`
			`Custom: ["/emoji/.png", "/emoji/custom/.png"]`
			`]`
			```
Adding tag to emoji ets table changes in apis 2019-04-01 10:17:57 +00:00
little changes and typos 2019-04-02 09:13:34 +00:00			Order of the `groups` matters, so to override default tags just put your group on top of the list. E.g:
syntax highlighting 2019-04-02 13:32:37 +00:00			```elixir
Adding tag to emoji ets table changes in apis 2019-04-01 10:17:57 +00:00			`config :pleroma, :emoji,`
			`shortcode_globs: ["/emoji/custom/*/.png"],`
updating custom_emoji docs 2019-04-02 08:57:57 +00:00			`groups: [`
			`"Finmoji special": "/finmoji/128px/a_trusted_friend-128.png", # special file`
			"Cirno": "/emoji/custom/cirno*.png", # png files in /emoji/custom/ which start with `cirno`
			`"Special group": "/emoji/custom/special_folder/*.png", # png files in /emoji/custom/special_folder/`
			`"Another group": "/emoji/custom/special_folder/*/.png", # png files in /emoji/custom/special_folder/ subfolders`
			`Finmoji: "/finmoji/128px/*-128.png",`
			`Custom: ["/emoji/.png", "/emoji/custom/.png"]`
			`]`
Adding tag to emoji ets table changes in apis 2019-04-01 10:17:57 +00:00			```
updating custom_emoji docs 2019-04-02 08:57:57 +00:00
little changes and typos 2019-04-02 09:13:34 +00:00			`Priority of tags assigns in emoji.txt and custom.txt:`
updating custom_emoji docs 2019-04-02 08:57:57 +00:00
			`tag in file > special group setting in config.exs > default setting in config.exs`

			`Priority for globs:`

			`special group setting in config.exs > default setting in config.exs`