Guide

Getting Emoji Support in Markdown to PDF Conversions

Updated July 10, 2026

Getting Emoji Support in Markdown to PDF Conversions

Emojis have become a standard element in modern writing. They add expression to technical guides, organize list items in notes, and make documents more engaging. However, when you compile a Markdown file containing emojis into a PDF, you are often met with disappointment. Emojis frequently render as empty rectangular boxes (known as “tofu”), weird question marks, or fail to display entirely.

In this troubleshooting guide, we’ll explain how to get complete emoji support markdown to pdf exports, ensuring your documents look beautiful and colorful on every screen and printout.

Why Emojis Break in PDF Exports

To understand how to fix emojis, we must look at the two main reasons they break during conversion:

  1. Character Encoding Failures: If the converter reads your file using an older encoding format (like ISO-8859-1 or ASCII), it won’t recognize emoji unicode symbols.
  2. Missing Font Glyphs: Standard document fonts like Arial, Times New Roman, and Georgia do not contain vector graphics for emojis. If your stylesheet does not define an emoji fallback font, the rendering engine will display a default missing-glyph box.

Step 1: Force UTF-8 Character Encoding

Emojis require UTF-8 encoding. If you compile your Markdown through CLI tools or custom scripts, ensure your HTML meta headers or engine settings specify UTF-8.

If you are injecting custom HTML templates, add this meta tag to your <head>:

<meta charset="utf-8">

For command-line tools like Pandoc, specify the input encoding option:

pandoc document.md -o document.pdf --pdf-engine=xelatex -V mainfont="DejaVu Sans"

Step 2: Set Up Emoji Font Fallbacks in CSS

The most robust way to support emojis in browser-based Markdown-to-PDF converters is by configuring your CSS font-family property. You need to list specialized color emoji fonts as fallbacks in your main styling stack.

Here is a cross-platform emoji font stack:

body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, 
                 "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
}

Why this stack works:

  • "Apple Color Emoji" ensures emojis look crisp and native on macOS and iOS.
  • "Segoe UI Emoji" renders native Microsoft-styled emojis on Windows.
  • "Noto Color Emoji" provides Google’s open-source color emojis on Linux and Android.

By adding these to the end of your font stack, the rendering engine will fall back to these fonts whenever it encounters an emoji character.

Step 3: Server-Side Fonts (For Headless Compilers)

If you are running your PDF compilation on a Linux server (using tools like Puppeteer, WeasyPrint, or wkhtmltopdf), you must install emoji fonts on the server’s operating system. If the server doesn’t have the font installed, the rendering engine cannot use it.

To install Noto Color Emoji on Ubuntu/Debian:

sudo apt-get update
sudo apt-get install fonts-noto-color-emoji

Once installed, rebuild your font cache:

sudo fc-cache -f -v

Step 4: Using SVG Fallbacks (Twemoji or JoyPixels)

If you want absolute styling consistency regardless of the reader’s operating system, you can use javascript libraries to convert unicode emojis into inline SVG images before exporting to PDF. Libraries like Twemoji (by Twitter) parse your document and swap characters like 🚀 for <img class="emoji" src="https://abs.twimg.com/emoji/v2/svg/1f680.svg" />.

Then you can style them in your CSS:

img.emoji {
    height: 1.2em;
    width: 1.2em;
    margin: 0 .05em 0 .1em;
    vertical-align: -0.1em;
    display: inline-block;
}

Try It Yourself

Tired of dealing with broken character layouts and “tofu” boxes? Use our Markdown to PDF Editor. It features pre-configured UTF-8 encoding and built-in cross-platform emoji font stacks, so you can write freely and download PDFs with rich emoji support instantly.

Written by Markdown to PDF Editorial Team

Our team specializes in document design, web standards, and developer utilities. This guide was researched and vetted against current browser printing standards and Paged.js specifications. Learn more on our About page.

Try it yourself — free, no signup

Convert your Markdown to a polished PDF right in your browser.

Open the editor

Related reading

← All articles