Unwanted emojis generated in API docs

[flynneva]

Problem

Sometimes an API reference matches the name of an emoji (e.g. my_namespace::smile::SomeClass where the emoji :smile: would be displayed like this 😄). This is the undesired behavior.

There are two types of this sort of problem:

1. In generated API docs
2. In "normal" md articles that reference the API directly

Ideally' we would like to "skip" or filter these.

Any ideas?

Possible solutions

• turn off emojis completely
• A custom emoji_generator or emoji_index method that filters them out (either based on filepath or based on the in-line match)?

[flynneva]

fyi @facelessuser, any ideas? I'm trying my hand at a custom emoji_generator method now, similar to the custom superfence method I did earlier in the year...but maybe you have a better idea.

[facelessuser]

I do not understand enough about what is trying to be done to answer your question.

You could provide your own functions to the pymdownx.emoji plugin and work within that framework, but again, I don't understand what you are trying to do and why you need a special custom syntax outside of emoji.

If we are talking about escaping, you can certainly use HTML entities as @squidfunk suggested to escape the syntax, and you can also escape the color \:. As you want to use two :: I do not know if this would conflict with what you are trying to do.

[facelessuser]

Re-reading, I see that your syntax has nothing to do with emojis, so it does sound like you just want to escape them. I don't know why I thought you were doing some special Markdown syntax.

[flynneva]

@squidfunk @facelessuser wow you guys are fast! Thanks for the quick replies. I updated my question above to hopefully better describe the problem (unwanted emojis in API references).

As a short-term / hacky solution I've just wrote a quick emoji_generator method that filters all emoji matches to only accept / render the shorthand notation (e.g. :emoji:) and skip it if there are two : on either side (aka an API string).

import logging
import re

from materialx.emoji import to_svg

log = logging.getLogger('mkdocs')


def emoji_generator(index, shortname, alias, uc, alt, title, category, options, md):

  # Get all the md lines with the emoji string
  emoji_lines = [line for line in md.lines if shortname in line]

  # Determine if line is actually an API reference
  pattern = re.compile(f":{shortname}:")
  api_match = [line for line in emoji_lines if pattern.search(line)]

  if api_match:
      return shortname  # not sure what to return here though...
  
  log.info(f'[ EMOJI ] {emoji_lines}')
  return to_svg(index, shortname, alias, uc, alt, title, category, options, md)

A better solution I think would be to modify the emoji regex a bit...not sure how the current implementation works but if we could just require that the regex match does not have a : before and after (using look-aheads / look-behinds) then that would also work and probably be faster at build time too.

[facelessuser]

Well, that seems to be a very specific use case you are unhappy with. I cannot predict all the ways people choose to use emoji and if there are legitimate cases, for instance, let's say someone is using an emoji before a colon.

Check out the example below :smile::

```
some example
```

Personally, if I am using a reference to a code API, I wrap it in code blocks, but there is nothing wrong with not doing so either.

I will note that it isn't uncommon for emoji implementations to not give :: special handling. Let's consider GitHub:

::smile:: --> ::smile::

[squidfunk]

I'm marking this as the answer, since there are several ways explained on how to make this work with the emoji extension, either by putting identifiers in code blocks, or by escaping colons. As @facelessuser pointed out, it's not generally solvable.