Ensure Docusaurus v3 (MDX v3) compatibility

[jasikpark]

Ensure Docusaurus v3 (MDX v3) compatibility

[smeng9]

Since we are still in v2 beta yet, shall we consider making v2 release #439 compatible with docusaurus 3?

[justCXQ]

3.0.0-beta.3
It worked for me like this

presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          docRootComponent: "@theme/DocRoot",
          docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

versions:

  "@docusaurus/core": "3.0.1",
    "@docusaurus/preset-classic": "3.0.1",
        "docusaurus-plugin-openapi-docs": "3.0.0-beta.3",
    "docusaurus-theme-openapi-docs": "3.0.0-beta.3",

[jcwillox]

Thanks @jcwillox, have you seen the changes proposed in #648?

Oh look at that, that's very similar to what I did but an even nicer output 👍, should fix the same issue with mdx, I believe the main issue was multiple opening tags on one line.

[Gijsdeman]

3.0.0-beta.1 works for me with Docusaurus 3.0.1, except for the highlighting as @jcwillox noted. For my documentation I also noticed that I had to add json and bash to additionalLanguages to fix the highlighting for these, while this was not needed for previous Docusaurus versions.

With 3.0.0 I get Hook is called outside the <DocProvider>. However, I had this issue with previous versions as well and am not quite sure if it is completely related.

Great work on the quick release!

[jasikpark]

ah, the issue is that markdown surrounded by JSX always generates a paragraph now unless it is inline I believe.

https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#unintended-extra-paragraphs

[jcwillox]

I managed to fix the MDX output with this simple patch, it's very rudimentary but pnpm dlx docusaurus-mdx-checker passed on the ~360 MDX files this plugin generates for our API.

