Ensure Docusaurus v3 (MDX v3) compatibility

[jasikpark]

Is your feature request related to a problem?

I would like to easily upgrade my Docusaurus site to v3 in the future (https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3) and I'm uncertain whether this plugin supports Docusaurus v3 / MDX v3

Describe the solution you'd like

Confirmation that the plugin works with the updated framework version

Describe alternatives you've considered

Additional context

Just trying to open a preemptive issue so testing can be started before full release

[IanVS]

I appreciate that everyone's bringing up issues and helping each other here, but I'm very confused as to the current state of the plugin. Is it fully compatible with docusaurus v3, or are the approaches here just workarounds until the plugin is updated to work with v3? @sserrata could you share what you believe to be the current state? That would really help bring clarity to those of us waiting to update.

[sserrata]

Hi everyone, the latest v3 beta is definitely not tested with the latest docusaurus (3.1.1). It's possible a breaking change was introduced in docusaurus, which is quite common for plugins/themes. That said, I would recommend downgrading to either 3.1.0 or 3.0.1. Also, please ensure all docusaurus dependencies are on the same release - this sometimes requires configuring yarn resolutions or manually pinning versions in package.json.

[IanVS]

Great, so it sounds like v3 beta is compatible with at least some versions of docusaurus 3.x? If so, I'd suggest closing out this issue so that people can open separate individual ones if they have problems.

[mrcljx]

Had to make these changes to dedupe dependencies:

    "resolutions": {
        "@docusaurus/core": "3.1.1",
        "@docusaurus/theme-common": "3.1.1",
        "@docusaurus/plugin-content-docs": "3.1.1",
        "@docusaurus/utils": "3.1.1",
        "@docusaurus/utils-validation": "3.1.1",
        "docusaurus-plugin-openapi-docs": "3.0.0-beta.5",
        "react": "18.2.0",
        "react-redux": "7.2.6"
    },

After that I don't see major dupes anymore:

$ ls node_modules/docusaurus*openapi-docs/node_modules/

node_modules/docusaurus-plugin-openapi-docs/node_modules/:
clsx/     fs-extra/

node_modules/docusaurus-theme-openapi-docs/node_modules/:
@types/                        sass-loader/
clsx/                          unified/
hast-util-from-parse5/         unist-util-is/
hast-util-parse-selector/      unist-util-position/
hast-util-raw/                 unist-util-stringify-position/
hast-util-to-parse5/           unist-util-visit/
hastscript/                    unist-util-visit-parents/
html-void-elements/            vfile/
parse5/                        vfile-location/
prism-react-renderer/          vfile-message/
rehype-raw/

Make sure to include these to avoid the Redux Provider error:

docRootComponent: "@theme/DocRoot",
docItemComponent: "@theme/ApiItem",

After that the only issue remaining seems to be hr and br in MDX files:

# For macOS, on Linux you have to remove ''
find ./docs/api -type f -name "*.mdx" -exec sed -i '' 's/<hr>/<hr\/>/g' '{}' +
find ./docs/api -type f -name "*.mdx" -exec sed -i '' 's/<br>/<br\/>/g' '{}' +

[jasikpark]

Great, so it sounds like v3 beta is compatible with at least some versions of docusaurus 3.x? If so, I'd suggest closing out this issue so that people can open separate individual ones if they have problems.

Closing my issue 👍

[wade-liwei]

a custom markdownGenerators->createInfoPageMD function

Could you please give me an example of how to use a custom markdownGenerators->createInfoPageMD function? I do not know how to define the function in the file of docusaurus.config.js.