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

[smeng9]

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

[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/:

[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

[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 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.

[sserrata]

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

[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.

[sserrata]

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