[Planned Feature] Updating Docusaurus 2 to Docusaurus 3

[VladimirLevadnij]

Description

Before setting up Docusaurus to work with multilingual documentation (Issue #42), you must upgrade Docusaurus 2 to Docusaurus 3.

Acceptance Criteria

After updating Docusaurus 2 to Docusaurus 3, nothing will break and for the user the documentation will look the same as it looked before when it was implemented on Docusaurus 2.

[VladimirLevadnij]

1. First, I updated Docusaurus from version 2.0.0-beta.21 to the latest version in branch 2 - version 2.4.3. I tested the work.

2. I tested the compatibility of existing content with version 3 using the npx docusaurus-mdx-checker command. As a result, it was reported that there are no compatibility problems with version 3.

3. I updated Docusaurus to the latest version in branch 3 - version 3.1.1 and established that a newer version could be used, that is, I registered ^3.1.1.

4. I launched Docusaurus 3 and saw problems with increasing the size of buttons and vertical stretching of images.

   

5. This happened because I didn’t want to automatically update everything to the latest versions, I only updated individual packages manually and it seemed like something was missing. I used the command yarn upgrade --latest.

6. After updating all the packages, it also turned out that the way prism-react-renderer works with themes has changed, here is a description of the method for fixing the error https://github.com/FormidableLabs/prism-react-renderer/issues/194

Old code:

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');
const darkTheme = require('prism-react-renderer/themes/vsDark/index.cjs.js')

Now I did this:

const themes = require('prism-react-renderer').themes;
const lightCodeTheme = themes.github;
const darkCodeTheme = themes.dracula;
const darkTheme = themes.vsDark;

7. I carried out new testing, now almost everything began to work well, including images began to be displayed normally, but there was still a problem with the buttons, which were still stretched in height.

   

8. The problem is that the <p> tag is now added when rendering.

In DevTools you can see that it used to work like this:

<div>
    <a href="https://themirrorgdp.itch.io/the-mirror" target="_blank" rel="noopener noreferrer" class="button mirror-success-button button--lg">
        Download Directly on Itch
    </a>
</div>

And now like this:

<div>
    <a class="button mirror-success-button button--lg" href="https://themirrorgdp.itch.io/the-mirror">
        <p>Download Directly on Itch</p>
    </ a>
</div>

In DevTools you can see that the <p> tag works like this:

p {
     margin: 0 0 var(--ifm-paragraph-margin-bottom);
}

9. To correct this situation, I applied this solution, I don’t know how much this is the best solution, for me it’s just the fastest and most logical solution :blush:

.mirror-success-button p {
   margin: 0;
}

11. I checked, everything was fine with the button.

The work is not finished yet.

1. In DevTools you can see that now in Docusaurus 3 the target="_blank" attribute is not substituted by default and links do not open in a new window by default.

2. There is also a problem with the build; errors appear when performing yarn build.

Error: Docusaurus server-side rendering could not render static page with path /docs/script/getting_started because of error: Expected component TabItem to be defined: you likely forgot to import, pass, or provide it.

3. Even after assembly, you need to check how the search works, because the search does not work in development mode.

[VladimirLevadnij]

It was one of those sad stories that began with the phrase “Now I’ll quickly update and continue further” :laughing:

[VladimirLevadnij]

As far as I understand, in Docusaurus 2, the TabItem component was automatically available in MDX without the need for explicit import. However, in Docusaurus 3, this component requires explicit import.

Therefore, in all files where TabItem is used, I imported.

import TabItem from '@theme/TabItem';

The build was successful. I ran npm run serve and checked the search, the search is working correctly.

It remains to resolve the issue of opening links in a new window by default.

[VladimirLevadnij]

I continue to figure out why, after upgrading from Docusaurus 2 to Docusaurus 3, our default functionality to open all links in a new window broke. That is, now the target="_blank" attribute is not automatically inserted into the link.

@Kluskey Please tell me, do you remember if you did this functionality yourself in Docusaurus 2 or was it the default behavior in Docusaurus 2 that changed in Docusaurus 3? I need to know this in order to understand what exactly I should investigate, where exactly I need to look for the source of this problem 😊

[VladimirLevadnij]

I’ll add an additional clarification that now in Docusaurus 3, in a new way (without using target="_blank"), only some of the links that are created using HTML work.

Here is a link in Docusaurus 3 that works as it used to work in Docusaurus 2 (the target="_blank" attribute is added)

Here is a link to the site, [click to go](https://site.com)

But such a link in Docusaurus 3 is broken, it does not work as it used to work in Docusaurus 2 (the target="_blank" attribute is NOT added)

Direct download link

<div>
   <a
     className="button mirror-success-button button--lg" href="https://site.com/download">
     Download
   </a>
</div>

[VladimirLevadnij]

You can endlessly look at three things: how the fire burns, how the water flows and how programmers improve the code and fight bugs 😊

Since it has now become clear that in Docusaurus 3, links that are created using the HTML <a> tag do not automatically have the target="_blank" attribute added, but for links that are created using Markdown, all this works as it did before in Docusaurus 2, that is, the target="_blank" attribute is automatically added, I see the action plan as follows:

1. I asked a question on the Docusaurus support Discord server, maybe someone will provide more information on this topic.

2. In order for everything to work as before, in the documentation, in all cases when a link created using the HTML <a> tag is used, I will add the target="_blank" attribute.

   Moreover, in the documentation there is already a practice of using target="_blank" in the HTML <a> tag, for example, in the document mirror-docs/docs/script/getting_started.mdx

   The original idea was inspired by Godot's own visual scripting that was present in the engine prior to version 4.0 before it was <a href="https://godotengine.org/article/godot-4-will-discontinue-visual-scripting" target="_blank" rel="noopener">discontinued</a>.

3. We will notify everyone who works with the documentation that after updating to Docusaurus 3, in cases where a link created using the HTML <a> tag is used, you need to add the target="_blank" attribute if you want the link to open in new window.

4. We will monitor developments and if we receive new information on the topic, we will make the necessary changes. Including gradually exploring the recommendations that were made in this Issue, on a slightly different topic, but the recommendations may be useful for us https://github.com/facebook/docusaurus/issues/9908

@Kluskey Please tell me, do you have any other suggestions or should I implement the plan I wrote above?

[VladimirLevadnij]

I did as I wrote above and sent a Pull Request.