Getting Emoji to Work in Asciidoctor PDF

At Gooroo, we use AsciiDoc + Asciidoctor for publishing our Tutor Handbook. This setup allows us to generate HTML, ePub, and PDF versions of the handbook from a single source file.

One issue we ran into is the lack of out-of-the-box support for emojis in the Asciidoctor PDF converter, which appears to be caused by some limitations in the TTF library used by Prawn, the PDF writer used by Asciidoctor PDF.

A simple workaround that I found is to use Prawn::Emoji, a gem that adds emoji support to Prawn. For it to work, assuming you are using Rake, you need to require Prawn::Emoji before requiring Asciidoctor as follows:

# Rakefile
require 'prawn/emoji' # Must be required before asciidoctor and asciidoctor-pdf
require 'asciidoctor'
require 'asciidoctor-pdf'
require 'asciidoctor-epub3'

desc 'Generate the PDF version of the handbook'
task :pdf do
  Asciidoctor.convert_file 'src/epub.adoc',
    safe: :unsafe,
    backend: 'pdf',
    to_dir: 'dist',
    mkdirs: true,
    to_file: 'handbook.pdf',
    attributes: [
      'imagesdir=images',
      'pdf-theme=./theme.yml',
      'pdf-fontsdir=./src/fonts'
    ]
end

# ...

✨