search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
57.02k stars 8.59k forks source link

Codeblock does not style properly #9347

Closed xiaohai-huang closed 1 year ago

xiaohai-huang commented 1 year ago

Have you read the Contributing Guidelines on issues?

Prerequisites

Description

https://github.com/facebook/docusaurus/assets/56380096/ab311c1b-6ba8-4dd9-ada7-ebd663399a52

Bad Format Codeblock

The codeblock does not style properly.

image

Normal Codeblock

After refreshing the page, all codeblocks become normal.

image

Reproducible demo

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

image

Actual behavior

image

Your environment

Self-service

Chetax commented 1 year ago

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

xiaohai-huang commented 1 year ago

@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 commented 1 year ago

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 https://github.com/facebook/docusaurus/issues/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 commented 1 year ago

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

xiaohai-huang commented 1 year ago

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

image

image

xiaohai-huang commented 1 year ago

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

image

Josh-Cena commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

@slorber

Things that I struggled with

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 commented 1 year ago

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:

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 commented 1 year ago

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