Swizzle of MDXComponents/Img is not working under v3.1 about docusaurus

[slorber]

Your issue is not super clear, so I'm going to clarify it.

You are using this tag in your Markdown content:

## Heading

<img src={testImg} />

As far as I understand you expect MDXComponents/Img to be the component used to render it.

In practice it is not the case, right?

---

This is working as intended and is a MDX v2 breaking change, documented on our migration guide + the MDX docs/changelog.

We have documented this here:
https://docusaurus.io/docs/migration/v3#lower-case-mdxcomponent-mapping

If you provide a MDX component with key img, it will now only be used to render Markdown images (![alt](src)), and not anymore <img> tags.

However if you provided a mapping for Img, you would be able to write <Img src={testImg} />

Upper-case and lower-case components are now treated differently by MDX, on purpose.

This is briefly documented here as a breaking change of MDX v2:

We now “sandbox” components, for lack of a better name. It means that when you pass a component for h1, it does get used for # hi but not for <h1>hi</h1>

---

Note: technically if you care about restoring the former MDX behavior, you can do it by writing a remark plugin to process the lowercase tag and upper-casing it.

An example:

import type {Transformer} from 'unified';
import type {MdxJsxFlowElement} from 'mdast-util-mdx';

export default function plugin(): Transformer {
  return async (root) => {
    const {visit} = await import('unist-util-visit');
    visit(root, 'mdxJsxFlowElement', (node: MdxJsxFlowElement) => {
      if (node.name === 'img') {
        node.name = 'Img';
      }
    });
  };
}

This is not standard MDX v2+ anymore so it's now your responsibility to figure out if this is a good idea or not.

[slorber]

@t1m0thyj i explained above that indeed the remark plugin is required.

That lowercase mapping will only work with md image syntax, not img tags.

That's not Docusaurus, that's how MDX v2+ works

Edit:I made a case typo in my comment just fixed it.

[t1m0thyj]

@slorber Thanks for providing guidance on how to migrate img components in Docusaurus v3.

However if you provided a mapping for Img, you would be able to write <img src={testImg} />

By "providing a mapping", do you mean the following?

export default {
  ...MDXComponents,
  img: MyCustomImageComponent,
  Img: MyCustomImageComponent,
}

I expected this would register my custom image component for both Markdown images and the img tag. But it didn't work for the img tag until I added the Remark plugin that you suggested. So I have a workaround but am wondering if I'm missing something related to the mapping?