How to disable rendering of :emoji:?

[ilg-ul]

I have the following MDX code:

## Definition

<CodeBlock>namespace os::rtos::flags::mode &#123; ... &#125;</CodeBlock>

It is rendered as:

In this context, replacing the :flags: sequence with an icon is definitely not correct.

I searched for 'emoji' in the documentation, but did not find anything relevant.

Is there a way to disable this behaviour?

[slorber]

We use remark-emoji by default: https://github.com/rhysd/remark-emoji

Docusaurus doesn't permit to disable this lib, and from what I see, the library doesn't give you ability to replace only a subset of emojis (it's all or nothing)

Fortunately, you should be able to keep your original text by using a JSX expression instead of Markdown text. Remark-emoji only operates on text nodes to replace emojis in the AST.

[ilg-ul]

... Docusaurus doesn't permit to disable this lib ...

:-(

My goal is to have nice documentation for my (lots of) C++ projects, and in C++ it is impossible to avoid :emoji: like content (this is the namespaces syntax and it is practically impossible to have documentation pages that avoid this syntax).

Even more, the tool I wrote to turn the Doxygen XML files into nice Docusaurus MDX pages is open source, and I would like to make it available to other C++ projects.

Therefore it would be great for Docusaurus to not interfere with the namespace names.

Is it that difficult to add a configuration option to disable the remark-emoji processing? I can postpone the migration of my sites to Docusaurus for a while, if necessary.

[slorber]

Is it that difficult to add a configuration option to disable the remark-emoji processing? I can postpone the migration of my sites to Docusaurus for a while, if necessary.

We release new features on minor versions, and usually try to batch them so that we can announce something meaningful on our v3.9 blog post.

---

If you want to add an option to the MDX loader, although plugin authors often use it, it's not a publicly documented API surface. I think it's fine to add a retrocompatible option to disable emojis in a patch release and consider it as an internal non-breaking refactor to be released asap.

This gives us time to figure out how to expose this option to our public API (global siteConfig.markdown and/or plugin options)

[ilg-ul]

I mean a small patch in packages/docusaurus-mdx-loader/src/processor.ts:

  function getDefaultRemarkPlugins({options}: {options: Options}): MDXPlugin[] {
    const plugins: MDXPlugin[] = [
      [
        headings,
        {anchorsMaintainCase: options.markdownConfig.anchors.maintainCase},
      ],
    ]
    if (!options.disableEmojiSubstitution) {
      plugins.push(emoji)
    }
    plugins.push(toc)
    return plugins;
  }

and a bit more code in the docs, blog and pages content plugins to set options.disableEmojiSubstitution based on a definition in siteConfig.

Would this be acceptable?

[ilg-ul]

@slorber, do you want me to prepare a PR for this?

[slorber]

If this is only modifying the MDX loader API, we could release it in a patch.

and a bit more code in the docs, blog and pages content plugins to set options.disableEmojiSubstitution based on a definition in siteConfig.

If this modifies publicly documented API surface by adding new options, we'll have to wait for v3.9 to release this, alongside other things.

If you need the ability to disable emojis asap, the best option is likely to add a local Docusaurus patch with https://www.npmjs.com/package/patch-package

If you can wait for v3.9, we already have a markdownConfig object passed to the MDX loader. I'm ok to add an API like siteConfig.markdown.emojis = false to disable emojis globally for your site.

---

In general, it's preferable that you submit a design / RFC rather than a PR, so that we can see the overall design before we even start implementing it.

We have various plugins that users may want to disable for various reasons (emojis, toc, directives, gfm...), through various ways (globally through config, globally through a plugin lifecycle, locally through plugin options...).

We don't want to introduce new APIs just to solve your specific use case, and then figure out it's not ideal, or creates config ambiguity for another use case.

And we need to design this properly, taking into account the upcoming APIs we want to adopt for giving more control to users, notably:

• RFC: plugin Markdown lifecycles – configureMarkdownLoader #6370
• Move remarkPlugins to markdown config #5999

[ilg-ul]

If you can wait for v3.9,

I'll try to wait for 3.9. Any rough estimate when it will be available?

we already have a markdownConfig object passed to the MDX loader. I'm ok to add an API like siteConfig.markdown.emojis = false to disable emojis globally for your site.

That would be perfect, thank you! All documentation sites for C++ projects will benefit from it.

Anyway, please let me know if there is anything I can do to help with this issue.

[slorber]

I'll try to wait for 3.9. Any rough estimate when it will be available?

This is likely the last v3 release so I'm trying to figure out the all the v4 future flags I can sneak in: https://docusaurus.io/blog/releases/3.8#future-flags

Can't really tell when it will be ready, but considering v3.8 was just released, it will likely be in 2-4 months until I get everything ready.

But you can still adopt a canary release in the meantime.

That would be perfect, thank you! All documentation sites for C++ projects will benefit from it.

Anyway, please let me know if there is anything I can do to help with this issue.

Great, let's add this API then.

[ilg-ul]

Great, let's add this API then.

Let's add it.

If I have to enter an issue for this, or do anything else, please let me know.