How to Use Emoji in Markdown

Emoji shortcodes are not Markdown. Neither CommonMark nor GFM defines :smile: — the conversion is a text-replacement feature each platform layers on top, with its own list of recognized names. A pasted Unicode emoji, by contrast, is just a character: it survives every renderer, every converter, and every copy-paste, because there is nothing to parse. The practical rule: use Unicode when a document needs to travel between platforms, and shortcodes when you are staying inside one platform and want names that are searchable and consistent in the source.

Platform support splits cleanly. GitHub recognizes a large shortcode set (the gemoji list) in READMEs, issues, and comments, and typing a colon in the web editor opens an autocomplete picker. Slack has its own shortcode names — overlapping with GitHub's but not identical — plus custom workspace emoji, and converts codes as you type. Discord autocompletes :name: in the message box and supports custom server emoji. Obsidian is the notable holdout: it does no shortcode conversion at all, so :smile: stays literal text unless you install a community plugin — but Unicode emoji render perfectly and even work in note titles and filenames. The same is true of most static site generators and Markdown libraries: unless the pipeline explicitly adds an emoji plugin, shortcodes pass through to the published page as plain colon-delimited text.

The subtlest emoji gotcha lives in headings. GitHub generates anchor slugs from heading text by lowercasing, hyphenating spaces, and stripping characters that are not letters, numbers, or hyphens — and emoji get stripped. The space that separated the emoji from the text survives as a hyphen, so ## 🚀 Launch Guide gets the anchor #-launch-guide, not #launch-guide. Hand-written table-of-contents links that ignore this break silently. If you decorate headings with emoji, verify the generated anchor (hover the heading on GitHub and copy the link icon) rather than guessing, or keep emoji out of any heading you intend to link to.

Two more practical considerations. First, shortcodes fail loudly when unsupported and quietly when misspelled: :rokcet: renders as literal colon text on every platform, so proofread the names. Second, emoji are read aloud by screen readers using their Unicode names — a single 🎉 after a sentence is fine, but a row of ten decorative emoji becomes ten spoken descriptions, and emoji used in place of words ("ship it 🚀 today") interrupt the sentence flow. Rendering also varies by operating system font, so an emoji that looks subtle on macOS may look very different on Windows or Android.