lecture.studio

Emoji in Marp: shortcodes, Twemoji images and offline PDFs

By Ekrem Çetinkaya · Published

Marp turns :tada: shortcodes into emoji and, by default, renders every emoji (typed or from a shortcode) as a Twemoji image loaded from the jsDelivr CDN, so slides look the same on every machine. The cost is a network dependency: an offline PDF export shows an empty box where the emoji was. marp-cli and Marp Core have an option to keep the system's own emoji instead.

This guide covers the syntax, the CDN behaviour, offline export, and where emoji are useful in a lecture deck (rarely, and then consistently).

Shortcodes

- :white_check_mark: done
- :warning: watch the quantum
- :tada: end of term

The names are the GitHub set (:tada:, :warning:, :bulb:, :book:, :rocket:). Typing the emoji character works the same.

Twemoji from a CDN

Marp Core converts emoji to <img> tags pointing at cdn.jsdelivr.net/gh/twitter/twemoji…. In the HTML export the viewer's browser fetches them; in a PDF export marp-cli's browser fetches them during conversion. Both need a network connection at that moment. Offline, the image fails and the PDF shows nothing (or a broken-image box), which is the usual "my emoji disappeared" report.

Keep the system emoji

Turn the conversion off in a marp-cli config file:

// marp.config.js
module.exports = {
  options: { emoji: { shortcode: true, unicode: false } },
};

shortcode: true still expands :tada: to the character; unicode: false stops the Twemoji image conversion, so the browser's own emoji font draws it (Apple Color Emoji on a Mac, Segoe UI Emoji on Windows, Noto Color Emoji on Linux). The look then depends on the machine, but the PDF works offline and the emoji embeds as a glyph.

For the VS Code extension there is no setting for this; export from marp-cli with the config when offline PDFs matter. This site's online editor uses the system emoji.

Emoji in a lecture deck

Two uses hold up: a consistent status mark (:white_check_mark: / :x: in a do-and-don't pair) and a single icon on a section divider. Emoji as bullets, emoji in headings, or emoji for emphasis read as noise from the back row and date the deck. If the deck goes to students as a PDF, remember the offline caveat.

FAQ

Does Marp support emoji shortcodes?

Yes: :tada:, :warning: and the rest of the GitHub set expand to emoji.

Why do emoji disappear in my Marp PDF?

They are Twemoji images from a CDN, and the export ran offline. Export online, or set emoji: { unicode: false } in marp.config.js to use the system emoji font.

Can I use the system emoji instead of Twemoji?

Yes, with the emoji option in a marp-cli config file (unicode: false). The VS Code extension has no setting for it.

Do emoji work in the PPTX export?

The default PPTX renders each slide as an image, so whatever the browser drew (Twemoji or system emoji) is in it.

More guides