IN A NUTSHELL
-
Getting Wicked PDF and wkhtmltopdf to correctly embed custom and multi-language fonts (like Chinese characters) in Rails-generated PDFs is surprisingly tricky, but I figured it out for you.
-
After wrestling with various methods, I landed on the most reliable approach: installing the fonts directly on your server and updating its font cache. Forget base64 encoding or flaky CDNs – this works.
-
By following my steps for server-side font setup, you’ll ensure your PDFs consistently render correctly, no matter the language or system, which is crucial for professional, internationalised documents.
Recently we had a client project using Wicked PDF and wkhtmltopdf on Rails. The application needed to generate PDFs both in English and Chinese characters using a custom font for printing that was compatible with both Mac and Windows desktops.
This apparently simple problem proved to be a rabbit hole of considerable depth. You see, PDFs embed fonts, and this is done using the local font available at the time of creation. When generating these programatically, you need to make sure that the font you are using has all the right glyphs of the language you are targeting. So if you want to put a Chinese character into your PDF, you need to make sure you are using a font that contains all those UTF-8 Chinese character code-points you need. The version of Helvetica in your server is probably not going to cut it, and even the quickly becoming standard that is Google’s Open-Sans font won’t handle it either.
What you need to do is either:
- Explain to wkhtmltopdf that you want to use a specific font and provide the font in some way that wkhtmltopdf can find it, or
- Install the font on the server you are using and then tell wkhtmltopdf the font family you are using.
Examples of how to do number 1 include base64 encoding the font into your stylesheet, which has the unwelcome side effect of bloating the size of your PDF, as all those font files (which for Asian fonts can be multiple megabytes) are embedded wholesale into your PDF. There are other methods, using CDNs and the like but I found them flakey at best.
However, using the second option of installing the font on the server turned out to be fairly simple, and is what I am going to use here. wkhtmltopdf uses the local system to generate the PDF, and as a result when you generate a PDF and pass in a font-family declaration in the CSS, it will search for a font which the system knows about to see if it can comply. On unix systems, this font cache is controlled by fc-cache
So to get this working, the first thing we do is install Wicked PDF by following the installation instructions on the GitHub page.
Then in the initializer, we specified our layout file (and that we are using HTTPS by default for all the things):
# config/initializers/wicked_pdf.rb
WickedPdf.config = {
layout: 'document.html',
default_protocol: 'https'
}
Our layout file is fairly simple:
<!-- app/views/layouts/document.pdf.erb -->
<!doctype html>
<html>
<head>
<meta charset='utf-8' />
<%= wicked_pdf_stylesheet_link_tag 'documents' -%>
</head>
<body>
<div class='pdf-page'>
<header class='document-header'>
<h1 class='page-title'>
<%= yield :header_title %>
</h1>
</header>
<%= yield %>
</div>
</body>
</html>
And then in the stylesheet we include:
// app/assets/stylesheets/documents.css
body {
font-family: 'Noto Sans SC', 'Noto Sans';
font-size: 14px;
}
Now we need to get the font files. So get the Noto Sans and Noto Sans SC font files and copy them into your app/assets/fonts directory. Make sure you include the various types of fonts you need for compatibility. We installed eot, ttf, woff and woff2 font files to make sure we were compatible.
Finally, on server deploy you need to make sure the font files are known about by the server; at reinteractive we deploy using our OpsCare service, so this was easily done by putting the following into our after_deploy.sh file:
# config/deploy/hooks/after_deploy.sh
# Add hook to refresh font cache for wkhtmltopdf to work
echo "Linking font dir to ${current_app_path}/app/assets/fonts"
ln -sf ${current_app_path}/app/assets/fonts ~/.fonts
echo "Caching fonts"
fc-cache -v
During the deploy you then see the following happen in the output:
45s - Hook: after_deploy.
45s - /var/www/tradeline-staging/current/app/assets/fonts:
46s - caching, new cache contents: 26 fonts, 0 dirs
var/www/tradeline-staging/current/app/assets/fonts:
50s - caching, new cache contents: 26 fonts, 0 dirs
home/app_user/.cache/fontconfig: cleaning cache directory
fc-cache: succeeded
Which tells us that the fc-cache command has found its intended targets and cached our fonts.
Now, when we view the PDF it should render the fonts correctly and not produce a blank page. Done!
