Fix some MDXv3 migration bugs (#270)

Author: bourdakos1

demo/docusaurus.config.js

@@ -18,6 +18,14 @@ const config = {
   organizationName: "cloud-annotations", // Usually your GitHub org/user name.
   projectName: "docusaurus-openapi", // Usually your repo name.
 
+  markdown: {
+    mdx1Compat: {
+      comments: false,
+      admonitions: false,
+      headingIds: false,
+    },
+  },
+
   presets: [
     [
       "docusaurus-preset-openapi",

demo/examples/petstore.yaml

@@ -38,8 +38,6 @@ info:
     OAuth2 - an open protocol to allow secure authorization in a simple
     and standard method from web, mobile and desktop applications.
 
-    <SecurityDefinitions />
-
   version: 1.0.0
   title: Swagger Petstore YAML
   termsOfService: "http://swagger.io/terms/"
@@ -442,7 +440,7 @@ paths:
         - store
       summary: Find purchase order by ID
       description: >-
-        For valid response try integer IDs with value <= 5 or > 10. Other values
+        For valid response try integer IDs with value \<= 5 or > 10. Other values
         will generated exceptions
       operationId: getOrderById
       parameters:

demo/examples/petstore/_spec_.yaml

@@ -38,8 +38,6 @@ info:
     OAuth2 - an open protocol to allow secure authorization in a simple
     and standard method from web, mobile and desktop applications.
 
-    <SecurityDefinitions />
-
   version: 1.0.0
   title: Swagger Petstore YAML
   termsOfService: "http://swagger.io/terms/"
@@ -442,7 +440,7 @@ paths:
         - store
       summary: Find purchase order by ID
       description: >-
-        For valid response try integer IDs with value <= 5 or > 10. Other values
+        For valid response try integer IDs with value \<= 5 or > 10. Other values
         will generated exceptions
       operationId: getOrderById
       parameters:

packages/docusaurus-plugin-openapi/src/markdown/createDescription.ts

@@ -9,6 +9,5 @@ export function createDescription(description: string | undefined) {
   if (!description) {
     return "";
   }
-  // Replace usages of <= or >= with \<= or \>= to avoid MDX3 parsing issues.
-  return `\n\n${description.replace(/([<>]=?)/g, "\\$1")}\n\n`;
+  return `\n\n${description}\n\n`;
 }

packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts

@@ -242,7 +242,9 @@ export function createSchemaTable({ title, body, type, ...rest }: Props) {
           children: create("th", {
             style: { textAlign: "left" },
             children: [
-              `${title} `,
+              create("span", {
+                children: `${title} `,
+              }),
               ...parseTitleLabel({ required: body.required, type }),
               create("div", {
                 children: createDescription(body.description),

packages/docusaurus-plugin-openapi/src/markdown/createVersionBadge.ts

@@ -15,6 +15,6 @@ export function createVersionBadge(version: string | undefined) {
       className: "theme-doc-version-badge badge badge--secondary",
       children: `Version: ${escape(version)}`,
     }),
-    `\n\n`,
+    `\n`,
   ]);
 }

packages/docusaurus-plugin-openapi/src/markdown/utils.ts

@@ -17,9 +17,7 @@ export function create(tag: string, props: Props): string {
     propString += ` ${key}={${JSON.stringify(value)}}`;
   }
 
-  return `<${tag}${propString}>
-  ${render(children)}
-</${tag}>`;
+  return `<${tag}${propString}>${render(children)}</${tag}>`;
 }
 
 export function guard<T>(
@@ -34,8 +32,21 @@ export function guard<T>(
 }
 
 export function render(children: Children): string {
-  if (Array.isArray(children)) {
-    return children.filter((c) => c !== undefined).join("\n");
+  const res = Array.isArray(children)
+    ? children.filter((c) => c !== undefined).join("\n")
+    : children ?? "";
+
+  const isMultiline = res.split("\n").length > 1;
+
+  // It is not possible to wrap “blocks” if text and tags are on the same line,
+  // but the corresponding tags are on different lines. This can accidentally
+  // happen if the rendered item has multiple lines. To be safe, we pad with
+  // newlines.
+  //
+  // See: https://mdxjs.com/migrating/v2/#jsx
+  if (isMultiline) {
+    return "\n" + res + "\n";
   }
-  return children ?? "";
+
+  return res;
 }