Codeblock does not style properly

[xiaohai-huang]

Have you read the Contributing Guidelines on issues?

• I have 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

VID_20230928_144046.mp4

Bad Format Codeblock

The codeblock does not style properly.

Normal Codeblock

After refreshing the page, all codeblocks become normal.

Reproducible demo

• The page that contains the bug
• docusaurus.config.js

Steps to reproduce

1. Visit a page that contains codeblock. e.g., an example page
2. The codeblock does not style properly if it is the first time to visit the site
3. After refreshing the page, the codeblock becomes normal

Expected behavior

Actual behavior

Your environment

• Public source code: https://github.com/xiaohai-huang/learning-notes/blob/master/docs/Web/JavaScript/01-this.mdx
• Public site URL: https://xiaohai.wiki/docs/Web/JavaScript/this#default-binding
• Docusaurus version used: 2.4.3
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[Chetax]

@xiaohai-huang i want to work on this issue can you please elaborate it and assign me

[xiaohai-huang]

@Chetax I am unable to assign people. What else do you need to know about the issue? Have you tried to visit the page https://xiaohai.wiki/docs/Web/JavaScript/this#default-binding?

[slorber]

Hmm, weird I can also see this behavior on this code block for example

```js title='"use strict" in function definition (contents)' {2,8}
function foo() {
  "use strict";
  console.log(this.a);
}

var a = 2; // is declared in the global scope

foo(); // Uncaught TypeError: Cannot read properties of undefined (reading 'a')
```

https://xiaohai.wiki/docs/Web/JavaScript/this#default-binding

I wonder if it's not related to a React hydration issue, as we had some in v2 (cf this other issue #9208)

Maybe it will work better once you upgrade to Docusaurus v3 (I'll publish a blog post very soon to help you do so).

---

@Chetax it doesn't look like a good first issue. Also we don't assign issues here: you either know how to handle it and submit a draft PR, or you don't and find another issue to work on.

[Chetax]

@slorber ok i will find another issue to work on.

[xiaohai-huang]

Maybe it will work better once you upgrade to Docusaurus v3

@slorber I have upgraded to "3.0.0-beta.0". The issue still exists. 3.0.0-beta.0 version of the page

Here is how I upgrade my site. PR

[xiaohai-huang]

The issue occurs because I created a custom component called JSEditor with "react-simple-code-editor". After removing the component everything become normal.

My JSEditor component https://github.com/xiaohai-huang/learning-notes/blob/upgrade-to-v3/src/components/js-live-code-editor/index.tsx

[Josh-Cena]

Hmmm, then this does not seem like a Docusaurus bug. You can post further details below, but I would encourage you to debug yourself, and if you have questions, you can start a discussion thread instead.

[xiaohai-huang]

Solve this issue by following the instruction from prism-react-renderer | Custom Language Support

import { Highlight, Prism } from "prism-react-renderer";

(typeof global !== "undefined" ? global : window).Prism = Prism
await import("prismjs/components/prism-applescript")
/** or **/
require("prismjs/components/prism-applescript")

[slorber]

Great
Your custom editor was likely causing React hydration issues on both Docusaurus v2 and v3.

Now in v3 those errors are logged to the console so it's easier to identify them.

That's outside the scope of Docusaurus to fix them since it's not our code, but glad you fixed it 👍

[slorber]

@xiaohai-huang by chance can you give us feedback on how easy it was to upgrade to v3?

Do we need to document or clarify anything that you struggled with?

[xiaohai-huang]

@slorber

Things that I struggled with

• Prettier prevent me from modifying some changes. I have to add {/* prettier-ignore */}.
• I don't know which version to set for some packages. e.g., @mdx-js/react, typescript
• I don't know which version to set for @tsconfig/docusaurus.
• I got some strange errors after the upgrade. Solved by doing rm -rf node_modules yarn.lock package-lock.json.
• MDX error message sometimes show the wrong position for the error. And I don't understand the error message see here

Maybe you should add "Make sure to use remark-math >= 5 and rehype-katex >= 6 for Docusaurus v3 (using MDX v2)." to the upgrade guide as well.

[slorber]

Things that I struggled with

Thanks for the feedback!

• Prettier prevent me from modifying some changes. I have to add {/* prettier-ignore */}.

True. Actually Prettier does not "officially" support MDX v2 and might cause troubles sometimes.

Related:

• MDX 3 prettier/prettier#12209
• v3 doc: Prettier hasn't supported MDX v2 or v3 yet #9318

Unfortunately there's nothing we can do apart opting out with prettier ignore or disabling prettier entirely.

Note: I think it works fine most of the time and we shouldn't need to stop recommending the usage of prettier.

Also, it also had shortcomings with MDX v1.

• I don't know which version to set for some packages. e.g., @mdx-js/react, typescript

We have documented it in https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#try-docusaurus-v3-today

TS 5+ and MDX React 2.3+ should work fine.

• I don't know which version to set for @tsconfig/docusaurus.

Also documented: use @docusaurus/tsconfig now

https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#typescript-base-config

• I got some strange errors after the upgrade. Solved by doing rm -rf node_modules yarn.lock package-lock.json.

Any message to share? that would help 😅

After an upgrade, docusaurus clear can help too.

• MDX error message sometimes show the wrong position for the error. And I don't understand the error message see here

True, this is something I'll fix

Error messages are not always easy to understand but we referenced some of them in the blog post here:
https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#common-mdx-problems

Maybe you should add "Make sure to use remark-math >= 5 and rehype-katex >= 6 for Docusaurus v3 (using MDX v2)." to the upgrade guide as well.

Thanks, will do 👍

[slorber]

Regarding the Math/katex upgrades, I think not possible now because this blog post is about preparing your v2 site, and is not full v3 upgrade guide. Apparently the newer math/katex versions are not compatible with mdx v1/Docusaurus v2 so this does not qualify as "preparatory work". We can only upgrade those plugins when doing the v3 upgrade, not ahead of time.

BTW @Josh-Cena you wrote this section about using newer version:
https://docusaurus.io/docs/markdown-features/math-equations#upgrading-rehype-katex-beyond-recommended-version

Have you been able to do that in practice? Because I couldn't make it work 😅

https://stackblitz.com/edit/github-xqy2c4?file=docusaurus.config.js,docs%2Fintro.md,package.json