docusaurus-theme-openapi-docs 4.2.0 → 4.3.0

package/lib/theme/ResponseSchema/index.js

@@ -58,13 +58,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importStar(require("react"));
 const BrowserOnly_1 = __importDefault(require("@docusaurus/BrowserOnly"));
 const Details_1 = __importDefault(require("@theme/Details"));
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const MimeTabs_1 = __importDefault(require("@theme/MimeTabs")); // Assume these components exist
 const ResponseExamples_1 = require("@theme/ResponseExamples");
 const Schema_1 = __importDefault(require("@theme/Schema"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const createDescription_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/createDescription");
 const ResponseSchemaComponent = ({ title, body, style }) => {
   if (
     body === undefined ||
@@ -143,7 +143,9 @@ const ResponseSchemaComponent = ({ title, body, style }) => {
                           {
                             style: { marginTop: "1rem", marginBottom: "1rem" },
                           },
-                          (0, createDescription_1.createDescription)(
+                          react_1.default.createElement(
+                            Markdown_1.default,
+                            null,
                             body.description
                           )
                         )

package/lib/theme/Schema/index.js

@@ -17,17 +17,15 @@ const Details_1 = __importDefault(require("@theme/Details"));
 const DiscriminatorTabs_1 = __importDefault(
   require("@theme/DiscriminatorTabs")
 );
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const SchemaItem_1 = __importDefault(require("@theme/SchemaItem"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
 // eslint-disable-next-line import/no-extraneous-dependencies
 const allof_merge_1 = require("allof-merge");
 const clsx_1 = __importDefault(require("clsx"));
-const createDescription_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/createDescription");
 const schema_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/schema");
 const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
-const react_markdown_1 = __importDefault(require("react-markdown"));
-const rehype_raw_1 = __importDefault(require("rehype-raw"));
 // eslint-disable-next-line import/no-extraneous-dependencies
 // const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 const mergeAllOf = (allOf) => {
@@ -38,14 +36,11 @@ const mergeAllOf = (allOf) => {
   return mergedSchemas;
 };
 // Renders string as markdown, useful for descriptions and qualifiers
-const Markdown = ({ text }) => {
+const MarkdownWrapper = ({ text }) => {
   return react_1.default.createElement(
     "div",
     { style: { marginTop: ".5rem", marginBottom: ".5rem" } },
-    react_1.default.createElement(react_markdown_1.default, {
-      children: (0, createDescription_1.createDescription)(text),
-      rehypePlugins: [rehype_raw_1.default],
-    })
+    react_1.default.createElement(Markdown_1.default, null, text)
   );
 };
 const Summary = ({ name, schemaName, schema, required }) => {
@@ -276,11 +271,11 @@ const PropertyDiscriminator = ({
           "div",
           { style: { marginLeft: "1rem" } },
           schema.description &&
-            react_1.default.createElement(Markdown, {
+            react_1.default.createElement(MarkdownWrapper, {
               text: schema.description,
             }),
           (0, schema_1.getQualifierMessage)(discriminator) &&
-            react_1.default.createElement(Markdown, {
+            react_1.default.createElement(MarkdownWrapper, {
               text: (0, schema_1.getQualifierMessage)(discriminator),
             })
         ),
@@ -321,7 +316,10 @@ const PropertyDiscriminator = ({
 const DiscriminatorNode = ({ discriminator, schema, schemaType }) => {
   let discriminatedSchemas = {};
   let inferredMapping = {};
-  const discriminatorProperty = schema.properties[discriminator.propertyName];
+  // default to empty object if no parent-level properties exist
+  const discriminatorProperty = schema.properties
+    ? schema.properties[discriminator.propertyName]
+    : {};
   if (schema.allOf) {
     const mergedSchemas = mergeAllOf(schema);
     if (mergedSchemas.oneOf || mergedSchemas.anyOf) {
@@ -347,15 +345,23 @@ const DiscriminatorNode = ({ discriminator, schema, schemaType }) => {
     }
     const subProperties = subSchema.properties || mergedSubSchema.properties;
     if (subProperties[discriminator.propertyName]) {
-      schema.properties[discriminator.propertyName] = {
-        ...schema.properties[discriminator.propertyName],
-        ...subProperties[discriminator.propertyName],
-      };
-      if (subSchema.required && !schema.required) {
-        schema.required = subSchema.required;
+      if (schema.properties) {
+        schema.properties[discriminator.propertyName] = {
+          ...schema.properties[discriminator.propertyName],
+          ...subProperties[discriminator.propertyName],
+        };
+        if (subSchema.required && !schema.required) {
+          schema.required = subSchema.required;
+        }
+        // Avoid duplicating property
+        delete subProperties[discriminator.propertyName];
+      } else {
+        schema.properties = {};
+        schema.properties[discriminator.propertyName] =
+          subProperties[discriminator.propertyName];
+        // Avoid duplicating property
+        delete subProperties[discriminator.propertyName];
       }
-      // Avoid duplicating property
-      delete subProperties[discriminator.propertyName];
     }
   });
   const name = discriminator.propertyName;
@@ -460,9 +466,11 @@ const SchemaNodeDetails = ({
         "div",
         { style: { marginLeft: "1rem" } },
         schema.description &&
-          react_1.default.createElement(Markdown, { text: schema.description }),
+          react_1.default.createElement(MarkdownWrapper, {
+            text: schema.description,
+          }),
         (0, schema_1.getQualifierMessage)(schema) &&
-          react_1.default.createElement(Markdown, {
+          react_1.default.createElement(MarkdownWrapper, {
             text: (0, schema_1.getQualifierMessage)(schema),
           }),
         react_1.default.createElement(SchemaNode, {

package/lib/theme/SchemaItem/index.js

@@ -12,12 +12,8 @@ var __importDefault =
   };
 Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
-const CodeBlock_1 = __importDefault(require("@theme/CodeBlock"));
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const clsx_1 = __importDefault(require("clsx"));
-const react_markdown_1 = __importDefault(require("react-markdown"));
-const rehype_raw_1 = __importDefault(require("rehype-raw"));
-const remark_gfm_1 = __importDefault(require("remark-gfm"));
-const createDescription_1 = require("../../markdown/createDescription");
 const utils_1 = require("../../markdown/utils");
 const transformEnumDescriptions = (enumDescriptions) => {
   if (enumDescriptions) {
@@ -91,11 +87,7 @@ function SchemaItem(props) {
       return react_1.default.createElement(
         "div",
         { style: { marginTop: ".5rem" } },
-        react_1.default.createElement(react_markdown_1.default, {
-          remarkPlugins: [remark_gfm_1.default],
-          rehypePlugins: [rehype_raw_1.default],
-          children: value,
-        })
+        react_1.default.createElement(Markdown_1.default, null, value)
       );
     }
   );
@@ -103,43 +95,18 @@ function SchemaItem(props) {
     schemaDescription,
     (description) =>
       react_1.default.createElement(
-        "div",
+        react_1.default.Fragment,
         null,
-        react_1.default.createElement(react_markdown_1.default, {
-          children: (0, createDescription_1.createDescription)(description),
-          components: {
-            pre: "div",
-            code({ node, inline, className, children, ...props }) {
-              const match = /language-(\w+)/.exec(className || "");
-              if (inline)
-                return react_1.default.createElement("code", null, children);
-              return !inline && match
-                ? react_1.default.createElement(
-                    CodeBlock_1.default,
-                    { className: className },
-                    children
-                  )
-                : react_1.default.createElement(
-                    CodeBlock_1.default,
-                    null,
-                    children
-                  );
-            },
-          },
-          rehypePlugins: [rehype_raw_1.default],
-        })
+        react_1.default.createElement(Markdown_1.default, null, description)
       )
   );
   const renderQualifierMessage = (0, utils_1.guard)(
     qualifierMessage,
     (message) =>
       react_1.default.createElement(
-        "div",
+        react_1.default.Fragment,
         null,
-        react_1.default.createElement(react_markdown_1.default, {
-          children: (0, createDescription_1.createDescription)(message),
-          rehypePlugins: [rehype_raw_1.default],
-        })
+        react_1.default.createElement(Markdown_1.default, null, message)
       )
   );
   function renderDefaultValue() {
@@ -218,8 +185,7 @@ function SchemaItem(props) {
       react_1.default.createElement(
         "span",
         { className: "openapi-schema__name" },
-        " ",
-        schemaName
+        Array.isArray(schemaName) ? schemaName.join(" | ") : schemaName
       ),
       (nullable || required || deprecated) &&
         react_1.default.createElement("span", {

package/lib/theme/StatusCodes/index.js

@@ -14,10 +14,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
 const ApiTabs_1 = __importDefault(require("@theme/ApiTabs"));
 const Details_1 = __importDefault(require("@theme/Details"));
-const ResponseExamples_1 = require("@theme/ResponseExamples");
+const Markdown_1 = __importDefault(require("@theme/Markdown"));
+const ResponseHeaders_1 = __importDefault(require("@theme/ResponseHeaders"));
 const ResponseSchema_1 = __importDefault(require("@theme/ResponseSchema"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const createDescription_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/createDescription");
 const StatusCodes = ({ label, id, responses }) => {
   if (!responses) return null;
   const codes = Object.keys(responses);
@@ -40,7 +40,11 @@ const StatusCodes = ({ label, id, responses }) => {
               react_1.default.createElement(
                 "div",
                 { style: { marginTop: ".5rem", marginBottom: ".5rem" } },
-                (0, createDescription_1.createDescription)(response.description)
+                react_1.default.createElement(
+                  Markdown_1.default,
+                  null,
+                  response.description
+                )
               )
           ),
           responseHeaders &&
@@ -61,10 +65,9 @@ const StatusCodes = ({ label, id, responses }) => {
                   )
                 ),
               },
-              react_1.default.createElement(
-                ResponseExamples_1.ResponseHeaders,
-                { responseHeaders: responseHeaders }
-              )
+              react_1.default.createElement(ResponseHeaders_1.default, {
+                responseHeaders: responseHeaders,
+              })
             ),
           react_1.default.createElement(ResponseSchema_1.default, {
             title: "Schema",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,26 +28,26 @@
     "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\""
   },
   "devDependencies": {
+    "@docusaurus/theme-common": "^3.5.0",
     "@docusaurus/types": "^3.5.0",
     "@types/crypto-js": "^4.1.0",
     "@types/file-saver": "^2.0.5",
     "@types/lodash": "^4.14.176",
     "concurrently": "^5.2.0",
+    "docusaurus-plugin-openapi-docs": "^4.3.0",
+    "docusaurus-plugin-sass": "^0.2.3",
     "eslint-plugin-prettier": "^5.0.1"
   },
   "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.2.0",
-    "docusaurus-plugin-sass": "^0.2.3",
     "file-saver": "^2.0.5",
     "lodash": "^4.17.20",
-    "node-polyfill-webpack-plugin": "^2.0.1",
+    "node-polyfill-webpack-plugin": "^3.0.0",
     "postman-code-generators": "^1.10.1",
     "postman-collection": "^4.4.0",
     "prism-react-renderer": "^2.3.0",
@@ -61,15 +61,19 @@
     "remark-gfm": "3.0.1",
     "sass": "^1.80.4",
     "sass-loader": "^16.0.2",
+    "unist-util-visit": "^5.0.0",
     "webpack": "^5.61.0",
     "xml-formatter": "^2.6.1"
   },
   "peerDependencies": {
+    "@docusaurus/theme-common": "^3.5.0",
+    "docusaurus-plugin-openapi-docs": "^4.0.0",
+    "docusaurus-plugin-sass": "^0.2.3",
     "react": "^16.8.4 || ^17.0.0 || ^18.0.0",
     "react-dom": "^16.8.4 || ^17.0.0 || ^18.0.0"
   },
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e7295a8aa6f3fab5ccc4f8f9ad0e6c33d785aa16"
+  "gitHead": "e16e2f912a3da02444d1755b6d350deadd62185f"
 }

package/src/theme/ApiExplorer/ApiCodeBlock/Line/_Line.scss

@@ -8,13 +8,6 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   --docusaurus-highlighted-code-line-bg: rgb(100 100 100);
 }
 
-.theme-code-block-highlighted-line {
-  background-color: var(--docusaurus-highlighted-code-line-bg);
-  display: block;
-  margin: 0 calc(-1 * var(--ifm-pre-padding));
-  padding: 0 var(--ifm-pre-padding);
-}
-
 .openapi-explorer__code-block-code-line {
   display: table-row;
   counter-increment: line-count;
@@ -36,11 +29,6 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   opacity: 0.4;
 }
 
-:global(.theme-code-block-highlighted-line)
-  .openapi-explorer__code-block-code-line-number::before {
-  opacity: 0.8;
-}
-
 .openapi-explorer__code-block-code-line-number {
   padding-right: var(--ifm-pre-padding);
 }

package/src/theme/ApiExplorer/Authorization/index.tsx

@@ -48,6 +48,7 @@ function Authorization() {
             <FormItem label="Bearer Token" key={a.key + "-bearer"}>
               <FormTextInput
                 placeholder="Bearer Token"
+                password
                 value={data[a.key].token ?? ""}
                 onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
                   const value = e.target.value;
@@ -69,6 +70,7 @@ function Authorization() {
             <FormItem label="Bearer Token" key={a.key + "-oauth2"}>
               <FormTextInput
                 placeholder="Bearer Token"
+                password
                 value={data[a.key].token ?? ""}
                 onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
                   const value = e.target.value;
@@ -130,6 +132,7 @@ function Authorization() {
             <FormItem label={`${a.key}`} key={a.key + "-apikey"}>
               <FormTextInput
                 placeholder={`${a.key}`}
+                password
                 value={data[a.key].apiKey ?? ""}
                 onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
                   const value = e.target.value;

package/src/theme/ApiExplorer/Body/index.tsx

@@ -14,6 +14,7 @@ import FormSelect from "@theme/ApiExplorer/FormSelect";
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import LiveApp from "@theme/ApiExplorer/LiveEditor";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+import Markdown from "@theme/Markdown";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
 import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -303,7 +304,7 @@ function Body({
           </TabItem>
           {/* @ts-ignore */}
           <TabItem label="Example" value="example">
-            {example.summary && <div>{example.summary}</div>}
+            {example.summary && <Markdown>{example.summary}</Markdown>}
             {exampleBody && (
               <LiveApp
                 action={dispatch}
@@ -341,7 +342,7 @@ function Body({
                 value={example.label}
                 key={example.label}
               >
-                {example.summary && <div>{example.summary}</div>}
+                {example.summary && <Markdown>{example.summary}</Markdown>}
                 {example.body && (
                   <LiveApp action={dispatch} language={language}>
                     {example.body}

package/src/theme/Markdown/Details/_Details.scss

@@ -23,10 +23,13 @@
 
 /* Top-Level Details Caret Styling */
 .openapi-left-panel__container > .openapi-markdown__details > summary::before,
-.openapi-markdown__details.mime > summary::before,
-.openapi-markdown__details.response > summary::before {
+.openapi-markdown__details.mime > summary::before {
   top: 0.1rem;
 }
+
+.openapi-markdown__details.response > summary::before {
+  top: 0.25rem; /* TODO: figure out why this is necessary */
+}
 /* End of Top-Level Details Caret Styling */
 
 .openapi-markdown__details {

package/src/theme/Markdown/index.js

@@ -7,30 +7,172 @@
 
 import React from "react";
 
+import Admonition from "@theme/Admonition";
 import CodeBlock from "@theme/CodeBlock";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkGfm from "remark-gfm";
+
+function remarkAdmonition() {
+  return (tree) => {
+    const openingTagRegex = /^:::(\w+)(?:\[(.*?)\])?\s*$/;
+    const closingTagRegex = /^:::\s*$/;
+    const textOnlyAdmonition = /^:::(\w+)(?:\[(.*?)\])?\s*([\s\S]*?)\s*:::$/;
+
+    const nodes = [];
+    let bufferedChildren = [];
+
+    let insideAdmonition = false;
+    let type = null;
+    let title = null;
+
+    tree.children.forEach((node) => {
+      if (
+        node.type === "paragraph" &&
+        node.children.length === 1 &&
+        node.children[0].type === "text"
+      ) {
+        const text = node.children[0].value.trim();
+        const openingMatch = text.match(openingTagRegex);
+        const closingMatch = text.match(closingTagRegex);
+        const textOnlyAdmonitionMatch = text.match(textOnlyAdmonition);
+
+        if (textOnlyAdmonitionMatch) {
+          const type = textOnlyAdmonitionMatch[1];
+          const title = textOnlyAdmonitionMatch[2]
+            ? textOnlyAdmonitionMatch[2]?.trim()
+            : undefined;
+          const content = textOnlyAdmonitionMatch[3];
+
+          const admonitionNode = {
+            type: "admonition",
+            data: {
+              hName: "Admonition", // Tells ReactMarkdown to replace the node with Admonition component
+              hProperties: {
+                type, // Passed as a prop to the Admonition component
+                title,
+              },
+            },
+            children: [
+              {
+                type: "text",
+                value: content?.trim(), // Trim leading/trailing whitespace
+              },
+            ],
+          };
+          nodes.push(admonitionNode);
+          return;
+        }
+
+        if (openingMatch) {
+          type = openingMatch[1];
+          title = openingMatch[2] || type;
+          insideAdmonition = true;
+          return;
+        }
+
+        if (closingMatch && insideAdmonition) {
+          nodes.push({
+            type: "admonition",
+            data: {
+              hName: "Admonition",
+              hProperties: { type: type, title: title },
+            },
+            children: bufferedChildren,
+          });
+          bufferedChildren = [];
+          insideAdmonition = false;
+          type = null;
+          title = null;
+          return;
+        }
+      }
+
+      if (insideAdmonition) {
+        bufferedChildren.push(node);
+      } else {
+        nodes.push(node);
+      }
+    });
+
+    if (bufferedChildren.length > 0 && type) {
+      nodes.push({
+        type: "admonition",
+        data: {
+          hName: "Admonition",
+          hProperties: { type: type, title: title },
+        },
+        children: bufferedChildren,
+      });
+    }
+    tree.children = nodes;
+  };
+}
+
+function convertAstToHtmlStr(ast) {
+  if (!ast || !Array.isArray(ast)) {
+    return "";
+  }
+
+  const convertNode = (node) => {
+    switch (node.type) {
+      case "text":
+        return node.value;
+      case "element":
+        const { tagName, properties, children } = node;
+
+        // Convert attributes to a string
+        const attrs = properties
+          ? Object.entries(properties)
+              .map(([key, value]) => `${key}="${value}"`)
+              .join(" ")
+          : "";
+
+        // Convert children to HTML
+        const childrenHtml = children ? children.map(convertNode).join("") : "";
+
+        return `<${tagName} ${attrs}>${childrenHtml}</${tagName}>`;
+      default:
+        return "";
+    }
+  };
+
+  return ast.map(convertNode).join("");
+}
 
 function Markdown({ children }) {
   return (
-    <div>
-      <ReactMarkdown
-        children={children}
-        rehypePlugins={[rehypeRaw]}
-        components={{
-          pre: "div",
-          code({ node, inline, className, children, ...props }) {
-            const match = /language-(\w+)/.exec(className || "");
-            if (inline) return <code>{children}</code>;
-            return !inline && match ? (
-              <CodeBlock className={className}>{children}</CodeBlock>
-            ) : (
-              <CodeBlock>{children}</CodeBlock>
-            );
-          },
-        }}
-      />
-    </div>
+    <ReactMarkdown
+      rehypePlugins={[rehypeRaw]}
+      remarkPlugins={[remarkGfm, remarkAdmonition]}
+      components={{
+        pre: (props) => <div {...props} />,
+        code({ node, inline, className, children, ...props }) {
+          const match = /language-(\w+)/.exec(className || "");
+          return match ? (
+            <CodeBlock className={className} language={match[1]} {...props}>
+              {children}
+            </CodeBlock>
+          ) : (
+            <code className={className} {...props}>
+              {children}
+            </code>
+          );
+        },
+        admonition: ({ node, ...props }) => {
+          const type = node.data?.hProperties?.type || "note";
+          const title = node.data?.hProperties?.title || type;
+          const content = convertAstToHtmlStr(node.children);
+          return (
+            <Admonition type={type} title={title} {...props}>
+              <div dangerouslySetInnerHTML={{ __html: content }} />
+            </Admonition>
+          );
+        },
+      }}
+    >
+      {children}
+    </ReactMarkdown>
   );
 }