feat: docusaurus v3 support

[sean-perkins]

Resolves #264

What does this introduce?

Introduces compatibility for Docusaurus v3 and MDX3 to the plugins. These changes are not backwards compatible.

Breaking Changes

Requires Node v18+, React 18+ and Docusaurus v3+

Additional Notes

The MDX3 parser is extremely sensitive to the generated text output in the MDX files. For example you can run just about any generated output from the main branch against https://mdxjs.com/playground/ and see that it fails to parse when the contents are on a single line. The logical changes for parsing account for that formatting requirement and to escape <= and >= text usages, which also fail.

The fs-extra changes aren't required, but limits how much of the infrastructure uses 3rd party dependencies.

We should likely target this release under a new minor and update the README to note which versions support v2 vs. v3.

[netlify[bot]]

✅ Deploy Preview for docusaurus-openapi ready!

Name	Link
🔨 Latest commit
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-openapi/deploys/6578ef9f1b94d8245a22f913
😎 Deploy Preview	https://deploy-preview-266--docusaurus-openapi.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[sean-perkins]

@bourdakos1 netlify will need to be updated to use Node v18 for CI.

I ran the build locally and all unit/e2e tests pass. Let me know if you have questions, this one touched a bit.

[sean-perkins]

Ok I found one site configuration that broke, but I cannot find any reference to a change of behavior in Docusuarus' breaking changes.

If you have a docs site configuration with the same base routeBasePath, the open API routes will fail to load and result in a 404.

For example with a configuration like:

api: {
  path: "examples/petstore.yaml",
  routeBasePath: "petstore/reference",
},
docs: {
  sidebarPath: require.resolve("./sidebars.js"),
  routeBasePath: "petstore",
  // Please change this to your repo.
  editUrl:
    "https://github.com/cloud-annotations/docusaurus-openapi/edit/main/demo/",
},

Navigating to /petstore will render the docs, but navigating to /petstore/reference will result in a 404, even though the debugger at http://localhost:3000/__docusaurus/debug/routes shows the routes are registered at that path.

Previous to Docusaurus v3 you could have your docs at a base path and your openAPI docs generated at a sub path and both would resolve correctly.

Edit:

It looks like we need to assign a higher priority when adding the route 😐 but no indication of what value or why we need to do that. I'll dig a little more before using that solution.

[Kelly-Fisher-27Global]

Any update on getting this merged?

[bourdakos1]

@sean-perkins I updated the node version in netlify, can you try pushing a commit to re-run checks? Manually re-running doesn’t seem to be triggering a build for some reason.

[bourdakos1]

They succeeded in netlify but didn’t reflect here, so I’ll just ignore the errors and merge