Response descriptions in v4.2.0 not processing MDX

[Preston-Landers]

Describe the bug

After updating my project to Docusaurus-OpenAPI-Docs v4.2.0 (from 4.1.0), when I build and view my docs, any Markdown / MDX processing is not happening in the Responses description - admonitions, back-tick quoting, etc doesn't render there.

Expected behavior

I have MDX stuff in a Response description:

CreateItemResponse:
  description: |
    The item was successfully created.

    This is a minimal response that indicates whether the request was successful and provides the
    URI of the created item. To retrieve additional details or the full item, you may need to make
    additional requests.

    :::info

    See the `Location` header for the URL of the new item,
    as well as the `X-Item-Id` and `X-Item-Table` headers for the ID and
    table name of the new item.

    :::

  type: object
  properties:
    ...

projects-collection:
  post:
    ...
    responses:
      "201":
        description:
          $ref: "../../schemas/create_item_response_schema.yaml#/CreateItemResponse/description"
        content:
          application/json:
            schema:
              $ref: "../../schemas/create_item_response_schema.yaml#/CreateItemResponse"
        headers:
          $ref: "../../headers/create_item_headers.yaml#/CreateItemHeaders"

The admonition and the backtick words should render out correctly, but I'm just seeing the raw text as shown below.

As far as I can tell in my limited testing so far, it's only happening in Response descriptions. No obvious signs of warnings or errors in the build.

Current behavior

The admonitions should be rendered correctly as shown in the screenshots.

Screenshots

Not working:

Working:

Context

Only happened after updating to 4.2.0.

[ahelmy]

Hi @Preston-Landers,
I checked it and it is working on version 4.2.0, would you check that npm updated your project correctly?

[Preston-Landers]

Hi @ahelmy - I am using yarn. I tried a few things such as a deleting node_modules and yarn.lock (then running yarn install) and it still happens. I did notice a few things, though.

One is that if I simply deleted yarn.lock, and left all other package versions alone including leaving this plugin at 4.1.0, then ran yarn install and did a new build, it did update a number of packages, including a lot of @algolia ones and @babel ones, but then my Docusaurus build was getting some errors shown below and refusing to complete.

Then, if allowed all available packages to update (with yarn upgrade-interactive --latest), I was once again getting a passing build but the problem of non-rendering content was still there.

Something else I noticed - I'm seeing this not just in the Responses section, but also in the Request body description.

The last thing I wanted to mention, and probably the most important, is that I noticed that the *.api.mdx files generated by this plugin before and after the update were substantially different in many respects.

In the working version the MDX for the relevant section (talking about the Location) header looks like this:

<ApiTabs
      label={undefined}
      id={undefined}
    >
      <TabItem
        label={"201"}
        value={"201"}
      >
        <div>
          
          
          The item was successfully created.
          
          This is a minimal response that indicates whether the request was successful and provides the
          URI of the created item. To retrieve additional details or the full item, you may need to make
          additional requests.
          
          :::info
          
          See the `Location` header for the URL of the new item,
          as well as the `X-Item-Id` and `X-Item-Table` headers for the ID and
          table name of the new item.
          
          :::
          
          
          
        </div><details
          style={{"textAlign":"left","marginBottom":"1rem"}}
          className={"openapi-markdown__details"}
          data-collapsed={true}
          open={false}
        >
          <summary
            style={{}}
          >
            <strong>
              Response Headers
            </strong>

