Emojitsu

Tiny executable techniques for dealing with emoji

Table of Contents

• Emojitsu
  • Installation
  • CLI Usage
    • Overview
    • Examples
      • Emojify file contents to stdout
      • Emojify a file in place
      • Emojify from stdin
      • Look up the unicode emoji for a (GitHub) name
      • Look up the (GitHub) name for an emoji
  • CI Usage
  • Use with mdBook

NOTE: Emojitsu currently only supports name <-> unicode conversions for emoji supported by GitHub. But there is no reason it should stay so confined, if we find we need other features.

Installation

Using opam:

$ opam pin https://github.com/shonfeder/emojitsu.git#0.1.1

For Linux with x86 architecture, there is also a (hopefully) portable executable in the releases. This is intended for use in CI. See CI Usage for details.

CLI Usage

Overview

$ emojitsu --help=plain
NAME
       emojitsu - Techniques for dealing with emoji

SYNOPSIS
       emojitsu COMMAND ...

COMMANDS
       emojify
           Replace all names of the form :emoji_name: with the corresponding
           unicode

       find-name
           Find the (GitHub) name of an emoji given its unicode

       find-unicode
           Find the unicode of an emoji given its (GitHub) name

OPTIONS
       --help[=FMT] (default=auto)
           Show this help in format FMT. The value FMT must be one of `auto',
           `pager', `groff' or `plain'. With `auto', the format is `pager` or
           `plain' whenever the TERM env var is `dumb' or undefined.

       --version
           Show version information.

Examples

Consider the following example file:

$ cat > ./emoji-names-example.md <<EOL \
> # Emoji Names :tada:\
> :woman_teacher: :woman_student: :woman_scientist:\
> :rowing_woman: :basketball_woman: :biking_woman:\
> EOL

Emojify file contents to stdout

$ emojitsu emojify ./emoji-names-example.md
# Emoji Names 🎉
👩‍🏫 👩‍🎓 👩‍🔬
🚣‍♀ ⛹‍♀ 🚴‍♀

Emojify a file in place

$ emojitsu emojify --inplace ./emoji-names-example.md && cat ./emoji-names-example.md
# Emoji Names 🎉
👩‍🏫 👩‍🎓 👩‍🔬
🚣‍♀ ⛹‍♀ 🚴‍♀

Emojify from stdin

$ echo :fist: | emojitsu emojify
✊

Look up the unicode emoji for a (GitHub) name

$ emojitsu find-unicode black_flag
🏴

Look up the (GitHub) name for an emoji

$ emojitsu find-name ☮
peace_symbol

CI Usage

You can use emojitsu in your CI pipeline by installing from source. likely using opam.

We also build binaries via the ubuntu GitHub runner and upload them with our releases. You can find the latest gh-actions-emojitsu binary in the releases.

You can use it in your CI pipeline like so:

# Install emojitsu
wget --no-verbose https://github.com/shonfeder/emojitsu/releases/download/0.1.1/gh-actions-emojitsu
chmod +x gh-actions-emojitsu

# Emojify the markdown
find . -type f -name "*.md" -exec ./gh-actions-emojitsu emojify -i {} \;

This has only been tested in other github runners any my own Think Pad running Manjero.

Use with mdBook

You can use emojitsu as a preprocessor for mdBook by wrapping it in with a small bash script to account for mdBook's idiosyncratic expectations.

In ./emojitsu-wrapper.sh:

#!/usr/bin/env bash
set -euo pipefail

jq -M -c .[1] <&0 | emojitsu emojify

Explanation -- This script takes care of two thing:

1. It ignores the CLI args mdBook passes to preprocessors to test for formatting support (which is not needed for emojify to work its simple magic).
2. It extracts the second element of the JSON array mdBook sends to stdin, which contains the book content.

After you've made the wrapper executable --

chmod +x ./emojitsu-wrapper.sh

-- you can use it in your mdBook configuration by adding the following table to the book.toml:

# snip

[preprocessor.emojify]

command = "./emojitsu-wrapper.sh"