Guide

Emoji in Markdown

Q: How do I add emoji to a GitHub README?

Type the emoji directly, or use a shortcode like :sparkles: . Both work on GitHub.

There are two ways to put emoji in Markdown. Type the emoji itself, using your computer's emoji picker, and it works everywhere. Or type a shortcode between colons, like :rocket:, which only some apps turn into an emoji.

You write

Shortcodes look like this: :rocket: :tada: :white_check_mark:

You see

Shortcodes look like this: :rocket: :tada: :white_check_mark:

The shortcodes above stay as text here, because MarkdownPaper does not turn shortcodes into emoji. On GitHub they would show as emoji.

3 min read6 sectionsUpdated 1 Oct 2026

markdown-emoji.md

Practical guideSource becomes a page.

# heading

** emphasis

| table

Source→Page

On this page

Way 1: type the emoji

Markdown is plain text, and emoji are just characters, so an emoji typed into the file shows in any app that can show emoji. This is the portable way.

To open the emoji picker:

System	Keys
Windows	`Win` + `.`
macOS	`Ctrl` + `Cmd` + `Space`
Linux	Depends on the desktop and the app
Phones	The emoji key on the keyboard

Way 2: shortcodes

A shortcode is a name between colons. GitHub, Slack, Discord and many other apps turn it into the emoji with that name while you type or when they show the text.

You write

:smile: :heart: :thumbsup: :warning:

You see

:smile: :heart: :thumbsup: :warning:

Where shortcodes work:

App	Shortcodes
GitHub	Yes, in files, issues and comments
Slack, Discord	Yes, in their own messages
MarkdownPaper	No, they stay as text
Many other apps	Often no

Because support varies, a shortcode that shows as an emoji on GitHub can show as :smile: everywhere else. If the file will be read in more than one place, type the emoji itself.

Finding a shortcode

GitHub's list of supported shortcodes is in its documentation, and many editors suggest them as you type a colon and the first letters of a name.

Should you use emoji in documents?

Use them sparingly. Screen readers read each emoji's name aloud, so a line full of them is slow to listen to. One emoji at the start of a status line, like a tick for done, reads well. A row of them in a heading does not.

Questions

How do I add emoji to a GitHub README?

Type the emoji directly, or use a shortcode like :sparkles:. Both work on GitHub.

Why do my emoji shortcodes show as text?

The app does not support shortcodes. Type the emoji itself with your system's emoji picker instead.

Do emoji work in headings and tables?

Yes. Emoji are characters like any other, so they work anywhere text does.

Markdown text formatting, for other ways to make text stand out.
Open your Markdown in the reader to see how it reads.