docusaurus-plugin-openapi-docs 2.1.3 → 3.0.0-beta.10

package/lib/index.js

@@ -15,6 +15,7 @@ const path_1 = __importDefault(require("path"));
 const zlib_1 = __importDefault(require("zlib"));
 const utils_1 = require("@docusaurus/utils");
 const chalk_1 = __importDefault(require("chalk"));
+const json5_1 = __importDefault(require("json5"));
 const mustache_1 = require("mustache");
 const markdown_1 = require("./markdown");
 const openapi_1 = require("./openapi");
@@ -105,17 +106,19 @@ function pluginOpenAPIDocs(context, options) {
             // TODO: figure out better way to set default
             if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
                 const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath, tagGroups);
-                const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
+                let sidebarSliceTemplate = `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";\n\n`;
+                sidebarSliceTemplate += `const sidebar: SidebarsConfig = {{{slice}}};\n\n`;
+                sidebarSliceTemplate += `export default sidebar.apisidebar;\n`;
                 const view = (0, mustache_1.render)(sidebarSliceTemplate, {
-                    slice: JSON.stringify(sidebarSlice),
+                    slice: json5_1.default.stringify({ apisidebar: sidebarSlice }, { space: 2, quote: '"' }),
                 });
-                if (!fs_1.default.existsSync(`${outputDir}/sidebar.js`)) {
+                if (!fs_1.default.existsSync(`${outputDir}/sidebar.ts`)) {
                     try {
-                        fs_1.default.writeFileSync(`${outputDir}/sidebar.js`, view, "utf8");
-                        console.log(chalk_1.default.green(`Successfully created "${outputDir}/sidebar.js"`));
+                        fs_1.default.writeFileSync(`${outputDir}/sidebar.ts`, view, "utf8");
+                        console.log(chalk_1.default.green(`Successfully created "${outputDir}/sidebar.ts"`));
                     }
                     catch (err) {
-                        console.error(chalk_1.default.red(`Failed to write "${outputDir}/sidebar.js"`), chalk_1.default.yellow(err));
+                        console.error(chalk_1.default.red(`Failed to write "${outputDir}/sidebar.ts"`), chalk_1.default.yellow(err));
                     }
                 }
             }
@@ -375,7 +378,7 @@ custom_edit_url: null
         }
         const versionsJson = JSON.stringify(versionsArray, null, 2);
         try {
-            fs_1.default.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+            fs_1.default.writeFileSync(`${outputDir}/versions.json`, versionsJson + "\n", "utf8");
             console.log(chalk_1.default.green(`Successfully created "${outputDir}/versions.json"`));
         }
         catch (err) {
@@ -399,7 +402,7 @@ custom_edit_url: null
         extendCli(cli) {
             cli
                 .command(`gen-api-docs`)
-                .description(`Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`)
+                .description(`Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).`)
                 .usage("<id>")
                 .arguments("<id>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
@@ -447,7 +450,7 @@ custom_edit_url: null
             });
             cli
                 .command(`gen-api-docs:version`)
-                .description(`Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`)
+                .description(`Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled).`)
                 .usage("<id:version>")
                 .arguments("<id:version>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
@@ -522,7 +525,7 @@ custom_edit_url: null
             });
             cli
                 .command(`clean-api-docs`)
-                .description(`Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`)
+                .description(`Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).`)
                 .usage("<id>")
                 .arguments("<id>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
@@ -565,7 +568,7 @@ custom_edit_url: null
             });
             cli
                 .command(`clean-api-docs:version`)
-                .description(`Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`)
+                .description(`Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts (if enabled).`)
                 .usage("<id:version>")
                 .arguments("<id:version>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")

package/lib/markdown/createAuthentication.js

