Naming Convention Question: Should a rehype plugin that supports MDX include "mdx" in its name?

[talatkuyuk]

I'm working on a new Rehype plugin related to image elements. The plugin finds <img> Element nodes in the HAST and enhances them with some custom features. In addition to standard HTML <img> elements, it also supports MDX by detecting MdxJsxFlowElement and MdxJsxTextElement nodes that represent image components (MdxJsx elements come from remark-mdx within @mdx-js/mdx). More context about the plugin: it doesn't convert Elements to MdxJsx Elements or visa-versa, just adds some features in place without changing the types.

I'm a bit unsure about the naming convention: Should the plugin name include "mdx" to reflect that it supports MDX syntax, or is it better to keep it more general?.

• rehype-image-xxx
• rehype-mdx-image-xxx

I wonder some users may consider that the plugin is only for mdx content if the name consists "mdx".

Another thought I had: Would it make more sense to split the plugin into two separate ones—one that only supports standard Markdown (markdown image syntax and HTML image elements), and another that also supports MDX?

However, it's also true that if a plugin supports MDX for images, it inherently has to support regular HAST Element nodes as well. So maintaining two separate plugins might be redundant and lead to code duplication.

I'd really appreciate your thoughts and experiences on naming and plugin structure in this kind of scenario. Thanks!

[remcohaszing]

If it works specifically for MDX, for example if it generates MDX specific nodes, I’d name it rehype-mdx-image-xxx.

If it supports hast without MDX, I would name it rehype-image-xxx. It can have special treatment for MDX nodes. I think this best describes your plugin.

I am curious why you need to handle JSX elements.

[talatkuyuk]

Thank you @remcohaszing. The plugin is not specifically for MDX, but covers it and has special treatment for MDX nodes. So, I think also that the name of rehype-image-xxx best describe the plugin.

I am curious why you need to handle JSX elements.

Just wanted to cover html syntax <img> besides markdown syntax ![]() in the beginning (only Elements). Than, I decided to get the same output for both "md" format and "mdx" format. As I progressed with the implementation, I realized that incorporating the MDX format into the process was a mistake, because there are too many edge cases. In the MDX format, all HTML-like content is not actually HTML, but rather MdxJsx elements, and there are many different kinds of expressions used to set their attributes. Covering all of them is quite difficult—if not impossible. At this point, I’ll leave it as-is and won’t try to handle the edge cases of the MDX format. I kept it at a basic level.

[wooorm]

It sounds like no mdx is needed in the plugin name.

As for what the plugin does: it may be good to make it optional. Or configurable.
I could see people write <img src={...} /> because they do not want the same handling as [](...).
But I can also see other people write <Image src={...} /> and also want the same handling as [](...) and <img src={...} />.

[talatkuyuk]

Thank you @wooorm.

The new rehype plugin will parse special directives in the image syntax. If no directive is present, it won’t take any action. This makes the behavior fully optional and configurable as you mentioned. Users will be able to handle both <img src={...} /> and ![...](...) through directives. It’s shaping up to be a promising all-in-one toolkit for image handling.

[talatkuyuk]

Hi @wooorm, the rehype plugin aforementioned has dropped to npm. https://www.npmjs.com/package/rehype-image-toolkit

This is the most comprehensive plugin of my own. I am open to your opinion.