Markdown: GFM Extended Syntax and Emoji

Q: Do emoji shortcodes ( :smile: ) work everywhere?

No. :smile: only works on specific platforms like GitHub, GitLab, and Slack. In VS Code and Typora, paste emoji characters directly instead.

Q: Is [TOC] part of GFM?

No. [TOC] is a custom feature of certain editors (like VS Code's Markdown All in One extension, Typora) and is not part of any Markdown standard.

Markdown has standard and extended flavors — GitHub Flavored Markdown is the most widely used extension, adding many practical syntax features.

1. What You'll Learn

The difference between GFM and standard Markdown
Complete usage of task lists
How to insert emoji
Using footnotes and definition lists
Auto-linking and URL recognition
How to ignore/escape Markdown syntax

2. An Open-Source Maintainer's Real Story

(1) Pain Point: Issues lack structured information

Morgan maintains an open-source project with 5000+ stars and receives dozens of Issues every day. Submissions are a mess — some have no reproduction steps, some forget to include error messages, some put emoji in titles making filtering hard. Maintainers spend a ton of time asking "what version are you on?" and "what's the full error message?"

(2) Solution: Create Issue templates with GFM

Morgan created GitHub Issue templates using task lists (- [ ] checklists), tables (version/environment info), and code blocks (error logs) to structure the information. Emoji mark the Issue type: 🐛 Bug, ✨ Feature, 📖 Documentation. After the template went live, Issue completeness rose from 30% to 85%, and average handling time was cut in half.

3. GFM Overview

GitHub Flavored Markdown (GFM) is a superset of standard Markdown, adding GitHub-specific extensions on top of the CommonMark spec:

graph TB
    A[GFM - GitHub Flavored Markdown] --> B[CommonMark Standard]
    A --> C[GFM Extensions]
    C --> D[Task Lists]
    C --> E[Tables]
    C --> F[Strikethrough]
    C --> G[Auto Links]
    C --> H[Emoji]
    C --> I[Syntax Escaping]

Feature	Standard Markdown	GFM
Tables	❌ No standard	✅ Full support
Task Lists	❌ No standard	✅ Supported
Strikethrough	❌ No standard	✅ ~~text~~
Auto Links	⚠️ Only `<>`	✅ URL auto-recognition
Emoji	❌ No standard	✅ `:smile:`
Fenced code syntax highlighting	⚠️ Partial	✅ Full support
Escaping Markdown	❌ Not supported	✅ `\` escape

💡 Tip: Although GFM is GitHub's extension, most modern Markdown parsers and editors (VS Code, Typora, Obsidian) also support these extensions.

4. Emoji

(1) Two ways to insert emoji

MARKDOWN

Method 1 (recommended): Use colon-wrapped shortcodes
:smile: → 😄
:rocket: → 🚀
:warning: → ⚠️

Method 2: Paste emoji characters directly
😄 🚀 ⚠️ ✅ ❌

(2) Common emoji for technical docs

MARKDOWN

✅ Done / ❌ Failed / ⚠️ Caution
🐛 Bug / ✨ New Feature / 📖 Documentation
🚀 Release / 🔧 Config / 🎨 Style
📦 Dependencies / 🔒 Security / 📊 Data

⚠️ Note: Not all platforms support emoji shortcodes (like :smile:). Some only support pasted emoji characters. For maximum compatibility outside GitHub, paste emoji characters directly.

▶ Example: Using emoji to label Issue types

MARKDOWN

## Issue Template

### Type
- 🐛 Bug Report
- ✨ Feature Request
- 📖 Documentation Improvement
- 🔧 Configuration Issue

### Environment
- OS: macOS 14.5
- Browser: Chrome 126
- Version: v2.3.1

5. Auto Links and URL Recognition

(1) URL auto-recognition

GFM automatically converts URLs into clickable links — no <> needed:

MARKDOWN

Visit https://github.com to learn more.

Documentation: https://developer.mozilla.org

Project repo: https://github.com/user/repo

(2) Email auto-recognition

MARKDOWN

Contact us: support@example.com
Author email: author@example.com

💡 Tip: If you don't want a URL to become a link, put it in a code block or use escaping.

6. Ignoring Markdown Syntax

Use the \ backslash to escape Markdown characters so they display as plain text:

MARKDOWN

\# This is not a heading — it shows the "#" character

\*\*This is not bold\*\*

\- This is not a list item

\[This is not a link\](url)

💡 Tip: GFM also supports wrapping symbols in ` to show their raw form: `#` displays as # instead of a heading.

▶ Example: Common escaping scenarios

MARKDOWN

When writing tutorials, you sometimes need to show the Markdown syntax itself:

Use \`#\` to denote a level-1 heading.

Syntax example: \*\*bold text\*\*

In code it's `**actual bold**` (wrapped in backticks, won't render).

💡 Tip: Wrapping syntax in backticks is the more common approach: `**text**` displays as code styling and won't render as bold.

7. Other GFM Extensions

(1) Strikethrough

MARKDOWN

~~This text has been deleted~~
~~This feature is deprecated~~

💡 Tip: Strikethrough is common in GFM but not all parsers support it. GitHub, GitLab, and VS Code all support it.

(2) Richer formatting within tables

GFM tables support code, links, and multiple content types:

MARKDOWN

| Command | Description | Example |
|:--------|:------------|:--------|
| `git status` | Show status | [Docs][status] |
| `git log` | Show history | `--oneline` compact mode |
| ~~`git merge`~~ | Deprecated | Use `rebase` instead |

[status]: https://git-scm.com/docs/git-status

(3) Fenced code block syntax highlighting

GFM supports syntax highlighting for dozens of languages:

YAML

name: CI Pipeline
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

💡 Tip: GFM supports the diff language tag — + lines show green (added), - lines show red (removed). Perfect for displaying code changes.

▶ Example: Using diff to show code changes

DIFF

# Old version
-    <script src="old-script.js"></script>
# New version
+    <script src="new-script.min.js" defer></script>

8. Complete Example: Writing a Full Issue with GFM

TEXT 📖 Display only

Issue title: Navigation bar won't expand in Firefox

Environment:
  OS | Windows 11
  Browser | Firefox 128.0
  Version | v3.2.1

Steps to reproduce:
1. Open the app
2. Click the user menu in top right
3. Menu fails to expand

Log output:
[2026-06-15 14:32:01] User clicked nav-toggle
[2026-06-15 14:32:03] No response from toggle handler

Expected result: A structured GitHub Issue with clear type labels (🐛 Bug), environment in a table, reproduction steps in an ordered list, and a checklist as a task list.

❓ FAQ

Q What's the difference between GFM and standard Markdown?

A Standard Markdown is the most basic syntax set (headings, lists, links, etc.). GFM adds tables, task lists, strikethrough, emoji, auto links, and more on top. Most modern tools support GFM.

Q Do emoji shortcodes (:smile:) work everywhere?

A No. :smile: only works on specific platforms like GitHub, GitLab, and Slack. In VS Code and Typora, paste emoji characters directly instead.

Q What if my Markdown parser doesn't support GFM?

A Check the parser's docs for GFM plugins or options. Pandoc uses --from gfm, marked.js supports GFM by default, Python-Markdown needs extensions=['extra'].

Q How do I make Markdown compatible with all parsers?

A Use only standard Markdown syntax (avoid GFM extensions), and fall back to HTML for unsupported parts. But this sacrifices convenience. Choose the right syntax subset based on your target platform.

Q Is [TOC] part of GFM?

A No. [TOC] is a custom feature of certain editors (like VS Code's Markdown All in One extension, Typora) and is not part of any Markdown standard.

📖 Summary

GFM is GitHub's CommonMark-based extension, adding task lists, tables, strikethrough, and more
Emoji can be inserted via :code: (GitHub) or pasted directly as characters
GFM auto-recognizes URLs and emails — no <> needed
Use \ to escape Markdown special characters and show them as plain text
The diff language tag uses +/- to show code changes
[TOC] and similar are not part of any standard or GFM — they're editor-specific features

📝 Exercises

Beginner: Write a Git commit message convention doc that uses emoji to label commit types (e.g. ✨ Feature 🐛 Fix) and includes a task list as a pre-commit checklist.
Intermediate: Use the diff language tag to show a before/after comparison of a code change (at least 5 lines, both additions and deletions). Then use auto-linking to reference a GitHub repository.
Challenge: Create a complete GitHub Issue template that combines tables (environment info), task lists (checklist), ordered lists (reproduction steps), code blocks (logs/config), emoji (type labels), and blockquotes (screenshots/extra notes).

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us

Markdown: GFM Extended Syntax and Emoji

1. What You'll Learn

2. An Open-Source Maintainer's Real Story

(1) Pain Point: Issues lack structured information

(2) Solution: Create Issue templates with GFM

3. GFM Overview

4. Emoji

(1) Two ways to insert emoji

(2) Common emoji for technical docs

▶ Example: Using emoji to label Issue types

5. Auto Links and URL Recognition

(1) URL auto-recognition

(2) Email auto-recognition

6. Ignoring Markdown Syntax

▶ Example: Common escaping scenarios

7. Other GFM Extensions

(1) Strikethrough

(2) Richer formatting within tables

(3) Fenced code block syntax highlighting

▶ Example: Using diff to show code changes

8. Complete Example: Writing a Full Issue with GFM

❓ FAQ

📖 Summary

📝 Exercises

🙏 帮我们做得更好