Markdown emoji: Unicode and shortcode syntax

There are two distinct ways to add emojis in Markdown. First, you can paste a Unicode emoji character (🎉) directly into the text, which works in every Markdown renderer because it is just a character. Second, you can type a shortcode such as :smile:, which some platforms convert to an emoji. Shortcodes are a GitHub and platform convention, not part of the Markdown standard.

Markdown emoji syntax reference

Markdown emoji key facts

• There are two ways to add an emoji: paste a Unicode emoji character directly, or type a colon shortcode such as :smile: that a supporting platform converts.
• Pasted Unicode emoji work everywhere because they are plain characters; Markdown does nothing special with them.
• Shortcodes are not part of the core Markdown or CommonMark specification; GitHub introduced the convention and each platform keeps its own list.
• If a renderer does not recognize a shortcode, it prints the literal characters, such as :smile:, instead of an emoji.
• Shortcode dictionaries differ across GitHub, Slack, and Discord, so a shortcode-heavy document is not portable.
• For portability, paste the Unicode character; for skin tone and combined emoji, pasting the Unicode form is the reliable approach.

Choose Unicode emoji for portability

Pasted Unicode emoji are ordinary text characters and survive most Markdown conversions. Colon shortcodes such as :rocket: depend on a platform-maintained name list and are not part of CommonMark. A shortcode that works on GitHub may remain literal text in another renderer.

Use Unicode when the document must move between editors or export formats. Use shortcodes when the target platform supports them and the source readability is useful. For accessible writing, do not replace important status words with an emoji alone. Keep labels such as “Warning,” “Complete,” or “Failed” in the text, and treat the emoji as supporting information.

Two ways to add an emoji

The single most important idea on this page is that "emoji in Markdown" means two separate things with very different support.

1. A pasted Unicode emoji is a real character in the text, like a letter or a digit. Markdown does nothing special with it. It passes straight through to the output and renders on any system with an emoji font.
2. A shortcode like :smile: is plain text that a specific platform recognizes and swaps for an emoji at render time. If the renderer does not recognize the shortcode, it prints the literal characters :smile: instead.

Neither approach is defined by the core Markdown specification. Pasted emoji work because of Unicode, not Markdown. Shortcodes work because of an extension that each platform adds on top.

Basic syntax: pasted Unicode emoji

Type or paste the emoji character directly into your Markdown. No special markup is needed.

Markdown

Deploy complete 🚀 and all tests passed ✅

Rendered output

HTML output

<p>Deploy complete 🚀 and all tests passed ✅</p>

The emoji appears verbatim in the HTML as a Unicode character. There is no wrapper element and no conversion step. This is why pasted emoji are the portable choice: any renderer that can display text can display them.

Basic syntax: shortcodes

A shortcode is an emoji name wrapped in colons, such as :tada: or :heart:. On a platform that supports shortcodes, the parser replaces the shortcode with the matching emoji.

Markdown

Great work :tada: I really :heart: this feature

Rendered output (on a supporting platform such as GitHub)

Great work 🎉 I really ❤️ this feature

Rendered output (on a plain CommonMark renderer)

Great work :tada: I really :heart: this feature

HTML output (on a supporting platform)

<p>Great work <g-emoji alias="tada">🎉</g-emoji> I really <g-emoji alias="heart">❤️</g-emoji> this feature</p>

The exact HTML depends on the platform. GitHub historically wrapped converted emoji in a <g-emoji> element and now often outputs a plain Unicode character or an <img> for custom emoji. A plain renderer that does not support shortcodes emits the literal text:

<p>Great work :tada: I really :heart: this feature</p>

Shortcodes are not standardized

There is no single, official list of shortcodes. Each platform maintains its own dictionary of names, so the same emoji can have different shortcodes on different tools.

• GitHub introduced the :name: convention and publishes its full list at the GitHub emoji API endpoint.
• Slack and Discord keep separate dictionaries. A name that works on one may not exist on the other. For example, Slack uses :slightly_smiling_face: where another tool might use a different name.

Because of this, a document full of shortcodes is not portable. If you paste it from GitHub into a tool that uses a different dictionary, some shortcodes may not resolve and will show as literal text.

Custom and platform-only emoji

Chat platforms such as Slack and Discord let teams upload custom emoji that also use the :name: shortcode form, for example :party_parrot:. These exist only inside that workspace or server. They are not Unicode characters, so they will never render anywhere else, and pasting the shortcode into another tool shows plain text.

Skin tone and combined emoji

Many emoji support skin tone modifiers and are built from multiple Unicode code points joined together, such as the family emoji or a waving hand with a tone. When you paste these as Unicode characters they render correctly wherever the font supports them. Shortcodes for tone variants are inconsistent across platforms, so pasting the Unicode character is the reliable approach.

Markdown

👋🏽 Hello, and welcome 👨‍👩‍👧‍👦

Rendered output

Flavor differences

Support splits cleanly along the two methods. Pasted Unicode emoji are plain text characters, so they remain intact across Markdown parsers. Their appearance and accessibility labels can still vary by system. Shortcodes are an extension that only some tools implement, and the core specifications do not define them.

The takeaway: only pasted Unicode emoji are safe to assume everywhere. Shortcodes depend entirely on the renderer.

Other platforms (GitHub, Slack, Discord, Notion, Obsidian)

