Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
5 of 7 tasks
davidzwa opened this issue Apr 12, 2024 · 8 comments
Closed
5 of 7 tasks
Labels
bug An error in the Docusaurus core causing instability or issues with its execution closed: can't repro This bug is because of some local setup that can't be reproduced.

Comments

@davidzwa
Copy link

Have you read the Contributing Guidelines on issues?

Prerequisites

  • I'm using the latest version of Docusaurus.
  • I have tried the npm run clear or yarn clear command.
  • 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.
  • 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
image

Version 3.0.0
image

Reproducible demo

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

Steps to reproduce

  1. 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.

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

Self-service

  • I'd be willing to fix this bug myself.
@davidzwa davidzwa added bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels Apr 12, 2024
@OzakIOne
Copy link
Collaborator

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
Copy link
Author

davidzwa commented Apr 12, 2024

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
Copy link
Author

davidzwa commented Apr 12, 2024

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
Copy link
Collaborator

slorber commented Apr 12, 2024

This works for me:

CleanShot 2024-04-12 at 12 12 53@2x

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.

CleanShot 2024-04-12 at 12 14 23@2x

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

CleanShot 2024-04-12 at 12 14 36@2x

Then it works

@slorber slorber closed this as not planned Won't fix, can't repro, duplicate, stale Apr 12, 2024
@slorber slorber added closed: can't repro This bug is because of some local setup that can't be reproduced. and removed status: needs triage This issue has not been triaged by maintainers labels Apr 12, 2024
@davidzwa
Copy link
Author

davidzwa commented Apr 14, 2024

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
Copy link
Collaborator

@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
Copy link
Author

davidzwa commented Apr 14, 2024

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
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug An error in the Docusaurus core causing instability or issues with its execution closed: can't repro This bug is because of some local setup that can't be reproduced.
Projects
None yet
Development

No branches or pull requests

4 participants