Document the pleroma.emoji task

This commit is contained in:
Ekaterina Vaartis 2019-04-20 10:57:31 +03:00
parent 1e311d6662
commit 31cff7dbca
2 changed files with 58 additions and 6 deletions

View file

@ -1,15 +1,25 @@
# 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:
* Add the image file(s) to `priv/static/emoji/custom`
* In case of conflicts: add the desired shortcode with the path to `config/custom_emoji.txt`, comma-separated and one per line
* Force recompilation (``mix clean && mix compile``)
* 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 `/priv/static/emoji/custom`): `happy.png` and `sad.png`
image files (in `instance/static/emoji/custom`): `happy.png` and `sad.png`
content of `config/custom_emoji.txt`:
content of `emoji.txt`:
```
happy, /emoji/custom/happy.png, Tag1,Tag2
sad, /emoji/custom/sad.png, Tag1

View file

@ -5,8 +5,50 @@
defmodule Mix.Tasks.Pleroma.Emoji do
use Mix.Task
@shortdoc "Manages Pleroma instance"
@shortdoc "Manages emoji packs"
@moduledoc """
Manages emoji packs
## ls-packs
mix pleroma.emoji ls-packs [OPTION...]
Lists the emoji packs and metadata specified in the manifest.
### Options
- `-m, --manifest PATH/URL` - path to a custom manifest, it can either be an URL
starting with `http`, in that case the manifest will be fetched from that address,
or a local path
## get-packs
mix pleroma.emoji get-packs [OPTION...] PACKS
Fetches, verifies and installs the specified PACKS from the manifest into
the `STATIC-DIR/emoji/PACK-NAME
### Options
- `-m, --manifest PATH/URL` - same as ls-packs
## gen-pack
mix pleroma.emoji gen-pack PACK-URL
Creates a new manifest entry and a file list from the specified remote pack file.
Currently, only .zip archives are recognized as remote pack files and packs are therefore
assumed to be zip archives. This command is intended to run interactively and
will first ask you some basic questions about the pack, then download the remote
file and generate an MD5 signature for it, then generate an emoji file list for you.
The manifest entry will either be written to a newly created `index.json` file or appended to the existing one,
*replacing* the old pack with the same name if it was in the file previously.
The file list will be written to the file specified previously, *replacing* that file.
You _should_ check that the file list doesn't contain anything you don't need in the pack, that is,
anything that is not an emoji (the whole pack is downloaded, but only emoji files are extracted).
"""
@default_manifest Pleroma.Config.get!([:emoji, :default_manifest])