In the non-working version it looks like this, and overall the file has far fewer MDX components and just a bunch of data crammed in property strings.

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The item was successfully created.\n\nThis is a minimal response that indicates whether the request was successful and provides the\nURI of the created item. To retrieve additional details or the full item, you may need to make\nadditional requests.\n\n:::info\n\nSee the `Location` header for the URL of the new item,\nas well as the `X-Item-Id` and `X-Item-Table` headers for the ID and\ntable name of the new item.\n\n:::\n","content":{"application/json":{"schema":{"description":"The item was successfully created.\n\nThis is a minimal response that indicates whether the request was successful and provides the\nURI of the created item. To retrieve additional details or the full item, you may need to make\nadditional requests.\n\n:::info\n\nSee the `Location` header for the URL of the new item,\nas well as the `X-Item-Id` and `X-Item-Table` headers for the ID and\ntable name of the new item.\n\n:::\n","type":"object","properties":{"response_code":{"type":"integer","description":"The response code.","example":201},"success":{"type":"boolean","description":"Indicates whether the request was successful.","example":true},"uri":{"type":"string","format":"uri","description":"The URI of the created item.","example":"https://example.apps.journyx.com/api/v1/users/123"}},"title":"CreateItemResponse"}}},"headers":{"Location":{"description":"The URL of the newly created object.\n","schema":{"type":"string","format":"uri"}},"X-Item-Id":{"description":"The ID of the newly created object.\n","schema":{"type":"string"}},"X-Item-Table":{"description":"The name of the table where the object was created.\n","schema":{"type":"string"}}}}, ...

The Docusaurus build errors previously mentioned looked like this:

Error: Can't render static file for pathname "/docs/reference/list-system-abilities"
            at generateStaticFile (/home/planders/src/jx/jx-api-docs/node_modules/@docusaurus/core/lib/ssg.js:119:15)
            at runNextTicks (node:internal/process/task_queues:60:5)
            at process.processImmediate (node:internal/timers:454:9)
            at async /home/planders/src/jx/jx-api-docs/node_modules/p-map/index.js:57:22 {
          [cause]: ReactContextError
              at useDoc (server.bundle.js:668219:112)
              at DocItemMetadata (server.bundle.js:669156:153)
              at Uc (server.bundle.js:1007238:44)
              at Xc (server.bundle.js:1007240:253)
              at Z (server.bundle.js:1007246:89)
              at Yc (server.bundle.js:1007249:98)
              at $c (server.bundle.js:1007248:140)
              at Z (server.bundle.js:1007246:345)
              at Yc (server.bundle.js:1007249:98)
              at $c (server.bundle.js:1007248:140) {
            message: 'Hook useDoc is called outside the <DocProvider>. '
          }
        }

[Preston-Landers]

A few more details:

• Apparently this plugin did a bunch of refactoring between version 4.1.0 and 4.2.0, so maybe the massive difference in the api.mdx files is expected.

• I have updated a bunch of other packages my project uses, including Docusaurus core from 3.5.2 to 3.6.0, and as long as I exclude this plugin upgrade from 4.1.0 to 4.2.0, everything works / renders fine.

• After multiple tests I confirmed that just the upgrade from 4.1.0 to 4.2.0 is breaking the rendering of these components (request body description and response body description). I've attached a file which is the diff between package.json and yarn.lock before and after this update.

• I don't see any errors in the web console or anything like that.

• I'm confident that I performed the upgrade correctly, tried resetting both yarn.lock and node_modules multiple times, and as I mentioned above, narrowed it down to this one package change.

Later this week I'll try to build a minimal demonstration repo that shows the issue.

Just to recap, the problem I'm seeing is that Markdown stuff in API request and response descriptions are not rendering correctly and just render as plain text as shown in my screenshots.

diff --git a/package.json b/package.json
index f31f5cd..a7ffba9 100644
--- a/package.json
+++ b/package.json
@@ -34,8 +34,8 @@
     "@easyops-cn/docusaurus-search-local": "0.45.0",
     "@mdx-js/react": "3.1.0",
     "clsx": "2.1.1",
-    "docusaurus-plugin-openapi-docs": "4.1.0",
-    "docusaurus-theme-openapi-docs": "4.1.0",
+    "docusaurus-plugin-openapi-docs": "4.2.0",
+    "docusaurus-theme-openapi-docs": "4.2.0",
     "prism-react-renderer": "2.4.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
diff --git a/yarn.lock b/yarn.lock
index 883b50d..3517dd6 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -4866,31 +4866,7 @@ doctrine@^2.1.0:
   dependencies:
     esutils "^2.0.2"
 
