feat: add GFM emoji shortcode support

mdfluence/__main__.py

@@ -242,6 +242,12 @@ def get_parser():
         "Enabled by default. Use --no-convert-anchors to disable.",
     )
 
+    parser.add_argument(
+        "--disable-emoji",
+        action="store_true",
+        help="disable conversion of :shortcode: emoji to Unicode characters",
+    )
+
     parser.add_argument(
         "--dry-run",
         action="store_true",
@@ -691,6 +697,7 @@ def collect_pages_to_upload(args):
                 strip_header=args.strip_top_header,
                 remove_text_newlines=args.remove_text_newlines,
                 enable_relative_links=False,
+                enable_emoji=not args.disable_emoji,
             )
         )
 
@@ -718,6 +725,7 @@ def collect_pages_to_upload(args):
                     use_gitignore=args.use_gitignore,
                     enable_relative_links=args.enable_relative_links,
                     skip_subtrees_wo_markdown=args.skip_subtrees_wo_markdown,
+                    enable_emoji=not args.disable_emoji,
                 )
             else:
                 try:
@@ -730,6 +738,7 @@ def collect_pages_to_upload(args):
                             strip_header=args.strip_top_header,
                             remove_text_newlines=args.remove_text_newlines,
                             enable_relative_links=enable_relative_links,
+                            enable_emoji=not args.disable_emoji,
                         )
                     )
                 except FileNotFoundError:

mdfluence/document.py

@@ -26,6 +26,7 @@
 from mdfluence.confluence_renderer import ConfluenceRenderer, RelativeLink
 from mdfluence.ignored_files import GitRepository
 from mdfluence.plugins.alerts import alerts
+from mdfluence.plugins.emoji import emoji as emoji_plugin
 
 
 class Page(object):
@@ -120,6 +121,7 @@ def get_pages_from_directory(
     use_gitignore: bool = True,
     enable_relative_links: bool = False,
     skip_subtrees_wo_markdown: bool = False,
+    enable_emoji: bool = True,
 ) -> List[Page]:
     """
     Collect a list of markdown files recursively under the file_path directory.
@@ -234,6 +236,7 @@ def get_pages_from_directory(
                 strip_header=strip_header,
                 remove_text_newlines=remove_text_newlines,
                 enable_relative_links=enable_relative_links,
+                enable_emoji=enable_emoji,
             )
             processed_page.parent_title = parent_page_title
             processed_pages.append(processed_page)
@@ -252,6 +255,7 @@ def get_page_data_from_file_path(
     strip_header: bool = False,
     remove_text_newlines: bool = False,
     enable_relative_links: bool = False,
+    enable_emoji: bool = True,
 ) -> Page:
     if not isinstance(file_path, Path):
         file_path = Path(file_path)
@@ -270,6 +274,7 @@ def get_page_data_from_file_path(
         strip_header=strip_header,
         remove_text_newlines=remove_text_newlines,
         enable_relative_links=enable_relative_links,
+        enable_emoji=enable_emoji,
     )
 
     if not page.title:
@@ -285,6 +290,7 @@ def get_page_data_from_lines(
     strip_header: bool = False,
     remove_text_newlines: bool = False,
     enable_relative_links: bool = False,
+    enable_emoji: bool = True,
 ) -> Page:
     frontmatter = get_document_frontmatter(markdown_lines)
     if "frontmatter_end_line" in frontmatter:
@@ -295,6 +301,7 @@ def get_page_data_from_lines(
         strip_header=strip_header,
         remove_text_newlines=remove_text_newlines,
         enable_relative_links=enable_relative_links,
+        enable_emoji=enable_emoji,
     )
 
     if "title" in frontmatter:
@@ -315,6 +322,7 @@ def parse_page(
     strip_header: bool = False,
     remove_text_newlines: bool = False,
     enable_relative_links: bool = False,
+    enable_emoji: bool = True,
 ) -> Page:
     renderer = ConfluenceRenderer(
         strip_header=strip_header,
@@ -339,6 +347,8 @@ def parse_page(
         alerts,  # must be after spoiler (both override block_quote)
     ]:
         plugin(confluence_mistune)
+    if enable_emoji:
+        emoji_plugin(confluence_mistune)
     confluence_result = confluence_mistune("".join(markdown_lines))
     if not isinstance(confluence_result, str):
         raise TypeError("Expected string output from Markdown renderer")

mdfluence/plugins/emoji.py

@@ -0,0 +1,59 @@
+"""Mistune plugin for GitHub-style emoji shortcodes.
+
+Converts ``:shortcode:`` patterns to Unicode emoji characters.
+Unknown shortcodes are left unchanged.
+
+Example::
+
+    :smile: → 😄
+    :warning: → ⚠️
+    :unknown: → :unknown: (unchanged)
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mistune import Markdown
+    from mistune.core import BaseRenderer, InlineState
+    from mistune.inline_parser import InlineParser
+
+from mdfluence.plugins.emoji_data import EMOJI_MAP
+
+# Match :shortcode: but not inside URLs (preceded by /) or already-escaped
+EMOJI_PATTERN = r":(?P<emoji_name>[\w+-]+):"
+
+
+def parse_emoji(inline: "InlineParser", m: re.Match[str], state: "InlineState") -> int:
+    """Parse an emoji shortcode token."""
+    name = m.group("emoji_name")
+    if name in EMOJI_MAP:
+        state.append_token(
+            {
+                "type": "emoji",
+                "raw": m.group(0),
+                "attrs": {"name": name},
+                "children": [],
+            }
+        )
+    else:
+        # Unknown shortcode — emit as plain text
+        state.append_token({"type": "text", "raw": m.group(0)})
+    return m.end()
+
+
+def render_emoji(renderer: "BaseRenderer", text: str, name: str) -> str:
+    """Render an emoji shortcode as its Unicode character."""
+    return EMOJI_MAP.get(name, f":{name}:")
+
+
+def emoji(md: "Markdown") -> None:
+    """A mistune plugin to support GitHub-style emoji shortcodes.
+
+    :param md: Markdown instance
+    """
+    md.inline.register("emoji", EMOJI_PATTERN, parse_emoji, before="link")
+    if md.renderer and md.renderer.NAME == "html":
+        md.renderer.register("emoji", render_emoji)