diff --git a/lib/markdown/utils.js b/lib/markdown/utils.js
index 09d5baef75e5f495c19610021771094463e69ce5..19519432acbe3918dc2db90246bf184fee53f2d5 100644
--- a/lib/markdown/utils.js
+++ b/lib/markdown/utils.js
@@ -13,7 +13,7 @@ function create(tag, props) {
     for (const [key, value] of Object.entries(rest)) {
         propString += ` ${key}={${JSON.stringify(value)}}`;
     }
-    return `<${tag}${propString}>${render(children)}</${tag}>`;
+    return `\n<${tag}${propString}>${render(children)}</${tag}>\n`;
 }
 exports.create = create;
 function guard(value, cb) {

However, the UI still crashes with Hook useDoc is called outside the <DocProvider>. when I add docItemComponent: "@theme/ApiItem" to my config. I believe it's due to the breaking changes related to the removal of docLayoutComponent option and the docs theme refactoring https://docusaurus.io/docs/migration/v3#docs-theme-refactoring.

[liamhalemccarty]

I'm stuck. I was getting the same error @lucasassisrosa was getting:

For me, when running against my definition I get these errors:

Error while compiling file docs/api/role-get.api.mdx (Line=37 Column=1)
Details: Expected a closing tag for `<div>` (37:440-37:445) before the end of `paragraph`
---
Error while compiling file docs/api/roles-list.api.mdx (Line=37 Column=1)
Details: Expected a closing tag for `<div>` (37:1035-37:1040) before the end of `paragraph`
---

But fortunately his fix worked for me (thanks @lucasassisrosa!):

When I ran into that it was due to the lack of new line chars and the presence of non-escaped characters. I did replacements following Docusaurus migration guide:

• https://docusaurus.io/docs/migration/v3#bad-usage-of--1
• https://mdxjs.com/migrating/v2/#update-mdx-files

I only did the first of those fixes — I literally just replaced < with /< — because I'm not sure what the second link means I should do.

But now I'm getting an error I don't know how to fix:

ERROR
Objects are not valid as a React child (found: object with keys {}). If you meant to render a collection of children, use an array instead.
    at throwOnInvalidObjectType (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:14888:9)
    at createChild (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:15140:7)
    at reconcileChildrenArray (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:15405:25)
    at reconcileChildFibers (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:15822:16)
    at reconcileChildren (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:19163:28)
    at updateHostComponent (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:19920:3)
    at beginWork (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:21614:14)
    at HTMLUnknownElement.callCallback (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4165:14)
    at Object.invokeGuardedCallbackDev (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4214:16)
    at invokeGuardedCallback (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4278:31)

More specifically, that first part is sometimes Objects are not valid as a React child (found: object with keys {textAlign, marginBottom}). So it seems that code like \<div style={{"textAlign":"left","marginLeft":"1rem"}}> is now problematic.

Does anyone know how I can fix this?

[rsmets]

I am getting the same error as @kjeom

#654 (comment)

Running these versions:

  "dependencies": {
    "@docusaurus/core": "^2.3.1",
    "@docusaurus/preset-classic": "^2.3.1",
    "@docusaurus/theme-live-codeblock": "2.3.1",
    "@mdx-js/react": "^1.6.21",
    "docusaurus-plugin-openapi-docs": "^2.0.2",
    "docusaurus-theme-openapi-docs": "^2.0.2",

So does not seem to be only a 3.0.0 issue.

[lucasassisrosa]

For me, when running against my definition I get these errors:

Error while compiling file docs/api/role-get.api.mdx (Line=37 Column=1)
Details: Expected a closing tag for `<div>` (37:440-37:445) before the end of `paragraph`
---
Error while compiling file docs/api/roles-list.api.mdx (Line=37 Column=1)
Details: Expected a closing tag for `<div>` (37:1035-37:1040) before the end of `paragraph`
---

When I ran into that it was due to the lack of new line chars and the presence of non-escaped characters. I did replacements following Docusaurus migration guide:

• https://docusaurus.io/docs/migration/v3#bad-usage-of--1
• https://mdxjs.com/migrating/v2/#update-mdx-files

[jcwillox]

I left a comment here #660 (comment), but tldr, everything looks to be working well, except for some syntax highlighting

[Gijsdeman]

After another inspection I noticed that this error occurs because of parameters that are in the description. We use this to, for example, show what endpoints you should use instead of an deprecated endpoint.

I believe this is another issue than is described in #663 (but I might be mistaken). Since the specifications allow you to use curly braces in summaries, descriptions and other places, I think it would be nice if these are escaped by default where possible.

[jk8]

I found that the recent changes in v3 are causing problems in the mermaid diagrams used in the info page description.

v2 (ok):

```mermaid
graph TD
  A --> B
```

v3.0.0-beta.2 (error):

```mermaid
graph TD
  A --> B
```

As a temporary solution, I solved this with a custom markdownGenerators->createInfoPageMD function (replacing > back to >).

Everything else works fine for me with v3.0.0-beta.2.

[kjeom]

When I was testing with following testcases, got these errors

1. dacusaurus/core:3.0.0 - docusaurus-plugin-openapi-docs:3.0.0-beta.1
2. dacusaurus/core:3.0.0 - docusaurus-plugin-openapi-docs:3.0.0-beta.2
3. dacusaurus/core:3.0.1 - docusaurus-plugin-openapi-docs:3.0.0-beta.1
4. dacusaurus/core:3.0.1 - docusaurus-plugin-openapi-docs:3.0.0-beta.2

ERROR
could not find react-redux context value; please ensure the component is wrapped in a <Provider>
    at useReduxContext (webpack-internal:///./node_modules/react-redux/es/hooks/useReduxContext.js:31:11)
    at useSelector (webpack-internal:///./node_modules/react-redux/es/hooks/useSelector.js:136:28)
    at MethodEndpoint (webpack-internal:///./node_modules/docusaurus-theme-openapi-docs/lib/theme/ApiExplorer/MethodEndpoint/index.js:6:932)
    at renderWithHooks (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:16306:18)
    at mountIndeterminateComponent (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:20070:13)
    at beginWork (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:21583:16)
    at HTMLUnknownElement.callCallback (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4165:14)
    at Object.invokeGuardedCallbackDev (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4214:16)
    at invokeGuardedCallback (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4278:31)
    at beginWork$1 (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:27447:7)
ERROR
Hook useScrollController is called outside the <ScrollControllerProvider>. 
ReactContextError
    at useScrollController (webpack-internal:///./node_modules/docusaurus-theme-openapi-docs/node_modules/@docusaurus/theme-common/lib/utils/scrollUtils.js:27:145)
    at useScrollPositionBlocker (webpack-internal:///./node_modules/docusaurus-theme-openapi-docs/node_modules/@docusaurus/theme-common/lib/utils/scrollUtils.js:45:63)
    at TabList (webpack-internal:///./node_modules/docusaurus-theme-openapi-docs/lib/theme/MimeTabs/index.js:20:339)
    at renderWithHooks (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:16306:18)
    at mountIndeterminateComponent (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:20070:13)
    at beginWork (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:21583:16)
    at HTMLUnknownElement.callCallback (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4165:14)
    at Object.invokeGuardedCallbackDev (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4214:16)
    at invokeGuardedCallback (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:4278:31)
    at beginWork$1 (webpack-internal:///./node_modules/react-dom/cjs/react-dom.development.js:27447:7)

[Gijsdeman]

1. dacusaurus/core:3.0.0 - docusaurus-plugin-openapi-docs:3.0.0-beta.1
2. dacusaurus/core:3.0.0 - docusaurus-plugin-openapi-docs:3.0.0-beta.2
3. dacusaurus/core:3.0.1 - docusaurus-plugin-openapi-docs:3.0.0-beta.1
4. dacusaurus/core:3.0.1 - docusaurus-plugin-openapi-docs:3.0.0-beta.2

As far as my testing brought me any difference in version matching between docusaurus and docusaurus-plugin-openapi-docs will cause issues with redux and hooks. I feel like this might be due to slight mismatches in dependencies, comparable to this issue.

You should be able to use the v3.0.0-beta.3 release in combination with docusaurus 3.0.1. It will not work with docusaurus 3.0.0 or any older versions.

[Gijsdeman]

Yep, you're totally right, adding json and bash fixed all the highlighting issues, can't believe I didn't think to do that 😄

I think this issue still persists with v3.0.0-beta.3, and is due to some necessary updates in the theme package. I started refactoring this package but this is a somewhat slow process...

[kjeom]

Is there anyone who have some trouble like the react-redux error?

[kjeom]

I'm also facing same issue as

[Error [ValidationError]: "docLayoutComponent" is not allowed] { _original: { sidebarPath: '/Users/<>/sidebars.js', editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', docLayoutComponent: '@theme/DocPage', docItemComponent: '@theme/ApiItem' }, details: [ { message: '"docLayoutComponent" is not allowed', path: [Array], type: 'object.unknown', context: [Object] } ] }

You should refer #654 (comment)

change the docLayoutComponent to docRootComponent

[lucasassisrosa]

Since we are still in v2 beta yet, shall we consider making v2 release #439 compatible with docusaurus 3?

Yes please. Our team is testing docusaurus-openapi-docs v2 beta with Docusaurus v2.4.3 and at least the mdx files were considered valid when checking against MDX v2 (npx docusaurus-mdx-checker). So I assume most breaking changes should be already figured out?

[rico0610]

Since we are still in v2 beta yet, shall we consider making v2 release #439 compatible with docusaurus 3?

Yes.

[AnaSofia-1294]

Is this already available? I need to use a plugin that requires docusaurus v3, and need react 18.

[jy95]

@jasikpark Well, if you use OpenAPI >= 3.1.0 , you can use my plugin as starting this version, OpenAPI is fully compatible with JSON Schema

[jasikpark]

my plugin

Thank you for the suggestion, but I'm looking to keep the same plugin for the UI and design choices we've made, and because this OpenAPI plugin has purpose built components for showing api definitions. I'm more interested in teaching my users about how to use the API than being specific about the shape of the spec, it's just a nice way to format the documentation.

[jasikpark]

at least the mdx files were considered valid when checking against MDX v2 (npx docusaurus-mdx-checker). So I assume most breaking changes should be already figured out?

For me, when running against my definition I get these errors:

Error while compiling file docs/api/role-get.api.mdx (Line=37 Column=1)
Details: Expected a closing tag for `<div>` (37:440-37:445) before the end of `paragraph`
---
Error while compiling file docs/api/roles-list.api.mdx (Line=37 Column=1)
Details: Expected a closing tag for `<div>` (37:1035-37:1040) before the end of `paragraph`
---

<details style={{"marginBottom":"1rem"}} className={"openapi-markdown__details"} data-collapsed={false} open={true}><summary style={{}}><strong>Query Parameters</strong></summary><div><ul><ParamsItem className={"paramsItem"} param={{"name":"includeCounts","in":"query","description":"If true, return count of total records and current page start and count in metadata","required":false,"schema":{"type":"boolean","default":false}}}></ParamsItem><ParamsItem className={"paramsItem"} param={{"name":"cursor","in":"query","description":"Cursor value at which to start the results, provided in `nextCursor` or `prevCursor` of a prior request","example":"bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19","schema":{"type":"string"}}}></ParamsItem><ParamsItem className={"paramsItem"} param={{"name":"pageSize","in":"query","description":"Number of records to return in each page","required":false,"schema":{"type":"integer","default":25,"maximum":500}}}></ParamsItem></ul></div></details><div><div><ApiTabs><TabItem label={"200"} value={"200"}><div>

Not sure exactly what the issue is..

https://mdxjs.com/playground/:

[sserrata]

Thanks @jcwillox, have you seen the changes proposed in #648?

[sserrata]

Anyone have a chance to try 3.0.0-beta.1?

[Gijsdeman]

After some more testing I ran into an issue with path parameters.

Looking at the Swagger specifications for describing parameters, each parameter is denoted with curly braces. In MDX3 these parameters will be considered to be expressions (see the Docusaurus migration guide for this common issue as well).

Thus, for endpoints with path parameters (in this specific case {type}), you will get the following error:

[sserrata]

After some more testing I ran into an issue with path parameters.

I believe this issue was addressed in v2 #663 and will be ported to v3 soon.

[emilyliu7321]

@sserrata I tested out 3.0.0-beta.1 and mostly everything looks good, thank you! The mdx files all compile and pass npx docusaurus-mdx-checker properly. But when I actually run the code and try to load one of the OpenAPI-to-Docusaurus pages locally, I get this error, despite all components having children components:

Docusaurus error: the <Tabs> component requires at least one <TabItem> children component

I get this error when there are multiple <TabItem> components under <ApiTabs>.

[jcwillox]

3.0.0-beta.1 works for me with Docusaurus 3.0.1, except for the highlighting as @jcwillox noted. For my documentation I also noticed that I had to add json and bash to additionalLanguages to fix the highlighting for these, while this was not needed for previous Docusaurus versions.

Yep, you're totally right, adding json and bash fixed all the highlighting issues, can't believe I didn't think to do that 😄

[kjeom]

1. dacusaurus/core:3.0.0 - docusaurus-plugin-openapi-docs:3.0.0-beta.1
2. dacusaurus/core:3.0.0 - docusaurus-plugin-openapi-docs:3.0.0-beta.2
3. dacusaurus/core:3.0.1 - docusaurus-plugin-openapi-docs:3.0.0-beta.1
4. dacusaurus/core:3.0.1 - docusaurus-plugin-openapi-docs:3.0.0-beta.2

As far as my testing brought me any difference in version matching between docusaurus and docusaurus-plugin-openapi-docs will cause issues with redux and hooks. I feel like this might be due to slight mismatches in dependencies, comparable to this issue.

You should be able to use the v3.0.0-beta.3 release in combination with docusaurus 3.0.1. It will not work with docusaurus 3.0.0 or any older versions.

Thanks for the response. But the issue is still in the combination (v3.0.1 - v3.0.0-beta.3)

[techwritermat]

Hello! Adding docusaurus-theme-openapi-docs@^2.0.2 to my project introduces a dependency to "@docusaurus/theme-common" ">=2.4.1 <=2.4.3". Can we bump this dependency to ^3.0.0?

[lennessyy]

@Gijsdeman The regex for matching curly braces would probably need a little tweaking.

Right now, if there are two pairs of curly braces on a single line, for example:

{key, value} {key, value}

The regex would match them as a single pair of brackets and only escape the first and the last one.

[Gijsdeman]

The regex would match them as a single pair of brackets and only escape the first and the last one.

Good catch, I did not take greedy matching into account. I also realized I could just escape all curly brackets instead of just the ones that surround text, thus I opted for that approach.

[Gijsdeman]

Is there anyone who have some trouble like the react-redux error?

Have you tried deleting your yarn.lock and all node modules and reinstalled everything (with aligned versions of docusaurus-*-openapi-docs and docusaurus)? I only had this error due to version mismatches, but a fresh install of all packages always fixed the issue for me.

[yevhenlisovenko]

Is there anyone who have some trouble like the react-redux error?

Have you tried deleting your yarn.lock and all node modules and reinstalled everything (with aligned versions of docusaurus-*-openapi-docs and docusaurus)? I only had this error due to version mismatches, but a fresh install of all packages always fixed the issue for me.

for me it does not help

package.json

    "@docusaurus/core": "3.0.1",
    "@docusaurus/plugin-google-gtag": "^3.0.1",
    "@docusaurus/preset-classic": "3.0.1",
    "@mdx-js/react": "^3.0.0",
    "clsx": "^2.0.0",
    "docusaurus-plugin-openapi-docs": "^3.0.0-beta.3",
    "docusaurus-theme-openapi-docs": "^3.0.0-beta.3",
    "prism-react-renderer": "^2.3.0",
    "prismjs": "^1.29.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },

still have the error:

ERROR
could not find react-redux context value; please ensure the component is wrapped in a <Provider>
~

[kjeom]

Is there anyone who have some trouble like the react-redux error?

Have you tried deleting your yarn.lock and all node modules and reinstalled everything (with aligned versions of docusaurus-*-openapi-docs and docusaurus)? I only had this error due to version mismatches, but a fresh install of all packages always fixed the issue for me.

Sure, I have deleted and reinstalled all the things with "@docusaurus/core": "3.0.1" and "docusaurus-plugin-openapi-docs": "^3.0.0-beta.3". But it doesn't work with same react-redux error

[kjeom]

I have also checked it working well

• "@docusaurus/core": "3.1.0",
• "@docusaurus/preset-classic": "3.1.0",
• "docusaurus-plugin-openapi-docs": "3.0.0-beta.4",
• "docusaurus-theme-openapi-docs": "3.0.0-beta.4",

[rdluffy]

Hello i m still facing the issue, with those versions.

[dakshika]

I'm also facing same issue as

[Error [ValidationError]: "docLayoutComponent" is not allowed] { _original: { sidebarPath: '/Users/<>/sidebars.js', editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', docLayoutComponent: '@theme/DocPage', docItemComponent: '@theme/ApiItem' }, details: [ { message: '"docLayoutComponent" is not allowed', path: [Array], type: 'object.unknown', context: [Object] } ] }

[maxweisel]

I have also checked it working well

• "@docusaurus/core": "3.1.0",
• "@docusaurus/preset-classic": "3.1.0",
• "docusaurus-plugin-openapi-docs": "3.0.0-beta.4",
• "docusaurus-theme-openapi-docs": "3.0.0-beta.4",

I'm still hitting the Cause: Expected a closing tag for '<div>' (31:488-31:544) before the end of 'paragraph' with these versions using the openapi-docs example with petstore.yaml.

[dakshika]

I have also checked it working well

• "@docusaurus/core": "3.1.0",
• "@docusaurus/preset-classic": "3.1.0",
• "docusaurus-plugin-openapi-docs": "3.0.0-beta.4",
• "docusaurus-theme-openapi-docs": "3.0.0-beta.4",

I'm still hitting the Cause: Expected a closing tag for '<div>' (31:488-31:544) before the end of 'paragraph' with these versions using the openapi-docs example with petstore.yaml.

Try to cleanup the generated api docs and run. Also check that " themes: ["docusaurus-theme-openapi-docs"], " is on config.js

[dakshika]

I'm also facing same issue as
[Error [ValidationError]: "docLayoutComponent" is not allowed] { _original: { sidebarPath: '/Users/<>/sidebars.js', editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/', docLayoutComponent: '@theme/DocPage', docItemComponent: '@theme/ApiItem' }, details: [ { message: '"docLayoutComponent" is not allowed', path: [Array], type: 'object.unknown', context: [Object] } ] }

You should refer #654 (comment)

change the docLayoutComponent to docRootComponent

Thank you this is working now

[maxweisel]

I have also checked it working well

• "@docusaurus/core": "3.1.0",
• "@docusaurus/preset-classic": "3.1.0",
• "docusaurus-plugin-openapi-docs": "3.0.0-beta.4",
• "docusaurus-theme-openapi-docs": "3.0.0-beta.4",

I'm still hitting the Cause: Expected a closing tag for '<div>' (31:488-31:544) before the end of 'paragraph' with these versions using the openapi-docs example with petstore.yaml.

Try to cleanup the generated api docs and run. Also check that " themes: ["docusaurus-theme-openapi-docs"], " is on config.js

Is there a recommended way to do that? I can go through and remove the accidental newlines in the generated mdx files manually, but it would take ages on the petstore example to do by hand. I've got " themes: ["docusaurus-theme-openapi-docs"], " in my config already.