[email protected]:
-  version "4.1.0"
-  resolved "https://registry.yarnpkg.com/docusaurus-plugin-openapi-docs/-/docusaurus-plugin-openapi-docs-4.1.0.tgz#7af4577c05872573365d990ade76767c548cc2a6"
-  integrity sha512-QBoRDFlRGJBKNyHi+4+wuSUlVPF4KrFR5sNyEr/s4eoPPVpaViB/Fwh8DmWbVXvWopNZ0UR1nk1r3Kwls6Qg2Q==
-  dependencies:
-    "@apidevtools/json-schema-ref-parser" "^11.5.4"
-    "@docusaurus/plugin-content-docs" "^3.5.0"
-    "@docusaurus/utils" "^3.5.0"
-    "@docusaurus/utils-validation" "^3.5.0"
-    "@redocly/openapi-core" "^1.10.5"
-    chalk "^4.1.2"
-    clsx "^1.1.1"
-    fs-extra "^9.0.1"
-    json-pointer "^0.6.2"
-    json-schema-merge-allof "^0.8.1"
-    json5 "^2.2.3"
-    lodash "^4.17.20"
-    mustache "^4.2.0"
-    openapi-to-postmanv2 "^4.21.0"
-    postman-collection "^4.4.0"
-    slugify "^1.6.5"
-    swagger2openapi "^7.0.8"
-    xml-formatter "^2.6.1"
-
-docusaurus-plugin-openapi-docs@^4.1.0:
[email protected], docusaurus-plugin-openapi-docs@^4.2.0:
   version "4.2.0"
   resolved "https://registry.yarnpkg.com/docusaurus-plugin-openapi-docs/-/docusaurus-plugin-openapi-docs-4.2.0.tgz#80fc3c3a7eafe6d613b9cd4f42b595641ceaa300"
   integrity sha512-6G8LtpQlb4nCTyDnjkRwxg/oq3WIZ05GCFQFfTqbdiI5D8d9Glya0vp6TF9InEyXtAkc8ozi1HP8It2zEUwNGw==
@@ -4929,18 +4905,19 @@ docusaurus-plugin-sass@^0.2.3:
   dependencies:
     sass-loader "^10.1.1"
 
[email protected]:
-  version "4.1.0"
-  resolved "https://registry.yarnpkg.com/docusaurus-theme-openapi-docs/-/docusaurus-theme-openapi-docs-4.1.0.tgz#beae02d0051aa418ca59c980e3a29d473a821150"
-  integrity sha512-KQ7zs82fTeGrK55VqPvHF9suPYecPhcpoTi0y68/HlCMjMnSl6RN+Q0eLbJr8WwM5r5o96QXObqAx8ot+Dc4BA==
[email protected]:
+  version "4.2.0"
+  resolved "https://registry.yarnpkg.com/docusaurus-theme-openapi-docs/-/docusaurus-theme-openapi-docs-4.2.0.tgz#af65439165f06bddd246ea284812a45f3f6539dd"
+  integrity sha512-TTvrF3mOt9VjDJHu5Ga7jPZyPxhu6//FKTLXJrcGrQ/OOMnojCZZX0KX7zSUL96yF8VlRjwSeM9D90m+dZ9gHw==
   dependencies:
     "@docusaurus/theme-common" "^3.5.0"
     "@hookform/error-message" "^2.0.1"
     "@reduxjs/toolkit" "^1.7.1"
+    allof-merge "^0.6.6"
     clsx "^1.1.1"
     copy-text-to-clipboard "^3.1.0"
     crypto-js "^4.1.1"
-    docusaurus-plugin-openapi-docs "^4.1.0"
+    docusaurus-plugin-openapi-docs "^4.2.0"
     docusaurus-plugin-sass "^0.2.3"
     file-saver "^2.0.5"
     lodash "^4.17.20"
@@ -4956,8 +4933,8 @@ [email protected]:
     react-redux "^7.2.0"
     rehype-raw "^6.1.1"
     remark-gfm "3.0.1"
-    sass "^1.58.1"
-    sass-loader "^13.3.2"
+    sass "^1.80.4"
+    sass-loader "^16.0.2"
     webpack "^5.61.0"
     xml-formatter "^2.6.1"
 
@@ -7409,7 +7386,7 @@ json-schema-compare@^0.2.2:
   dependencies:
     lodash "^4.17.4"
 
