Markdown Icons and Emoji: How to Add Them (2026)
September 11, 2026 · 10 min read
Markdown Icons and Emoji: How to Add Them
You can add markdown icons in four ways: emoji shortcodes like :rocket:, raw Unicode characters, HTML entities such as ✔, and small inline images. Only the last three work everywhere. This post shows each method, where it renders, and which one to pick for READMEs, docs sites, and chat apps.
Four Ways to Put Icons in Markdown
Markdown has no icon syntax of its own. The CommonMark spec and the GFM spec never mention emoji, so every markdown icon you see in a rendered file arrives by one of these routes:
1. Shortcode: :rocket: :white_check_mark: :warning:
2. Unicode: 🚀 ✅ ⚠️ → ✔ ★
3. HTML entity: ✔ ❌ → ★
4. Inline image: <img src="https://raw.githubusercontent.com/dcurtis/markdown-mark/master/png/66x40-solid.png" width="33" alt="Markdown mark" />
Line 1 renders as markdown emojis on GitHub, GitLab, Slack, and Discord. Almost everywhere else it stays as literal colon text. Line 2 renders in every renderer because it is plain text. Line 3 works in any parser that follows CommonMark, which passes HTML entities through to the browser. Line 4 works wherever inline HTML is allowed. That includes GitHub READMEs but not Slack or Discord messages.
We prefer raw Unicode for anything that needs to survive a change of platform. A ✅ pasted into a file is still a ✅ when the same file lands in Obsidian, a wiki, or a PDF export. Shortcodes are convenient on GitHub, but they turn into :white_check_mark: the moment the file leaves.
Where Do Markdown Emoji Shortcodes Work?
Shortcode support is a platform feature, not a Markdown feature. Here is the tested behaviour on the platforms readers ask about most.
| Platform | :shortcode: | Raw Unicode | HTML entity | Inline <img> |
|---|---|---|---|---|
| GitHub (README, issues, PRs) | Yes, 1,936 codes | Yes | Yes | Yes |
| GitLab | Yes | Yes | Yes | Yes |
| Slack messages | Yes (own names) | Yes | No | No |
| Discord messages | Yes (own names) | Yes | No | No |
| Obsidian | No | Yes | Yes | Yes |
| VS Code preview | Only with the Markdown Emoji extension | Yes | Yes | Yes |
| Material for MkDocs | Yes, with pymdownx.emoji | Yes | Yes | Yes |
| Our editor and most CommonMark renderers | No | Yes | Yes | Yes |
GitHub documents the syntax in Basic writing and formatting syntax: type a colon and the name, and typing : alone opens an autocomplete list. The full set comes from the public endpoint https://api.github.com/emojis, which returned 1,936 names when we fetched it. Of those, 23 are GitHub-only images with no Unicode equivalent: :octocat:, :shipit:, :bowtie:, :trollface:, :dependabot:, and :copilot: among them.
Obsidian's basic formatting reference lists no emoji syntax, and in our testing :smile: stays as typed. Paste the emoji itself instead. VS Code's built-in preview behaves the same way until you install Matt Bierner's Markdown Emoji extension, which adds :emoji: rendering to the preview and to notebook Markdown cells.
Slack and Discord each keep their own shortcode tables, so a name that works on GitHub may not exist there. Slack's API represents emoji in message text in the same colon form, so 🎉 travels as :tada:. Both apps offer autocomplete after you type a colon, so you rarely need to remember the names. See the Discord Markdown cheat sheet for the rest of Discord's formatting rules.
42 Shortcodes Worth Memorising
The full GitHub list has close to two thousand entries. These 42 markdown icons cover almost every case that shows up in READMEs, changelogs, and issue templates.
| Purpose | Shortcodes |
|---|---|
| Status | :white_check_mark: ✅ :x: ❌ :warning: ⚠️ :construction: 🚧 :heavy_check_mark: ✔️ |
| Changes | :sparkles: ✨ :bug: 🐛 :zap: ⚡ :boom: 💥 :recycle: ♻️ :wrench: 🔧 |
| Docs and notes | :memo: 📝 :book: 📖 :bulb: 💡 :pushpin: 📌 :information_source: ℹ️ :question: ❓ |
| Releases | :rocket: 🚀 :tada: 🎉 :package: 📦 :bookmark: 🔖 :label: 🏷️ |
| Security and ops | :lock: 🔒 :key: 🔑 :shield: 🛡️ :gear: ⚙️ :hammer: 🔨 :fire: 🔥 |
| Reactions | :+1: 👍 :-1: 👎 :heart: ❤️ :eyes: 👀 :clap: 👏 :wave: 👋 |
| Arrows and marks | :arrow_right: ➡️ :arrow_up: ⬆️ :star: ⭐ :heavy_plus_sign: ➕ :ballot_box_with_check: ☑️ |
| GitHub-only | :octocat: :shipit: :bowtie: |
Two names in that table cause confusion. :heavy_check_mark: and :white_check_mark: are different characters (a bare tick versus a tick in a green box), and neither is a task-list checkbox. A clickable checkbox comes from - [ ] syntax, covered in the Markdown checkbox guide.
How Do You Find the Right Shortcode Name?
Names are not standardised across platforms. :+1: and :thumbsup: both map to 👍 on GitHub, but only one may exist elsewhere. Three lookups settle it fast:
- GitHub's API. Open
https://api.github.com/emojisand search the JSON for the name. A URL containing/unicode/means a standard emoji; anything else is a GitHub-only image. - The platform's autocomplete. Type
:plus two or three letters in GitHub, Slack, or Discord and pick from the list. What autocomplete offers is what renders. - Emojipedia. Each emoji page lists its shortcodes per platform, the quickest way to spot a name that differs between GitHub and Slack.
For a Unicode symbol rather than an emoji (a plain arrow, a box-drawing character, a mathematical star), skip shortcodes entirely. Copy the character, or write its hex code point as an entity: → gives →, ✔ gives ✔, and ☐ gives ☐. Section 6.2 of the GFM spec confirms both decimal and hexadecimal forms are valid.
Try Markdown Icons in the Editor
Paste or edit the sample below. Our editor renders with a standard CommonMark-style parser. You'll see the Unicode, entity, and image rows come through, while the shortcode row stays as plain text. That is exactly what happens to markdown icons in most non-GitHub renderers.
Swap the tool to Markdown to HTML if you want the raw HTML to paste into a site.
Icon Fonts and Icon Sets in Docs Sites
Documentation generators go further than emoji. Material for MkDocs bundles four icon sets and states that more than 10,000 icons are available once you enable the extension in mkdocs.yml:
markdown_extensions:
- attr_list
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
After that, :material-account:, :fontawesome-brands-github:, :octicons-mark-github-16:, and :simple-markdown: render as inline SVG. The prefixes are material-, fontawesome-, octicons-, and simple-. These shortcodes are specific to MkDocs; on GitHub they print as text.
On platforms that allow inline HTML, a Font Awesome <i class="fa-solid fa-check"></i> tag only works if the page also loads the Font Awesome stylesheet. GitHub strips class-based styling, so it does nothing there. Shields.io badges are the usual GitHub answer: a  image link gives you a coloured label with no font dependency. The README Markdown guide covers badge layout in detail.
The Markdown File Icon Itself
Part of the search traffic for this topic wants a markdown file icon: the logo that represents Markdown in a file browser or a toolbar. That mark is the Markdown Mark by Dustin Curtis, a rounded rectangle containing an M and a down arrow. The markdown-mark repository has been dedicated to the public domain and ships SVG, PNG, ICO, ICNS, and icon-font versions.
The README asks you to keep the aspect ratio and border radius, keep all three elements the same colour, and prefer grey, white, or black where possible. The 66 by 40 pixel PNG in the demo above is the solid variant. If you're picking a markdown icon for a file-type badge or an app toolbar, use this one rather than a redrawn version from an icon marketplace.
Common Markdown Icon Mistakes
Shortcodes inside code. Anything between backticks or in a fenced block is literal, so :rocket: in a code span prints the colons. Move the icon outside the code span.
Emoji in headings that feed a table of contents. Many generators build the heading's anchor from its text, and an emoji in ## 🚀 Getting Started can produce an ugly or empty slug. GitHub drops the emoji from the slug, which usually leaves a leading hyphen such as #-getting-started. Keep emoji out of headings you plan to link to, or add the emoji after the anchor is set.
Assuming an icon looks the same everywhere. Emoji are glyphs supplied by the operating system, so ✅ on Windows, macOS, and Android are three different drawings of the same markdown icon. Screen readers also announce the emoji's name, so "🔥 Hot fix 🔥" reads as "fire Hot fix fire". One icon per line is plenty in a README.
Markdown Icons and Emoji FAQ
Pick the method that matches where the file will live. Shortcodes are quickest on GitHub and in chat, Unicode and entities travel with the file, and inline images give exact control. For a document that must look the same in a README, a wiki, and a PDF, raw Unicode is the safest of the markdown icons options. Test your mix in the editor, and keep the Markdown cheat sheet handy for the rest of the syntax.