@@ -148,11 +148,12 @@ function createAuthentication(securitySchemes) {
     };
     return (0, utils_1.create)("div", {
         children: [
-            (0, utils_1.create)("h2", {
+            (0, utils_1.create)("Heading", {
                 children: "Authentication",
                 id: "authentication",
-                style: { marginBottom: "1rem" },
-            }),
+                as: "h2",
+                className: "openapi-tabs__heading",
+            }, { inline: true }),
             (0, utils_1.create)("SchemaTabs", {
                 className: "openapi-tabs__security-schemes",
                 children: Object.entries(securitySchemes).map(([schemeKey, schemeObj]) => (0, utils_1.create)("TabItem", {

package/lib/markdown/createCallbacks.js

@@ -25,10 +25,12 @@ function createCallbacks({ callbacks }) {
             (0, utils_1.create)("div", {
                 className: "openapi__divider",
             }),
-            (0, utils_1.create)("h2", {
+            (0, utils_1.create)("Heading", {
                 children: "Callbacks",
                 id: "callbacks",
-            }),
+                as: "h2",
+                className: "openapi-tabs__heading",
+            }, { inline: true }),
             (0, utils_1.create)("OperationTabs", {
                 className: "openapi-tabs__operation",
                 children: callbacksNames.flatMap((name) => {

package/lib/markdown/createContactInfo.js

@@ -28,20 +28,11 @@ function createContactInfo(contact) {
             (0, utils_1.create)("span", {
                 children: [
                     (0, utils_1.guard)(name, () => `${name}: `),
-                    (0, utils_1.guard)(email, () => (0, utils_1.create)("a", {
-                        href: `mailto:${email}`,
-                        children: `${email}`,
-                    })),
+                    (0, utils_1.guard)(email, () => `[${email}](mailto:${email})`),
                 ],
             }),
             (0, utils_1.guard)(url, () => (0, utils_1.create)("span", {
-                children: [
-                    "URL: ",
-                    (0, utils_1.create)("a", {
-                        href: `${url}`,
-                        children: `${url}`,
-                    }),
-                ],
+                children: ["URL: ", `[${url}](mailto:${url})`],
             })),
         ],
     });

package/lib/markdown/createDeprecationNotice.js

@@ -12,8 +12,11 @@ function createAdmonition({ children }) {
     return `:::caution deprecated\n\n${(0, utils_1.render)(children)}\n\n:::`;
 }
 function createDeprecationNotice({ deprecated, description, }) {
-    return (0, utils_1.guard)(deprecated, () => createAdmonition({
-        children: description !== null && description !== void 0 ? description : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
-    }));
+    return (0, utils_1.guard)(deprecated, () => {
+        var _a;
+        return createAdmonition({
+            children: (_a = (0, utils_1.clean)(description)) !== null && _a !== void 0 ? _a : "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
+        });
+    });
 }
 exports.createDeprecationNotice = createDeprecationNotice;

package/lib/markdown/createDescription.js

@@ -9,13 +9,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDescription = void 0;
 const utils_1 = require("./utils");
 function createDescription(description) {
-    if (!description) {
-        return "";
-    }
-    return `\n\n${description
-        .replace(utils_1.greaterThan, "\\>")
-        .replace(utils_1.codeFence, function (match) {
-        return match.replace(/\\>/g, ">");
-    })}\n\n`;
+    return `\n\n${(0, utils_1.clean)(description)}\n\n`;
 }
 exports.createDescription = createDescription;

package/lib/markdown/createHeading.js

@@ -10,10 +10,11 @@ exports.createHeading = void 0;
 const utils_1 = require("./utils");
 function createHeading(heading) {
     return [
-        (0, utils_1.create)("h1", {
+        (0, utils_1.create)("Heading", {
+            children: (0, utils_1.clean)(heading),
+            as: "h1",
             className: "openapi__heading",
-            children: `${heading}`,
-        }),
+        }, { inline: true }),
         `\n\n`,
     ];
 }

package/lib/markdown/createRequestHeader.d.ts

@@ -1 +1 @@
-export declare function createRequestHeader(header: string): string;
+export declare function createRequestHeader(header: string): string[];

package/lib/markdown/createRequestHeader.js

@@ -7,7 +7,16 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRequestHeader = void 0;
+const utils_1 = require("./utils");
 function createRequestHeader(header) {
-    return `## ${header}\n\n`;
+    return [
+        (0, utils_1.create)("Heading", {
+            children: header,
+            id: header.replace(" ", "-").toLowerCase(),
+            as: "h2",
+            className: "openapi-tabs__heading",
+        }, { inline: true }),
+        `\n\n`,
+    ];
 }
 exports.createRequestHeader = createRequestHeader;

package/lib/markdown/createSchema.test.js

@@ -32,7 +32,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const prettier = __importStar(require("prettier"));
 const createSchema_1 = require("./createSchema");
 describe("createNodes", () => {
-    it("should create readable MODs for oneOf primitive properties", () => {
+    it("should create readable MODs for oneOf primitive properties", async () => {
         const schema = {
             type: "object",
             properties: {
@@ -68,6 +68,6 @@ describe("createNodes", () => {
                 },
             },
         };
-        expect((0, createSchema_1.createNodes)(schema, "request").map((md) => prettier.format(md, { parser: "babel" }))).toMatchSnapshot();
+        expect(await Promise.all((0, createSchema_1.createNodes)(schema, "request").map(async (md) => await prettier.format(md, { parser: "babel" })))).toMatchSnapshot();
     });
 });

package/lib/markdown/createVersionBadge.js

@@ -13,7 +13,7 @@ function createVersionBadge(version) {
         (0, utils_1.create)("span", {
             className: "theme-doc-version-badge badge badge--secondary",
             children: `Version: ${escape(version)}`,
-        }),
+        }, { inline: true }),
         `\n\n`,
     ]);
 }

package/lib/markdown/index.js

@@ -39,9 +39,10 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import Markdown from "@theme/Markdown";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import OperationTabs from "@theme/OperationTabs";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
-        (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
+        (0, createHeading_1.createHeading)(title),
         (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
         infoPath && (0, createAuthorization_1.createAuthorization)(infoPath),
         frontMatter.show_extensions
@@ -66,12 +67,13 @@ exports.createApiPageMD = createApiPageMD;
 function createInfoPageMD({ info: { title, version, description, contact, license, termsOfService, logo, darkLogo, }, securitySchemes, downloadUrl, }) {
     return (0, utils_1.render)([
         `import ApiLogo from "@theme/ApiLogo";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
         `import TabItem from "@theme/TabItem";\n`,
         `import Export from "@theme/ApiExplorer/Export";\n\n`,
         (0, createVersionBadge_1.createVersionBadge)(version),
         (0, createDownload_1.createDownload)(downloadUrl),
-        (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
+        (0, createHeading_1.createHeading)(title),
         (0, createLogo_1.createLogo)(logo, darkLogo),
         (0, createDescription_1.createDescription)(description),
         (0, createAuthentication_1.createAuthentication)(securitySchemes),
@@ -91,6 +93,7 @@ function createSchemaPageMD({ schema }) {
         `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
         `import SchemaItem from "@theme/SchemaItem";\n`,
         `import SchemaTabs from "@theme/SchemaTabs";\n`,
+        `import Heading from "@theme/Heading";\n`,
         `import TabItem from "@theme/TabItem";\n\n`,
         (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
         (0, createDescription_1.createDescription)(description),

package/lib/markdown/utils.d.ts

@@ -2,9 +2,15 @@ export type Children = string | undefined | (string | string[] | undefined)[];
 export type Props = Record<string, any> & {
     children?: Children;
 };
-export declare function create(tag: string, props: Props): string;
+export type Options = {
+    inline?: boolean;
+};
+export declare function create(tag: string, props: Props, options?: Options): string;
 export declare function guard<T>(value: T | undefined, cb: (value: T) => Children): string;
 export declare function render(children: Children): string;
 export declare const lessThan: RegExp;
 export declare const greaterThan: RegExp;
 export declare const codeFence: RegExp;
+export declare const curlyBrackets: RegExp;
+export declare const codeBlock: RegExp;
+export declare function clean(value: string | undefined): string;

package/lib/markdown/utils.js

@@ -6,14 +6,21 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
-function create(tag, props) {
+exports.clean = exports.codeBlock = exports.curlyBrackets = exports.codeFence = exports.greaterThan = exports.lessThan = exports.render = exports.guard = exports.create = void 0;
+function create(tag, props, options = {}) {
     const { children, ...rest } = props;
     let propString = "";
     for (const [key, value] of Object.entries(rest)) {
-        propString += ` ${key}={${JSON.stringify(value)}}`;
+        propString += `\n  ${key}={${JSON.stringify(value)}}`;
     }
-    return `<${tag}${propString}>${render(children)}</${tag}>`;
+    let indentedChildren = render(children).replace(/^/gm, "  ");
+    if (options.inline) {
+        propString += `\n  children={${JSON.stringify(children)}}`;
+        indentedChildren = "";
+    }
+    propString += propString ? "\n" : "";
+    indentedChildren += indentedChildren ? "\n" : "";
+    return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
 exports.create = create;
 function guard(value, cb) {
@@ -35,6 +42,27 @@ function render(children) {
 }
 exports.render = render;
 // Regex to selectively URL-encode '>' and '<' chars
-exports.lessThan = /<(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
+exports.lessThan = /<=?(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
 exports.greaterThan = /(?<!(button|code|details|summary|hr|br|span|strong|small|table|thead|tbody|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|bold|a|li|ol|ul|img|svg|div|center|\/|\s|"|'))>/gu;
 exports.codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
+exports.curlyBrackets = /([{|}])/g;
+exports.codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
+function clean(value) {
+    if (!value) {
+        return "";
+    }
+    let sections = value.split(exports.codeBlock);
+    for (let sectionIndex in sections) {
+        if (!sections[sectionIndex].startsWith("`")) {
+            sections[sectionIndex] = sections[sectionIndex]
+                .replace(exports.lessThan, "&lt;")
+                .replace(exports.greaterThan, "&gt;")
+                .replace(exports.codeFence, function (match) {
+                return match.replace(/\\>/g, ">");
+            })
+                .replace(exports.curlyBrackets, "\\$1");
+        }
+    }
+    return sections.join("");
+}
+exports.clean = clean;

package/lib/openapi/utils/utils/openapi.js

@@ -534,7 +534,7 @@ exports.setSecuritySchemePrefix = setSecuritySchemePrefix;
 const shortenHTTPVerb = (verb) => ({
     delete: "del",
     options: "opts",
-}[verb] || verb);
+})[verb] || verb;
 exports.shortenHTTPVerb = shortenHTTPVerb;
 function isRedocExtension(key) {
     const redocExtensions = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "2.1.3",
+  "version": "3.0.0-beta.10",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,18 +28,19 @@
     "watch": "tsc --watch"
   },
   "devDependencies": {
-    "@docusaurus/types": ">=2.4.1 <=2.4.3",
+    "@docusaurus/types": "^3.0.1",
     "@types/fs-extra": "^9.0.13",
     "@types/json-pointer": "^1.0.31",
     "@types/json-schema": "^7.0.9",
     "@types/lodash": "^4.14.176",
-    "@types/mustache": "^4.1.2"
+    "@types/mustache": "^4.1.2",
+    "eslint-plugin-prettier": "^5.0.1"
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@docusaurus/plugin-content-docs": ">=2.4.1 <=2.4.3",
-    "@docusaurus/utils": ">=2.4.1 <=2.4.3",
-    "@docusaurus/utils-validation": ">=2.4.1 <=2.4.3",
+    "@docusaurus/plugin-content-docs": "^3.0.1",
+    "@docusaurus/utils": "^3.0.1",
+    "@docusaurus/utils-validation": "^3.0.1",
     "@paloaltonetworks/openapi-to-postmanv2": "3.1.0-hotfix.1",
     "@paloaltonetworks/postman-collection": "^4.1.0",
     "@redocly/openapi-core": "^1.10.5",
@@ -48,6 +49,7 @@
     "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",
     "slugify": "^1.6.5",
@@ -60,5 +62,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "3bca23ffd3bc51c3d7f4ebb3916e2ece8c823961"
+  "gitHead": "82d70be14358052625d00e637b1eeba52a14b706"
 }

package/src/index.ts

@@ -12,6 +12,7 @@ import zlib from "zlib";
 import type { LoadContext, Plugin } from "@docusaurus/types";
 import { Globby, posixPath } from "@docusaurus/utils";
 import chalk from "chalk";
+import JSON5 from "json5";
 import { render } from "mustache";
 
 import {
@@ -159,21 +160,26 @@ export default function pluginOpenAPIDocs(
           tagGroups
         );
 
-        const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
+        let sidebarSliceTemplate = `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";\n\n`;
+        sidebarSliceTemplate += `const sidebar: SidebarsConfig = {{{slice}}};\n\n`;
+        sidebarSliceTemplate += `export default sidebar.apisidebar;\n`;
 
         const view = render(sidebarSliceTemplate, {
-          slice: JSON.stringify(sidebarSlice),
+          slice: JSON5.stringify(
+            { apisidebar: sidebarSlice },
+            { space: 2, quote: '"' }
+          ),
         });
 
-        if (!fs.existsSync(`${outputDir}/sidebar.js`)) {
+        if (!fs.existsSync(`${outputDir}/sidebar.ts`)) {
           try {
-            fs.writeFileSync(`${outputDir}/sidebar.js`, view, "utf8");
+            fs.writeFileSync(`${outputDir}/sidebar.ts`, view, "utf8");
             console.log(
-              chalk.green(`Successfully created "${outputDir}/sidebar.js"`)
+              chalk.green(`Successfully created "${outputDir}/sidebar.ts"`)
             );
           } catch (err) {
             console.error(
-              chalk.red(`Failed to write "${outputDir}/sidebar.js"`),
+              chalk.red(`Failed to write "${outputDir}/sidebar.ts"`),
               chalk.yellow(err)
             );
           }
@@ -528,7 +534,11 @@ custom_edit_url: null
 
     const versionsJson = JSON.stringify(versionsArray, null, 2);
     try {
-      fs.writeFileSync(`${outputDir}/versions.json`, versionsJson, "utf8");
+      fs.writeFileSync(
+        `${outputDir}/versions.json`,
+        versionsJson + "\n",
+        "utf8"
+      );
       console.log(
         chalk.green(`Successfully created "${outputDir}/versions.json"`)
       );
@@ -564,7 +574,7 @@ custom_edit_url: null
       cli
         .command(`gen-api-docs`)
         .description(
-          `Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).`
+          `Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).`
         )
         .usage("<id>")
         .arguments("<id>")
@@ -622,7 +632,7 @@ custom_edit_url: null
       cli
         .command(`gen-api-docs:version`)
         .description(
-          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).`
+          `Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if enabled).`
         )
         .usage("<id:version>")
         .arguments("<id:version>")
@@ -713,7 +723,7 @@ custom_edit_url: null
       cli
         .command(`clean-api-docs`)
         .description(
-          `Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).`
+          `Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).`
         )
         .usage("<id>")
         .arguments("<id>")
@@ -764,7 +774,7 @@ custom_edit_url: null
       cli
         .command(`clean-api-docs:version`)
         .description(
-          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if enabled).`
+          `Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts (if enabled).`
         )
         .usage("<id:version>")
         .arguments("<id:version>")

package/src/markdown/__snapshots__/createSchema.test.ts.snap

@@ -6,7 +6,7 @@ Array [
   <details style={{}} className={\\"openapi-markdown__details\\"}>
     <summary style={{}}>
       <strong>oneOfProperty</strong>
-      <span style={{ opacity: \\"0.6\\" }}> object</span>
+      <span style={{ opacity: \\"0.6\\" }}>object</span>
     </summary>
     <div style={{ marginLeft: \\"1rem\\" }}></div>
     <div>

package/src/markdown/createAuthentication.ts

@@ -167,11 +167,16 @@ export function createAuthentication(securitySchemes: SecuritySchemeObject) {
 
   return create("div", {
     children: [
-      create("h2", {
-        children: "Authentication",
-        id: "authentication",
-        style: { marginBottom: "1rem" },
-      }),
+      create(
+        "Heading",
+        {
+          children: "Authentication",
+          id: "authentication",
+          as: "h2",
+          className: "openapi-tabs__heading",
+        },
+        { inline: true }
+      ),
       create("SchemaTabs", {
         className: "openapi-tabs__security-schemes",
         children: Object.entries(securitySchemes).map(

package/src/markdown/createCallbacks.ts

@@ -43,10 +43,16 @@ export function createCallbacks({ callbacks }: Props) {
       create("div", {
         className: "openapi__divider",
       }),
-      create("h2", {
-        children: "Callbacks",
-        id: "callbacks",
-      }),
+      create(
+        "Heading",
+        {
+          children: "Callbacks",
+          id: "callbacks",
+          as: "h2",
+          className: "openapi-tabs__heading",
+        },
+        { inline: true }
+      ),
       create("OperationTabs", {
         className: "openapi-tabs__operation",
         children: callbacksNames.flatMap((name) => {

package/src/markdown/createContactInfo.ts

@@ -28,23 +28,12 @@ export function createContactInfo(contact: ContactObject) {
       create("span", {
         children: [
           guard(name, () => `${name}: `),
-          guard(email, () =>
-            create("a", {
-              href: `mailto:${email}`,
-              children: `${email}`,
-            })
-          ),
+          guard(email, () => `[${email}](mailto:${email})`),
         ],
       }),
       guard(url, () =>
         create("span", {
-          children: [
-            "URL: ",
-            create("a", {
-              href: `${url}`,
-              children: `${url}`,
-            }),
-          ],
+          children: ["URL: ", `[${url}](mailto:${url})`],
         })
       ),
     ],

package/src/markdown/createDeprecationNotice.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { guard, Props, render } from "./utils";
+import { clean, guard, Props, render } from "./utils";
 
 function createAdmonition({ children }: Props) {
   return `:::caution deprecated\n\n${render(children)}\n\n:::`;
@@ -23,7 +23,7 @@ export function createDeprecationNotice({
   return guard(deprecated, () =>
     createAdmonition({
       children:
-        description ??
+        clean(description) ??
         "This endpoint has been deprecated and may be replaced or removed in future versions of the API.",
     })
   );

package/src/markdown/createDescription.ts

@@ -5,15 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { greaterThan, codeFence } from "./utils";
+import { clean } from "./utils";
 
 export function createDescription(description: string | undefined) {
-  if (!description) {
-    return "";
-  }
-  return `\n\n${description
-    .replace(greaterThan, "\\>")
-    .replace(codeFence, function (match) {
-      return match.replace(/\\>/g, ">");
-    })}\n\n`;
+  return `\n\n${clean(description)}\n\n`;
 }

package/src/markdown/createHeading.ts

@@ -5,14 +5,19 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { create } from "./utils";
+import { clean, create } from "./utils";
 
 export function createHeading(heading: string) {
   return [
-    create("h1", {
-      className: "openapi__heading",
-      children: `${heading}`,
-    }),
+    create(
+      "Heading",
+      {
+        children: clean(heading),
+        as: "h1",
+        className: "openapi__heading",
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ];
 }

package/src/markdown/createRequestHeader.ts

@@ -5,6 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+import { create } from "./utils";
+
 export function createRequestHeader(header: string) {
-  return `## ${header}\n\n`;
+  return [
+    create(
+      "Heading",
+      {
+        children: header,
+        id: header.replace(" ", "-").toLowerCase(),
+        as: "h2",
+        className: "openapi-tabs__heading",
+      },
+      { inline: true }
+    ),
+    `\n\n`,
+  ];
 }

package/src/markdown/createSchema.test.ts

@@ -11,7 +11,7 @@ import { createNodes } from "./createSchema";
 import { SchemaObject } from "../openapi/types";
 
 describe("createNodes", () => {
-  it("should create readable MODs for oneOf primitive properties", () => {
+  it("should create readable MODs for oneOf primitive properties", async () => {
     const schema: SchemaObject = {
       type: "object",
       properties: {
@@ -48,8 +48,10 @@ describe("createNodes", () => {
       },
     };
     expect(
-      createNodes(schema, "request").map((md: any) =>
-        prettier.format(md, { parser: "babel" })
+      await Promise.all(
+        createNodes(schema, "request").map(
+          async (md: any) => await prettier.format(md, { parser: "babel" })
+        )
       )
     ).toMatchSnapshot();
   });

package/src/markdown/createVersionBadge.ts

@@ -9,10 +9,14 @@ import { create, guard } from "./utils";
 
 export function createVersionBadge(version: string | undefined) {
   return guard(version, (version) => [
-    create("span", {
-      className: "theme-doc-version-badge badge badge--secondary",
-      children: `Version: ${escape(version)}`,
-    }),
+    create(
+      "span",
+      {
+        className: "theme-doc-version-badge badge badge--secondary",
+        children: `Version: ${escape(version)}`,
+      },
+      { inline: true }
+    ),
     `\n\n`,
   ]);
 }

package/src/markdown/index.ts

@@ -77,9 +77,10 @@ export function createApiPageMD({
     `import SchemaItem from "@theme/SchemaItem";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import Markdown from "@theme/Markdown";\n`,
+    `import Heading from "@theme/Heading";\n`,
     `import OperationTabs from "@theme/OperationTabs";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
-    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createHeading(title),
     createMethodEndpoint(method, path),
     infoPath && createAuthorization(infoPath),
     frontMatter.show_extensions
@@ -117,13 +118,14 @@ export function createInfoPageMD({
 }: InfoPageMetadata) {
   return render([
     `import ApiLogo from "@theme/ApiLogo";\n`,
+    `import Heading from "@theme/Heading";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
     `import TabItem from "@theme/TabItem";\n`,
     `import Export from "@theme/ApiExplorer/Export";\n\n`,
 
     createVersionBadge(version),
     createDownload(downloadUrl),
-    createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
+    createHeading(title),
     createLogo(logo, darkLogo),
     createDescription(description),
     createAuthentication(securitySchemes as unknown as SecuritySchemeObject),
@@ -143,6 +145,7 @@ export function createSchemaPageMD({ schema }: SchemaPageMetadata) {
     `import DiscriminatorTabs from "@theme/DiscriminatorTabs";\n`,
     `import SchemaItem from "@theme/SchemaItem";\n`,
     `import SchemaTabs from "@theme/SchemaTabs";\n`,
+    `import Heading from "@theme/Heading";\n`,
     `import TabItem from "@theme/TabItem";\n\n`,
     createHeading(title.replace(lessThan, "<").replace(greaterThan, ">")),
     createDescription(description),

package/src/markdown/utils.ts

@@ -9,15 +9,29 @@ export type Children = string | undefined | (string | string[] | undefined)[];
 
 export type Props = Record<string, any> & { children?: Children };
 
-export function create(tag: string, props: Props): string {
+export type Options = { inline?: boolean };
+
+export function create(
+  tag: string,
+  props: Props,
+  options: Options = {}
+): string {
   const { children, ...rest } = props;
 
   let propString = "";
   for (const [key, value] of Object.entries(rest)) {
-    propString += ` ${key}={${JSON.stringify(value)}}`;
+    propString += `\n  ${key}={${JSON.stringify(value)}}`;
   }
+  let indentedChildren = render(children).replace(/^/gm, "  ");
 
-  return `<${tag}${propString}>${render(children)}</${tag}>`;
+  if (options.inline) {
+    propString += `\n  children={${JSON.stringify(children)}}`;
+    indentedChildren = "";
+  }
+
+  propString += propString ? "\n" : "";
+  indentedChildren += indentedChildren ? "\n" : "";
+  return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
 
 export function guard<T>(
@@ -43,7 +57,29 @@ export function render(children: Children): string {
 
 // Regex to selectively URL-encode '>' and '<' chars
 export const lessThan =
-  /<(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
+  /<=?(?!(=|button|\s?\/button|code|\s?\/code|details|\s?\/details|summary|\s?\/summary|hr|\s?\/hr|br|\s?\/br|span|\s?\/span|strong|\s?\/strong|small|\s?\/small|table|\s?\/table|thead|\s?\/thead|tbody|\s?\/tbody|td|\s?\/td|tr|\s?\/tr|th|\s?\/th|h1|\s?\/h1|h2|\s?\/h2|h3|\s?\/h3|h4|\s?\/h4|h5|\s?\/h5|h6|\s?\/h6|title|\s?\/title|p|\s?\/p|em|\s?\/em|b|\s?\/b|i|\s?\/i|u|\s?\/u|strike|\s?\/strike|bold|\s?\/bold|a|\s?\/a|table|\s?\/table|li|\s?\/li|ol|\s?\/ol|ul|\s?\/ul|img|\s?\/img|svg|\s?\/svg|div|\s?\/div|center|\s?\/center))/gu;
 export const greaterThan =
   /(?<!(button|code|details|summary|hr|br|span|strong|small|table|thead|tbody|td|tr|th|h1|h2|h3|h4|h5|h6|title|p|em|b|i|u|strike|bold|a|li|ol|ul|img|svg|div|center|\/|\s|"|'))>/gu;
 export const codeFence = /`{1,3}[\s\S]*?`{1,3}/g;
+export const curlyBrackets = /([{|}])/g;
+export const codeBlock = /(^```.*[\s\S]*?```$|`[^`].+?`)/gm;
+
+export function clean(value: string | undefined): string {
+  if (!value) {
+    return "";
+  }
+
+  let sections = value.split(codeBlock);
+  for (let sectionIndex in sections) {
+    if (!sections[sectionIndex].startsWith("`")) {
+      sections[sectionIndex] = sections[sectionIndex]
+        .replace(lessThan, "&lt;")
+        .replace(greaterThan, "&gt;")
+        .replace(codeFence, function (match) {
+          return match.replace(/\\>/g, ">");
+        })
+        .replace(curlyBrackets, "\\$1");
+    }
+  }
+  return sections.join("");
+}

package/src/openapi/utils/services/OpenAPIParser.ts

@@ -326,8 +326,8 @@ export class OpenAPIParser {
         const receiverItems = isBoolean(receiver.items)
           ? { items: receiver.items }
           : receiver.items
-          ? (Object.assign({}, receiver.items) as OpenAPISchema)
-          : {};
+            ? (Object.assign({}, receiver.items) as OpenAPISchema)
+            : {};
         const subSchemaItems = isBoolean(items)
           ? { items }
           : (Object.assign({}, items) as OpenAPISchema);

package/src/openapi/utils/utils/openapi.ts

@@ -689,7 +689,7 @@ export const shortenHTTPVerb = (verb) =>
   ({
     delete: "del",
     options: "opts",
-  }[verb] || verb);
+  })[verb] || verb;
 
 export function isRedocExtension(key: string): boolean {
   const redocExtensions = {