[email protected], json-schema-merge-allof@^0.8.1:
[email protected]:
   version "0.8.1"
   resolved "https://registry.yarnpkg.com/json-schema-merge-allof/-/json-schema-merge-allof-0.8.1.tgz#ed2828cdd958616ff74f932830a26291789eaaf2"
   integrity sha512-CTUKmIlPJbsWfzRRnOXz+0MjIqvnleIXwFTzz+t9T86HnYX/Rozria6ZVGLktAU9e+NygNljveP+yxqtQp/Q4w==
@@ -11152,14 +11129,14 @@ sass-loader@^10.1.1:
     schema-utils "^3.0.0"
     semver "^7.3.2"
 
-sass-loader@^13.3.2:
-  version "13.3.3"
-  resolved "https://registry.yarnpkg.com/sass-loader/-/sass-loader-13.3.3.tgz#60df5e858788cffb1a3215e5b92e9cba61e7e133"
-  integrity sha512-mt5YN2F1MOZr3d/wBRcZxeFgwgkH44wVc2zohO2YF6JiOMkiXe4BYRZpSu2sO1g71mo/j16txzUhsKZlqjVGzA==
+sass-loader@^16.0.2:
+  version "16.0.3"
+  resolved "https://registry.yarnpkg.com/sass-loader/-/sass-loader-16.0.3.tgz#17b944fab6702dc7a52c5d2a88cbfa38c39cdc75"
+  integrity sha512-gosNorT1RCkuCMyihv6FBRR7BMV06oKRAs+l4UMp1mlcVg9rWN6KMmUj3igjQwmYys4mDP3etEYJgiHRbgHCHA==
   dependencies:
     neo-async "^2.6.2"
 
-sass@^1.58.1:
+sass@^1.80.4:
   version "1.80.6"
   resolved "https://registry.yarnpkg.com/sass/-/sass-1.80.6.tgz#5d0aa55763984effe41e40019c9571ab73e6851f"
   integrity sha512-ccZgdHNiBF1NHBsWvacvT5rju3y1d/Eu+8Ex6c21nHp2lZGLBEtuwc415QfiI1PJa1TpCo3iXwwSRjRpn2Ckjg==

[Preston-Landers]

I created a relatively minimal repo that demonstrates the problem.

https://github.com/Preston-Landers/docusaurus-openapi-upgrade-bug-demo

Clone and run yarn install, then yarn build && yarn serve.

On the develop branch, on the Create User reference screen, you see something like the working version screenshot in my original post.

Then switch to the demo-of-issue-1012 branch, which only updates the Docusaurus-OpenAPI-Docs plugin to 4.2.0, then run yarn install && yarn build && yarn serve again and you will see a result like the "not working" screenshot.

Hopefully this is enough info to help you reproduce the issue. Thanks!

[ahelmy]

Hi @Preston-Landers ,
Thank you for sharing the repo, I can reproduce it now. I think it is related to generating docs from local OpenAPI spec only not from a file.

Hi @sserrata,
I think it is related to your latest commit https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/979/files

[sserrata]

This is likely due to moving/abstracting the majority of the emitted MDX to higher-level JSX/React components, meaning descriptions are no longer processed as MDX.

After a quick patch/change we can, at least, support GitHub-flavored markdown rendering but full Docusaurus-style MDX support may not be possible unless Docusaurus provides a hook or method for rendering Docusaurus MDX client-side.

[Preston-Landers]

I am not very knowledgeable about either this project or Docusaurus itself, but I'm not sure I understand the comment about possibly needing a hook in Docusaurus, because I was able to update to the latest version of that without issue. It seems like something substantial changed here in this project in how it emits the *.api.mdx files - was that because Docusaurus deprecated the way it was working before and it will stop working at some point in the future?

Not being able to use MDX in request and response descriptions would be a pretty major bummer for my use cases, unfortunately.

[sserrata]

Hi @Preston-Landers, it is a bit of an edge case, but I think I came up with a viable solution for supporting admonitions and potentially other MDX components:

https://docusaurus-openapi-36b86--pr1016-wu0mmkeo.web.app/petstore/add-pet

It basically boiled down to creating a custom remark plugin for handling admonitions and using the Docusaurus @theme/Admonition component for rendering"

#1016