Getting Emoji to Work in Asciidoctor PDF

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

One of the limitations that we ran into, is the lack of out-of-the-box support for emoji in the Asciidoctor PDF converter. This is due to some limitations in the TTF library used by Prawn, the PDF library 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 must 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

# ...

✨