Shortcode behavior varies widely across the chat and note tools that people paste AI-generated Markdown into:

• GitHub: supports shortcodes in Markdown files, issues, pull requests, and comments, using its own emoji list.
• Slack and Discord: both support :name: shortcodes and custom uploaded emoji, but each keeps a different dictionary, so names do not always match between them or with GitHub.
• Notion: inserts emoji through its own picker and slash command rather than converting Markdown shortcodes on paste; a pasted :smile: typically stays as literal text.
• Obsidian: renders pasted Unicode emoji natively; shortcode conversion depends on a community plugin rather than core behavior.

For the full comparison of how flavors differ across all elements, see Markdown flavors.

How Markdific renders it

Markdific renders pasted Unicode emoji as ordinary text characters, so they display wherever your system has an emoji font. Shortcodes such as :name: are a platform convention rather than standard Markdown and may appear as literal text unless the renderer supports them.

For portable documents, prefer pasted Unicode emoji, which render consistently regardless of shortcode support. Try it in the Markdific online editor.

Common mistakes and gotchas

• Assuming shortcodes work everywhere. :smile: is a platform convention, not standard Markdown. On many renderers it prints as literal text.
• Expecting one universal shortcode list. Names differ across GitHub, Slack, and Discord. A shortcode that works in one tool may not exist in another.
• Relying on custom emoji outside their platform. Custom Slack and Discord emoji are workspace-specific and never render elsewhere.
• Confusing pasted emoji with shortcodes. A pasted 🙂 is a Unicode character and always works. :smile: is text that needs a converter.
• Broken shortcodes after moving content. Copying shortcode-heavy text between platforms can leave some codes unresolved as literal :name: strings.
• Font or platform gaps. Even a valid Unicode emoji can show as a box if the viewing system lacks that glyph in its emoji font.

Best practices

• For portability, paste the Unicode emoji character directly rather than using a shortcode.
• Use shortcodes only when you know the target platform supports them, for example inside GitHub or a specific chat tool.
• Do not mix the two styles in one document if you plan to move it between tools.
• Keep emoji purposeful. In technical documentation, a small number of status emoji (✅, ⚠️) reads better than many decorative ones.
• Do not rely on emoji alone to convey required meaning, since a missing glyph or unconverted shortcode can drop the information.

HTML equivalent

A pasted Unicode emoji compiles to itself: the same character sits inside the surrounding HTML with no wrapper.

Markdown

Shipped 🚀

HTML output

<p>Shipped 🚀</p>

A shortcode, on a platform that supports it, compiles to the emoji character, sometimes inside a platform-specific wrapper element. On a platform that does not, it compiles to the literal text.

Markdown

Shipped :rocket:

HTML output (unsupported renderer)

<p>Shipped :rocket:</p>

FAQ

How do you add an emoji in Markdown? Two ways. Paste the Unicode emoji character directly, which works in any renderer, or type a shortcode like :smile:, which only converts on platforms that support shortcodes.

Are emoji shortcodes part of standard Markdown? No. Shortcodes such as :smile: are not defined by CommonMark or the core Markdown specification. They are an extension that GitHub popularized and that some platforms and tools implement.

Why does :smile: show as literal text instead of an emoji? Because the renderer does not support shortcodes. Plain CommonMark, Markdown Extra, and Pandoc without the emoji extension all print the literal :smile: text rather than converting it.

Do emoji shortcodes work on GitHub? Yes. GitHub supports :name: shortcodes in Markdown files, issues, pull requests, and comments, using its own published emoji list.

Are shortcodes the same across GitHub, Slack, and Discord? No. Each platform maintains its own dictionary of shortcode names, so a name that works in one tool may be different or missing in another.

What is the most portable way to use emoji in Markdown? Paste the Unicode emoji character directly. Because it is a plain character rather than a code to convert, it renders anywhere the viewing system has an emoji font.

Does Pandoc support emoji shortcodes? Only when you enable the emoji extension, which is off by default. Without it, Pandoc leaves :smile: as literal text.

Will a pasted emoji always display correctly? Almost always, but not guaranteed. The character passes through every renderer, though it can appear as an empty box if the viewing system lacks that specific emoji glyph in its font.

How do you type a Unicode emoji to paste into Markdown? Use your operating system's emoji picker: press Control plus Command plus Space on macOS, or the Windows key plus period on Windows. Pick the emoji and it is inserted as a plain character.

Where can you find the list of GitHub emoji shortcodes? GitHub publishes its full set of supported names at the GitHub emoji API endpoint. Because each platform keeps its own list, a name from GitHub may not match Slack or Discord.

Why does my emoji show as an empty box or a question mark? The viewing system lacks that specific emoji glyph in its font, so it cannot draw the character. Newer emoji are the most likely to fall back to a box on older devices.

Should you use emoji in technical documentation? Keep them purposeful. A small number of status emoji, such as a check mark or warning sign, reads better than many decorative ones, and you should not rely on an emoji alone to carry required meaning.

Sources and compatibility references

• GitHub: using emoji
• Unicode emoji charts

Use these primary references for syntax rules. Renderer behaviour can still vary by version and configuration, so preview important documents in their final destination.

Related pages

• Markdown documentation hub
• Escaping characters in Markdown
• Inline HTML in Markdown
• Highlight text in Markdown
• Subscript and superscript in Markdown
• Markdown flavors compared