Docusaurus v3 - Upgrade Support

[slorber]

Docusaurus v3 is around the corner.

Please use this discussion to ask questions so that we can help you upgrade.

Other useful support links

• Docusaurus v3 - Upgrade Support
• Docusaurus v3 - Discord channel #migration-v2-to-v3
• MDX v3 - Upgrade Support
• MDX v3 - Remark/Rehype Plugins Support
• MDX v3 - Discord channel #migration-mdx-v3

Before asking for support

To ask for support, please:

• Check if someone else already asked a similar question
• Create a minimal repro using docusaurus.new
• Give us the fs path of the problematic Markdown file, and the URL pathname to access it
• Spend some time explaining your problem clearly in a structured and concise way
• Paste full, clear error messages and provide screenshots if appropriate

It's not scalable to provide done-for-you support for all Docusaurus users looking to upgrade. Any support request not respecting those constraints will possibly be ignored.

If you want help, you need to invest your own time so that helping you is easy.

Alternatively, you can look for a paid Docusaurus Service Provider to help you.

[johnnyreilly]

Reported an issue here: #9379

EDIT: issue about React hydration errors being reported to the console

[johnnyreilly]

I've been testing out the Docusaurus 3 beta which migrates to MDX 2. I have a couple of rehype plugins that improve core webvitals and serve images with cloudinary. This post walks through the migration for each plugin:

https://johnnyreilly.com/docusaurus-3-how-to-migrate-rehype-plugins

[slorber]

Thanks

Worth posting this in #9337 instead ;)
I suppose most Docusaurus users don't create Rehype plugins. Will link to it in the support intro

[slorber]

About Docs HTML sidebar items disappearing.

This is a bug reported here: #9483
PR: #9531

Should be fixed in canary or upcoming v3.0.1

[mderriey]

Hi there 👋

We upgraded our docs site to Docusaurus v3 and had very few issues thanks to the grat upgrade guide you put together, big kudos!

We're facing a minor issue: admonitions don't render in block quotes in MDX files.
We don't know whether it's due to the MDX upgrade or a change in Docusaurus.
What we do know is this was working in Docusaurus v2.4.3.

Repro:

• StackBlitz: https://stackblitz.com/edit/github-qijbs8?file=docs%2Ftutorial-basics%2Fmarkdown-features.mdx
• When the site is up, open the menu in the top-left corner, expand "Tutorial - Basics", then "Markdown features"
• Go to the "Admonitions" section
• Observe two new admonitions, and the one within the blockquote doesn't render

MDX markup:

:::caution There be dragons

This is the admonition content

:::

> :::caution There be dragons
>
> This is the admonition content
>
> :::

Rendered:

We know the caution admonition has been deprecated in v3 and should be replaced; this code is from a generation tool that we don't own, we'll open a separate issue with it to get it replaced by warning. Replacing caution with warning has the same result.

[slorber]

Thanks!

This bug has already been reported/fixed and will be released in v3.0.1 soon

#9535

[mderriey]

Thanks for coming back to me so quickly @slorber.

I took a look at the issue, and it didn't seem to quite fit my use case.
It's not just spaces and tabs before the admonition, but > characters for a blockquote.

I installed the latest canary (0.0.0-5748 at the time of writing) as a test and the problem persists.

[slorber]

Thanks, I'll add a fix for that quotes case

However you'd rather adopt the markdown directlve syntax directly if you only have a few cases like this, cf #9507 (comment)

This should work:

> :::caution[There be dragons]
>
> This is the admonition content
>
> :::

[slorber]

Fixed in #9570

[mderriey]

Oh right, I hadn't clicked that it was a syntax issue, thanks.

I'll file an issue on the Docusaurus plugin we're using to see if we can move off the caution admonition and use the Markdown directive syntax.

Thanks again!

[homotechsual]

I'm in a bit of a sticky spot - a critical plugin I rely on breaks on v3 but with no errors so I'm at a loss to work out what needs to change to get it working on v3 sites which is holding back some key sites I'd love to get onto v3.

The plugin is: https://github.com/christian-bromann/docusaurus-theme-github-codeblock

Any insights would be gratefully received :-)

[slorber]

Answered in christian-bromann/docusaurus-theme-github-codeblock#49

[RRQM]

Thank you for the long-term updates and support from Docusaurus. My open-source project TouchSocket has been deployed using the Docusaurus website template. It is very beautiful and stable.
When I learned that Docusaurus had released v3, I was very happy and couldn't wait to try a new version. But I encountered a problem upgrading. I have used the method shown in the upgrade document, but the problem has not been resolved yet.
So I came here to request help. I hope you can help me upgrade the website version to v3. I will be very grateful to Docusaurus.

github

https://github.com/RRQM/TouchSocket

doc

https://github.com/RRQM/TouchSocket/tree/master/handbook

[slorber]

Hey

You don't describe the problem? 😅

[RRQM]

I've tried it once, and I've got a lot of errors. It seems impossible to solve.

[RRQM]

If you can, can you please help me PR a branch?

[slorber]

@RRQM what you are asking here is me doing all the work for you. If you want that, you have to pay 😅

I will only help for free if you show me your intention to try your best to solve problems on your own, and that you did your homework of reading carefully the migration guide and giving it a fair try.

If you encounter a specific error, please describe that error and show us the inputs (Markdown file content, git branch, url to look at) that lead to that error.

Only then we'll be able to help for free, one error at a time.