Updating to @mdx-js/react 3.0.1 causes admonition blocks to stop rendering colored box

davidzwa commented 7 months ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Prerequisites

[X] I'm using the latest version of Docusaurus.
[X] I have tried the npm run clear or yarn clear command.
[X] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
[ ] I have tried creating a repro with https://new.docusaurus.io.
[X] I have read the console error message carefully (if applicable).

Description

When upgrading @mdx-js/react to exactly 3.0.1, all the admonitions in my docs stop showing blocks.

Version 3.0.1

Version 3.0.0

Reproducible demo

https://github.com/fdm-monster/fdm-monster-docs/blob/main/docs/0_installing/windows_service.md

Steps to reproduce

Write a code block like the following
```
:::danger
```

The Windows service installation is deprecated!

Documentation for the Windows service is provided as-is and will not be supported.

:::

2. Update the package @mdx-js/react to 3.0.1 (exactly)
3. See the code block not being formatted anymore.
4. See a warning in console "The tag <admonition> is unrecognized in this browser. If you meant to render a React component, start its name with an uppercase letter."

Warning: The tag is unrecognized in this browser. If you meant to render a React component, start its name with an uppercase letter. at admonition at MDXContent (webpack-internal:///./docs/0_installing/windows_service.md:372:71) at MDXProvider (webpack-internal:///./node_modules/@docusaurus/theme-classic/node_modules/@mdx-js/react/lib/index.js:76:13) at MDXContent (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/MDXContent/index.js:15:25) at div at DocItemContent (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocItem/Content/index.js:27:306) at article at div at div at div at DocItemLayout (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocItem/Layout/index.js:28:750) at HtmlClassNameProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/metadataUtils.js:29:46) at DocProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/doc.js:24:26) at DocItem (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocItem/index.js:17:72) at RouteContextProvider (webpack-internal:///./node_modules/@docusaurus/core/lib/client/routeContext.js:16:60) at LoadableComponent (webpack-internal:///./node_modules/react-loadable/lib/index.js:138:32) at Route (webpack-internal:///./node_modules/react-router/esm/react-router.js:648:29) at Switch (webpack-internal:///./node_modules/react-router/esm/react-router.js:850:29) at div at main at DocRootLayoutMain (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocRoot/Layout/Main/index.js:16:32) at div at div at DocRootLayout (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocRoot/Layout/index.js:18:28) at DocsSidebarProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/docsSidebar.js:19:34) at HtmlClassNameProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/metadataUtils.js:29:46) at DocRoot (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocRoot/index.js:20:143) at RouteContextProvider (webpack-internal:///./node_modules/@docusaurus/core/lib/client/routeContext.js:16:60) at LoadableComponent (webpack-internal:///./node_modules/react-loadable/lib/index.js:138:32) at Route (webpack-internal:///./node_modules/react-router/esm/react-router.js:648:29) at Switch (webpack-internal:///./node_modules/react-router/esm/react-router.js:850:29) at DocsVersionProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/docsVersion.js:17:34) at HtmlClassNameProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/metadataUtils.js:29:46) at DocVersionRootContent (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocVersionRoot/index.js:18:820) at DocVersionRoot at RouteContextProvider (webpack-internal:///./node_modules/@docusaurus/core/lib/client/routeContext.js:16:60) at LoadableComponent (webpack-internal:///./node_modules/react-loadable/lib/index.js:138:32) at Route (webpack-internal:///./node_modules/react-router/esm/react-router.js:648:29) at Switch (webpack-internal:///./node_modules/react-router/esm/react-router.js:850:29) at ErrorBoundary (webpack-internal:///./node_modules/@docusaurus/core/lib/client/exports/ErrorBoundary.js:16:269) at div at NavbarSecondaryMenuDisplayProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/navbarSecondaryMenu/display.js:21:318) at NavbarMobileSidebarProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/navbarMobileSidebar.js:23:414) at NavbarSecondaryMenuContentProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/navbarSecondaryMenu/content.js:16:157) at NavbarProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/navbarUtils.js:22:29) at HtmlClassNameProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/metadataUtils.js:29:46) at PluginHtmlClassNameProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/metadataUtils.js:32:42) at DocsPreferredVersionContextProviderUnsafe (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/docsPreferredVersion.js:33:382) at DocsPreferredVersionContextProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/docsPreferredVersion.js:36:50) at ScrollControllerProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/scrollUtils.js:21:489) at AnnouncementBarProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/announcementBar.js:25:450) at ColorModeProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/colorMode.js:27:1246) at eval (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/reactUtils.js:59:9) at LayoutProvider (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/Layout/Provider/index.js:20:646) at Layout (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/Layout/index.js:26:33) at HtmlClassNameProvider (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/utils/metadataUtils.js:29:46) at DocsRoot (webpack-internal:///./node_modules/@docusaurus/theme-classic/lib/theme/DocsRoot/index.js:18:544) at RouteContextProvider (webpack-internal:///./node_modules/@docusaurus/core/lib/client/routeContext.js:16:60) at LoadableComponent (webpack-internal:///./node_modules/react-loadable/lib/index.js:138:32) at Route (webpack-internal:///./node_modules/react-router/esm/react-router.js:648:29) at Switch (webpack-internal:///./node_modules/react-router/esm/react-router.js:850:29) at Route (webpack-internal:///./node_modules/react-router/esm/react-router.js:648:29) at ClientLifecyclesDispatcher (webpack-internal:///./node_modules/@docusaurus/core/lib/client/ClientLifecyclesDispatcher.js:15:261) at PendingNavigation (webpack-internal:///./node_modules/@docusaurus/core/lib/client/PendingNavigation.js:17:150) at Root (webpack-internal:///./node_modules/@docusaurus/core/lib/client/theme-fallback/Root/index.js:20:16) at BrowserContextProvider (webpack-internal:///./node_modules/@docusaurus/core/lib/client/browserContext.js:21:127) at DocusaurusContextProvider (webpack-internal:///./node_modules/@docusaurus/core/lib/client/docusaurusContext.js:21:496) at ErrorBoundary (webpack-internal:///./node_modules/@docusaurus/core/lib/client/exports/ErrorBoundary.js:16:269) at App (webpack-internal:///./node_modules/@docusaurus/core/lib/client/App.js:29:241) at Router (webpack-internal:///./node_modules/react-router/esm/react-router.js:267:30) at BrowserRouter (webpack-internal:///./node_modules/react-router-dom/esm/react-router-dom.js:58:35) at r (webpack-internal:///./node_modules/react-helmet-async/lib/index.module.js:17:7350)



### Expected behavior

To see the 3.0.1 package not break admonitions. The blocks should be formatted.

### Actual behavior

The admonition blocks do not show properly, irregardless of whether Im creating a .md file or .mdx file.

### Your environment

- Public source code: https://github.com/fdm-monster/fdm-monster-docs/blob/main/docs/0_installing/windows_service.md
- Public site URL: [docs.fdm-monster.net](https://docs.fdm-monster.net/docs/installing/windows_service)
- Docusaurus version used: 3.2.1 and typescript 5.4.5
- Environment name and version (e.g. Chrome 89, Node.js 16.4): Edge 123.0.2420.81 (Official build) (64-bit), NodeJS 18.17.1
- Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 11 Home 23H2

### Self-service

- [ ] I'd be willing to fix this bug myself.

OzakIOne commented 7 months ago

I tried reproducing your issue in a minimal repro and I couldn't reproduce the bug. Am I missing something ?

https://stackblitz.com/edit/github-gesjj3?file=package.json

davidzwa commented 7 months ago

I tried adjusting your stackblitz (completely aligning all versions), but could also not reproduce the problem there.

The difference I see between your and my project is Typescript. You've generated a javascript based docusaurus repro. I've spun up a TS based project locally and I am able to reproduce the problem (a separate project with default tsconfig/docusaurus config).

davidzwa commented 7 months ago

I've checked locally: the docusaurus build output contains the (seemingly unrendered) component in the html page.

<admonition type="danger"><p>hello</p></admonition>

In the stackblitz the html output looks like:

<div class="theme-admonition theme-admonition-danger admonition_xJq3 alert alert--danger">
   <div class="admonitionHeading_Gvgb">
      <span class="admonitionIcon_Rf37">
         <svg viewBox="0 0 12 16">
            <path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path>
         </svg>
      </span>
      danger
   </div>
   <div class="admonitionContent_BuS1">
      <p>hello</p>
   </div>
</div>

At least this seems to explain what causes the warning in the console.

slorber commented 7 months ago

This works for me:

Your website declares "@mdx-js/react": "3.0.0", this leads to your repo having twice that package being loaded, not deduplicated, which is the problem.

Use "@mdx-js/react": "^3.0.1", and ensure there is no duplicate version of that package instead:

Then it works

davidzwa commented 7 months ago

Due to using an automated version management system (Renovate Mend), version pinning is crucial to my repo. Therefore, this solution is not a viable one for me.

I have removed @mdx-js/react from my packages. This gave compilation errors before, but for some reason it does work now.

Josh-Cena commented 7 months ago

@davidzwa You could still use version pinning. All you need to do is to make sure you are using the same version of @mdx-js/react that Docusaurus is using, i.e. 3.0.1 in this case. Or you can ask Renovate to upgrade it for you.

davidzwa commented 7 months ago

The problem is that Renovate did upgrade it before, but I suppose it did not resolve the lock file properly causing two versions to appear. I'm not sure what to do about that and I feel its not a problem to be discussed here.

The truth is: Its annoying that no compilation error is thrown, so a simple docusaurus build action won't cause the PR to be stopped. That's would be an improvement that can still be discussed and therefore this issue is still relevant.

Why does the admonition block not throw a compilation error?

Josh-Cena commented 7 months ago

Because MDX doesn't. 🤷‍♂️ We don't implement Markdown compilation; MDX does. If MDX doesn't tell us something went wrong, there's nothing we can do.

willnode commented 3 months ago

Amazing, I'm stumbled upon this issue and just blown away that I can remove @mdx-js/react from deps. Why it's listed in package.json after doing npx create-docusaurus?

Josh-Cena commented 3 months ago

@willnode because your MDX files will compile to files that import from @mdx-js/react. Some package managers (Yarn PnP and pnpm in certain modes) forbid you from importing things you don't explicitly declare as dependencies yourself. We need to make sure every package manager works out of the box, and you can change it to fit your setup.

facebook / docusaurus