remark-directive compatibility with emoji plugins

[baumandm]

I'd like to use the remark-directive plugin alongside an :emoji: shortcode plugin like remark-gemoji or remark-emoji.

The :emoji: shortcode syntax is ubiquitous thanks to GitHub, Slack, etc., so it's a must-have for me. And the generic directive syntax seems like the most popular solution for adding leaf & block-level elements.

The Problem

The problem is that the remark-directive plugin adds new syntax to the parser that creates textDirective nodes. So a document like this:

:emoji:

Will be parsed into a tree like

{ 
  type: 'paragraph', 
  children: [
    { 
      type: 'textDirective', 
      name: 'emoji', 
      attributes: [Object], 
      children: [Array], 
      position: [Object]
    },
    { 
      type: 'text', 
      value: ':', 
      position: [Object]
    }
  ]
}

This breaks emoji plugins that look for :emoji: shortcodes in text nodes.

Idea A: Backtrack if there's a trailing colon

Based on the proposed specification and the current implementation, a trailing colon isn't allowed in the text directive (this is why it appears as a separate text node). So one solution would be to update the tokenizer in micromark-extension-directive to check for a trailing colon after the name. If found, it would backtrack and fallback to using a text node for the entire shortcode.

One major issue with this idea is that currently, there is no spacing requirements to the text directives. For example:

:a:b

This creates two textDirective nodes, a and b. The above proposal would turn that into a single text node with :a:b. I don't have any ideas on how to avoid this breaking change.

Idea B: Emojis as text directives

I also considered the feasibility of creating a directive-compatible emoji plugin (e.g. remark-directive-emoji) which expects the emoji shortcodes to be converted to textDirective nodes. This plugin could visit textDirective nodes and convert them (if needed) into emojis.

However, with the current parser, the trailing colon is dangling in another text node and cleaning it up would be quite hacky. Alternately it could be parsed into the textDirective name, but that's also a victim of the same ambiguity as mentioned above.

There's also the issue that a textDirective node could be both an emoji shortcode and another directive. This could probably be solved by ensuring the plugins are in the correct priority order.

Any other ideas to get the syntax for both plugins to work together?

[wooorm]

Hmm. Interesting Q. And thanks for such a detailed write up. You’ve answered most of the questions I would’ve otherwise asked!

Here is the big complexity: :\-1: yields 👎.

What what means is that the gemoji shortcodes run after markdown is parsed. It’s not a “construct”. The escapes have been used already. So directives and shortcodes run at different stages...

[wooorm]

Thanks!

So, say we’re using heart_eyes, remark-directive will see it as :heart (a directive) and then leave the rest (_eyes:)...

We could allow _ in directive names? That would run to the end, :heart_eyes| and then see the : there?

Or we could disallow the underscore at the “end” of a directive?

@baumandm what do you prefer?

[baumandm]

I think both allowing _ in directive names but not at the end of the directive makes sense. I think that would avoid issues with emphasis like _:directive_?

[wooorm]

underscore emphasis is already not allowed in words by commonmark, but that’s smart, should be checked indeed

[wooorm]

PR: micromark/micromark-extension-directive#10

[wooorm]

landed: https://github.com/micromark/micromark-extension-directive/releases/tag/1.4.0