Markdown syntax

How to Use Emoji in Markdown
(Why :smile: Shows as Text)

There are two ways to put emoji in Markdown: paste the emoji character itself (πŸŽ‰), which works everywhere because it is just text, or type a shortcode like :tada:, which only converts on platforms that support it. If you are looking at a literal :smile: right now, your renderer is one of the many that do not.

The reliable way: paste the emoji itself

An emoji is a normal Unicode character, the same as a letter or a Chinese character. Paste πŸš€ into a .md file and every editor, viewer, and site will show it, because there is nothing to convert.

You do not need a cheat sheet to find one. Your OS has a picker built in:

  • Windows: press Win + . (the period key) and pick from the panel.
  • macOS: press Ctrl + Cmd + Space.

The character lands in your file like any other text and is saved with it. This is the way to go whenever the file might be opened somewhere else later.

Why :smile: shows up as plain text

Shortcodes look like Markdown syntax, but they are not. Neither the CommonMark spec nor GFM has an emoji rule. :smile: converting into πŸ˜„ is a feature that GitHub added on top for its own pages, and a handful of other platforms did the same with their own name lists.

So when a plain Markdown editor shows you the literal :smile:, nothing is broken. The editor is rendering the file correctly; the colons-and-name text is what the file actually contains. The same logic applies to the other cases where Markdown seems to not render: the first question is always whether the thing you typed is Markdown at all.

A misspelled name has the same symptom on platforms that do support shortcodes: :smiel: stays text on GitHub too, because the name has to match its list exactly.

Where shortcodes convert, and where they stay text

Platform :shortcode: Pasted emoji πŸŽ‰
GitHub (github.com) Converted Shown as emoji
GitLab Converted Shown as emoji
Slack, Discord (chat) Converted (their own name lists) Shown as emoji
VS Code preview Plain text (needs an extension) Shown as emoji
Obsidian Plain text Shown as emoji
NoteLoom Plain text Shown as emoji

The pattern in the right column is the whole story: the pasted character works in every row, on every platform, with no exceptions to memorize.

What happens when the file travels

This difference only starts to matter when a .md file moves between tools, and that is exactly what AI-era Markdown does. A README you download from GitHub, a doc an AI wrote for you, notes you move from one app to another: any :tada: inside travels as eleven plain characters, and whether it ever becomes πŸŽ‰ again depends on where the file lands.

A pasted emoji has no such dependency. It is in the file, it stays in the file, and it looks the same at every stop.

NoteLoom is a case in point: it renders CommonMark and GFM from your local .md files, so shortcodes stay as text, honestly reflecting what is in the file. Pasted emoji show up fine in all three views (source, live, and reading), and when you edit and save, they are written back to your local file untouched.

Related reading

Markdown not rendering? The common gotchas The diagnostic hub for every "why is this showing as symbols" moment, emoji included. How to underline text in Markdown Another thing Markdown does not have natively, and what to use instead. Markdown bold or italic not working? When it is real Markdown syntax that refuses to render, start here. How to write Markdown The core syntax in one place, for everything that actually is in the spec.

FAQ

Why does :smile: work on GitHub but not in my editor?
Emoji shortcodes are a GitHub feature, not Markdown syntax. The CommonMark and GFM specs have no emoji rule, so a plain Markdown editor leaves :smile: as the literal text you typed. GitHub converts it on github.com as an extra step of its own.
How do I type an emoji without a cheat sheet?
Use the emoji picker built into your OS: press Win+. (period) on Windows, or Ctrl+Cmd+Space on a Mac. Pick the emoji and it is inserted as a real character, no shortcode needed.
Do emoji break .md files?
No. An emoji is a normal Unicode character, the same as any letter, and .md files are plain text. It is saved in the file and survives copying, moving, and opening in other tools.
Does NoteLoom convert :shortcodes: into emoji?
No. NoteLoom renders CommonMark and GFM, and neither includes emoji shortcodes, so :tada: stays as text. Pasted Unicode emoji display fine in all three views and are saved into your local .md as-is.
Are shortcode names the same on every platform?
No, and that is another way they break. GitHub, Slack, and Discord each keep their own name lists, so a shortcode that converts in one place can stay plain text in another. Unicode emoji have no such problem.
Will my emoji still be there after saving and reopening the file?
Yes. A Unicode emoji is part of the text, so it is written into the .md file and comes back exactly the same when you reopen it, in any editor.

Check what your file really contains

Open your .md in NoteLoom in Chrome / Edge / Arc: the source view shows you the raw text (shortcodes and all), and the reading view shows it rendered. Local file in, local file out, nothing uploaded.

Open NoteLoom and try it