docusaurus-plugin-openapi-docs 0.0.0-1089 → 0.0.0-1092

package/README.md

@@ -41,7 +41,7 @@ Key Features:
 
 | Docusaurus OpenAPI Docs | Docusaurus      |
 | ----------------------- | --------------- |
-| 4.0.x (current)         | `3.5.0 - 3.8.1` |
+| 4.x.x (current)         | `3.5.0 - 3.9.2` |
 | 3.0.x (end-of-support)  | `3.0.1 - 3.4.0` |
 | 2.2.3 (legacy)          | `2.4.1 - 2.4.3` |
 | 1.7.3 (end-of-support)  | `2.0.1 - 2.2.0` |
@@ -51,7 +51,7 @@ Key Features:
 Run the following to bootstrap a Docusaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
 
 ```bash
-npx create-docusaurus@3.8.1 my-website --package-manager yarn
+npx create-docusaurus@3.9.2 my-website --package-manager yarn
 ```
 
 > When prompted to select a template choose `Git repository`.
@@ -156,28 +156,29 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 
 `config` can be configured with the following options:
 
-| Name                 | Type      | Default | Description                                                                                                                                 |
-| -------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `specPath`           | `string`  | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files.                 |
-| `outputDir`          | `string`  | `null`  | Desired output path for generated MDX and sidebar files.                                                                                    |
-| `proxy`              | `string`  | `null`  | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. Overrides site-wide `themeConfig.api.proxy` if set. |
-| `template`           | `string`  | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                                  |
-| `infoTemplate`       | `string`  | `null`  | _Optional:_ Customize MDX content for **info** pages only.                                                                                  |
-| `tagTemplate`        | `string`  | `null`  | _Optional:_ Customize MDX content for **tag** pages only.                                                                                   |
-| `schemaTemplate`     | `string`  | `null`  | _Optional:_ Customize MDX content for **schema** pages only.                                                                                |
-| `downloadUrl`        | `string`  | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                                             |
-| `hideSendButton`     | `boolean` | `null`  | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel.                                                    |
-| `showExtensions`     | `boolean` | `null`  | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions.                                                    |
-| `maskCredentials`    | `boolean` | `true`  | _Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security.     |
-| `sidebarOptions`     | `object`  | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                                            |
-| `version`            | `string`  | `null`  | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`.                                                         |
-| `label`              | `string`  | `null`  | _Optional:_ Version label used when generating the version‑selector dropdown menu.                                                          |
-| `baseUrl`            | `string`  | `null`  | _Optional:_ Base URL for versioned docs in the version‑selector dropdown.                                                                   |
-| `versions`           | `object`  | `null`  | _Optional:_ Options for versioning configuration. See below for a list of supported options.                                                |
-| `markdownGenerators` | `object`  | `null`  | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options.                                       |
-| `showSchemas`        | `boolean` | `null`  | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar.                                               |
-| `showInfoPage`       | `boolean` | `true`  | _Optional:_ If set to `false`, disables generation of the info page (overview page with API title and description).                         |
-| `schemasOnly`        | `boolean` | `false` | _Optional:_ If set to `true`, generates only schema pages (no API endpoint pages). Also available as `--schemas-only` CLI flag.             |
+| Name                 | Type      | Default | Description                                                                                                                                                    |
+| -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`           | `string`  | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files.                                    |
+| `outputDir`          | `string`  | `null`  | Desired output path for generated MDX and sidebar files.                                                                                                       |
+| `proxy`              | `string`  | `null`  | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. Overrides site-wide `themeConfig.api.proxy` if set.                    |
+| `template`           | `string`  | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                                                     |
+| `infoTemplate`       | `string`  | `null`  | _Optional:_ Customize MDX content for **info** pages only.                                                                                                     |
+| `tagTemplate`        | `string`  | `null`  | _Optional:_ Customize MDX content for **tag** pages only.                                                                                                      |
+| `schemaTemplate`     | `string`  | `null`  | _Optional:_ Customize MDX content for **schema** pages only.                                                                                                   |
+| `downloadUrl`        | `string`  | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                                                                |
+| `hideSendButton`     | `boolean` | `null`  | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel.                                                                       |
+| `showExtensions`     | `boolean` | `null`  | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions.                                                                       |
+| `maskCredentials`    | `boolean` | `true`  | _Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security.                        |
+| `sidebarOptions`     | `object`  | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                                                               |
+| `version`            | `string`  | `null`  | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`.                                                                            |
+| `label`              | `string`  | `null`  | _Optional:_ Version label used when generating the version‑selector dropdown menu.                                                                             |
+| `baseUrl`            | `string`  | `null`  | _Optional:_ Base URL for versioned docs in the version‑selector dropdown.                                                                                      |
+| `versions`           | `object`  | `null`  | _Optional:_ Options for versioning configuration. See below for a list of supported options.                                                                   |
+| `markdownGenerators` | `object`  | `null`  | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options.                                                          |
+| `showSchemas`        | `boolean` | `null`  | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar.                                                                  |
+| `showInfoPage`       | `boolean` | `true`  | _Optional:_ If set to `false`, disables generation of the info page (overview page with API title and description).                                            |
+| `schemasOnly`        | `boolean` | `false` | _Optional:_ If set to `true`, generates only schema pages (no API endpoint pages). Also available as `--schemas-only` CLI flag.                                |
+| `externalJsonProps`  | `boolean` | `true`  | _Optional:_ If set to `false`, disables externalization of large JSON props. By default, large JSON is written to external files for better build performance. |
 
 ### sidebarOptions
 
@@ -226,6 +227,28 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 | --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `createDocItem` | `function` | `null`  | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.<br/><br/>**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
 
+### Performance Optimization
+
+By default, `externalJsonProps` is enabled to optimize Docusaurus build times. This externalizes large JSON objects to separate files, significantly improving build performance for large OpenAPI specs.
+
+**How it works:**
+
+- With `externalJsonProps: true` (default): Large JSON props are written to separate `.json` files and loaded via `require()`. This bypasses MDX AST processing entirely, allowing the bundler to handle JSON more efficiently.
+
+- With `externalJsonProps: false`: Large JSON objects (responses, request bodies, parameters) are embedded directly in the MDX. The MDX compiler must parse these into an AST and serialize them back, which can be slow for deeply nested schemas.
+
+**When to disable:**
+
+You may set `externalJsonProps: false` if you have custom tooling that depends on parsing the MDX files directly:
+
+```typescript
+petstore: {
+  specPath: "examples/petstore.yaml",
+  outputDir: "docs/petstore",
+  externalJsonProps: false, // Disable if needed for custom tooling
+} satisfies OpenApiPlugin.Options,
+```
+
 ## Theme Configuration Options
 
 The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:

package/lib/index.js

@@ -20,6 +20,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const json5_1 = __importDefault(require("json5"));
 const mustache_1 = require("mustache");
 const markdown_1 = require("./markdown");
+const externalizeJsonProps_1 = require("./markdown/externalizeJsonProps");
 const openapi_1 = require("./openapi");
 const options_1 = require("./options");
 const sidebars_1 = __importDefault(require("./sidebars"));
@@ -281,7 +282,23 @@ custom_edit_url: null
                             if (item.id.length === 0) {
                                 throw Error("Operation must have summary or operationId defined");
                             }
-                            fs_1.default.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
+                            let finalView = view;
+                            let jsonFilesToWrite = [];
+                            // Externalize large JSON props if enabled
+                            if (options.externalJsonProps) {
+                                const result = (0, externalizeJsonProps_1.externalizeJsonPropsSimple)(view, item.id);
+                                finalView = result.mdx;
+                                jsonFilesToWrite = result.jsonFiles;
+                                // Write JSON files
+                                for (const jsonFile of jsonFilesToWrite) {
+                                    const jsonPath = `${outputDir}/${jsonFile.filename}`;
+                                    if (!fs_1.default.existsSync(jsonPath)) {
+                                        fs_1.default.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                                        console.log(chalk_1.default.green(`Successfully created "${jsonPath}"`));
+                                    }
+                                }
+                            }
+                            fs_1.default.writeFileSync(`${outputDir}/${item.id}.api.mdx`, finalView, "utf8");
                             console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.api.mdx"`));
                         }
                         catch (err) {
@@ -330,7 +347,22 @@ custom_edit_url: null
                                 throw Error("Schema must have title defined");
                             }
                             // eslint-disable-next-line testing-library/render-result-naming-convention
-                            const schemaView = (0, mustache_1.render)(schemaMdTemplate, item);
+                            let schemaView = (0, mustache_1.render)(schemaMdTemplate, item);
+                            let jsonFilesToWrite = [];
+                            // Externalize large JSON props if enabled
+                            if (options.externalJsonProps) {
+                                const result = (0, externalizeJsonProps_1.externalizeJsonPropsSimple)(schemaView, item.id);
+                                schemaView = result.mdx;
+                                jsonFilesToWrite = result.jsonFiles;
+                                // Write JSON files in schemas directory
+                                for (const jsonFile of jsonFilesToWrite) {
+                                    const jsonPath = `${outputDir}/schemas/${jsonFile.filename}`;
+                                    if (!fs_1.default.existsSync(jsonPath)) {
+                                        fs_1.default.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                                        console.log(chalk_1.default.green(`Successfully created "${jsonPath}"`));
+                                    }
+                                }
+                            }
                             fs_1.default.writeFileSync(`${outputDir}/schemas/${item.id}.schema.mdx`, schemaView, "utf8");
                             console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.schema.mdx"`));
                         }
@@ -361,6 +393,11 @@ custom_edit_url: null
                 cwd: path_1.default.resolve(apiDir),
                 deep: 1,
             });
+            // Clean up externalized JSON files
+            const jsonFiles = await (0, utils_1.Globby)(["*.json", "!versions.json"], {
+                cwd: path_1.default.resolve(apiDir),
+                deep: 1,
+            });
             apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
                 if (err) {
                     console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${mdx}"`), chalk_1.default.yellow(err));
@@ -377,6 +414,15 @@ custom_edit_url: null
                     console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`));
                 }
             }));
+            // Clean up externalized JSON files
+            jsonFiles.map((jsonFile) => fs_1.default.unlink(`${apiDir}/${jsonFile}`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${jsonFile}"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${jsonFile}"`));
+                }
+            }));
         }
         try {
             fs_1.default.rmSync(`${apiDir}/schemas`, { recursive: true });

package/lib/markdown/externalizeJsonProps.d.ts

@@ -0,0 +1,31 @@
+/**
+ * This module provides utilities for externalizing large JSON props in MDX files.
+ *
+ * The motivation is to improve MDX compilation performance. When large JSON objects
+ * are embedded directly as JSX props, MDX needs to parse them into AST and then
+ * serialize them back. By externalizing to JSON files and using require(), the
+ * MDX compiler can skip this expensive processing.
+ *
+ * @see https://github.com/facebook/docusaurus/discussions/11664
+ */
+export interface ExternalizedJsonFile {
+    /** The filename for the JSON file (without path) */
+    filename: string;
+    /** The JSON content to write */
+    content: string;
+}
+export interface ExternalizeResult {
+    /** The transformed MDX content with require() statements */
+    mdx: string;
+    /** List of JSON files that need to be written */
+    jsonFiles: ExternalizedJsonFile[];
+}
+/**
+ * Externalizes large JSON props from MDX content.
+ * Uses brace-counting to correctly handle deeply nested JSON.
+ *
+ * @param mdx - The original MDX content
+ * @param baseFilename - The base filename (without extension) for the MDX file
+ * @returns The transformed MDX and list of JSON files to write
+ */
+export declare function externalizeJsonPropsSimple(mdx: string, baseFilename: string): ExternalizeResult;

package/lib/markdown/externalizeJsonProps.js

@@ -0,0 +1,149 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.externalizeJsonPropsSimple = externalizeJsonPropsSimple;
+/**
+ * Components and their props that should be externalized.
+ * These are the components that typically receive large JSON objects.
+ */
+const COMPONENTS_TO_EXTERNALIZE = [
+    { component: "StatusCodes", prop: "responses" },
+    { component: "ParamsDetails", prop: "parameters" },
+    { component: "RequestSchema", prop: "body" },
+    { component: "Schema", prop: "schema" },
+    { component: "SchemaItem", prop: "schema" },
+];
+/**
+ * Minimum size (in characters) for a JSON prop to be externalized.
+ * Props smaller than this threshold will remain inline.
+ */
+const MIN_SIZE_THRESHOLD = 500;
+/**
+ * Extracts the content between balanced braces starting at a given position.
+ * Returns the content (without outer braces) and the end position.
+ */
+function extractBalancedBraces(str, startIndex) {
+    if (str[startIndex] !== "{") {
+        return null;
+    }
+    let depth = 0;
+    let inString = false;
+    let stringChar = "";
+    let escaped = false;
+    for (let i = startIndex; i < str.length; i++) {
+        const char = str[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (!inString) {
+            if (char === '"' || char === "'") {
+                inString = true;
+                stringChar = char;
+            }
+            else if (char === "{") {
+                depth++;
+            }
+            else if (char === "}") {
+                depth--;
+                if (depth === 0) {
+                    // Found the matching closing brace
+                    return {
+                        content: str.substring(startIndex + 1, i),
+                        endIndex: i,
+                    };
+                }
+            }
+        }
+        else {
+            if (char === stringChar) {
+                inString = false;
+            }
+        }
+    }
+    return null; // Unbalanced braces
+}
+/**
+ * Externalizes large JSON props from MDX content.
+ * Uses brace-counting to correctly handle deeply nested JSON.
+ *
+ * @param mdx - The original MDX content
+ * @param baseFilename - The base filename (without extension) for the MDX file
+ * @returns The transformed MDX and list of JSON files to write
+ */
+function externalizeJsonPropsSimple(mdx, baseFilename) {
+    const jsonFiles = [];
+    let transformedMdx = mdx;
+    for (const { component, prop } of COMPONENTS_TO_EXTERNALIZE) {
+        // Find pattern: prop={
+        const propPattern = new RegExp(`${prop}=\\{`, "g");
+        let match;
+        // Keep searching until no more matches (need to restart after each replacement)
+        let searchStart = 0;
+        while (true) {
+            propPattern.lastIndex = searchStart;
+            match = propPattern.exec(transformedMdx);
+            if (!match)
+                break;
+            const propStart = match.index;
+            const braceStart = propStart + prop.length + 1; // Position of '{'
+            // Extract the balanced content
+            const extracted = extractBalancedBraces(transformedMdx, braceStart);
+            if (!extracted) {
+                searchStart = braceStart + 1;
+                continue;
+            }
+            const jsonContent = extracted.content;
+            const propEnd = extracted.endIndex + 1; // Position after '}'
+            // Skip small or non-JSON content
+            const trimmed = jsonContent.trim();
+            if (jsonContent.length < MIN_SIZE_THRESHOLD ||
+                trimmed === "undefined" ||
+                trimmed === "null" ||
+                trimmed === "true" ||
+                trimmed === "false" ||
+                trimmed.startsWith("require(")) {
+                searchStart = propEnd;
+                continue;
+            }
+            // Check if this is within the target component
+            // Look backwards for the component tag
+            const beforeProp = transformedMdx.substring(0, propStart);
+            const componentTagPattern = new RegExp(`<${component}[\\s\\S]*$`);
+            if (!componentTagPattern.test(beforeProp)) {
+                searchStart = propEnd;
+                continue;
+            }
+            // Generate filename
+            const existingCount = jsonFiles.filter((f) => f.filename.includes(`.${prop}`)).length;
+            const suffix = existingCount > 0 ? `.${existingCount + 1}` : "";
+            const jsonFilename = `${baseFilename}.${prop}${suffix}.json`;
+            // Store the JSON file
+            jsonFiles.push({
+                filename: jsonFilename,
+                content: jsonContent.trim(),
+            });
+            // Replace the prop value with require()
+            const newProp = `${prop}={require("./${jsonFilename}")}`;
+            transformedMdx =
+                transformedMdx.substring(0, propStart) +
+                    newProp +
+                    transformedMdx.substring(propEnd);
+            // Continue searching after the replacement
+            searchStart = propStart + newProp.length;
+        }
+    }
+    return {
+        mdx: transformedMdx,
+        jsonFiles,
+    };
+}

package/lib/options.js

@@ -48,6 +48,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         schemasOnly: utils_validation_1.Joi.boolean(),
         disableCompression: utils_validation_1.Joi.boolean(),
         maskCredentials: utils_validation_1.Joi.boolean(),
+        externalJsonProps: utils_validation_1.Joi.boolean().default(true),
         version: utils_validation_1.Joi.string().when("versions", {
             is: utils_validation_1.Joi.exist(),
             then: utils_validation_1.Joi.required(),

package/lib/types.d.ts

@@ -33,6 +33,13 @@ export interface APIOptions {
     schemasOnly?: boolean;
     disableCompression?: boolean;
     maskCredentials?: boolean;
+    /**
+     * When enabled, large JSON props in generated MDX are written to external
+     * files and loaded via require(). This can significantly improve MDX
+     * compilation performance for large OpenAPI specs.
+     * @see https://github.com/facebook/docusaurus/discussions/11664
+     */
+    externalJsonProps?: boolean;
 }
 export interface MarkdownGenerator {
     createApiPageMD?: (pageData: ApiPageMetadata) => string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-1089",
+  "version": "0.0.0-1092",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "c3a9819571e1ca0aa03c26f93332b7ec71acc857"
+  "gitHead": "52285283e2fc0ee02b7f5e42a9678a3bb89c095b"
 }

package/src/index.ts

@@ -21,6 +21,10 @@ import {
   createSchemaPageMD,
   createTagPageMD,
 } from "./markdown";
+import {
+  externalizeJsonPropsSimple,
+  ExternalizedJsonFile,
+} from "./markdown/externalizeJsonProps";
 import { processOpenapiFiles, readOpenapiFiles } from "./openapi";
 import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
@@ -383,7 +387,33 @@ custom_edit_url: null
                   "Operation must have summary or operationId defined"
                 );
               }
-              fs.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
+
+              let finalView = view;
+              let jsonFilesToWrite: ExternalizedJsonFile[] = [];
+
+              // Externalize large JSON props if enabled
+              if (options.externalJsonProps) {
+                const result = externalizeJsonPropsSimple(view, item.id);
+                finalView = result.mdx;
+                jsonFilesToWrite = result.jsonFiles;
+
+                // Write JSON files
+                for (const jsonFile of jsonFilesToWrite) {
+                  const jsonPath = `${outputDir}/${jsonFile.filename}`;
+                  if (!fs.existsSync(jsonPath)) {
+                    fs.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                    console.log(
+                      chalk.green(`Successfully created "${jsonPath}"`)
+                    );
+                  }
+                }
+              }
+
+              fs.writeFileSync(
+                `${outputDir}/${item.id}.api.mdx`,
+                finalView,
+                "utf8"
+              );
               console.log(
                 chalk.green(
                   `Successfully created "${outputDir}/${item.id}.api.mdx"`
@@ -469,7 +499,27 @@ custom_edit_url: null
                 throw Error("Schema must have title defined");
               }
               // eslint-disable-next-line testing-library/render-result-naming-convention
-              const schemaView = render(schemaMdTemplate, item);
+              let schemaView = render(schemaMdTemplate, item);
+              let jsonFilesToWrite: ExternalizedJsonFile[] = [];
+
+              // Externalize large JSON props if enabled
+              if (options.externalJsonProps) {
+                const result = externalizeJsonPropsSimple(schemaView, item.id);
+                schemaView = result.mdx;
+                jsonFilesToWrite = result.jsonFiles;
+
+                // Write JSON files in schemas directory
+                for (const jsonFile of jsonFilesToWrite) {
+                  const jsonPath = `${outputDir}/schemas/${jsonFile.filename}`;
+                  if (!fs.existsSync(jsonPath)) {
+                    fs.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                    console.log(
+                      chalk.green(`Successfully created "${jsonPath}"`)
+                    );
+                  }
+                }
+              }
+
               fs.writeFileSync(
                 `${outputDir}/schemas/${item.id}.schema.mdx`,
                 schemaView,
@@ -517,6 +567,11 @@ custom_edit_url: null
         cwd: path.resolve(apiDir),
         deep: 1,
       });
+      // Clean up externalized JSON files
+      const jsonFiles = await Globby(["*.json", "!versions.json"], {
+        cwd: path.resolve(apiDir),
+        deep: 1,
+      });
       apiMdxFiles.map((mdx) =>
         fs.unlink(`${apiDir}/${mdx}`, (err) => {
           if (err) {
@@ -546,6 +601,22 @@ custom_edit_url: null
           }
         })
       );
+
+      // Clean up externalized JSON files
+      jsonFiles.map((jsonFile) =>
+        fs.unlink(`${apiDir}/${jsonFile}`, (err) => {
+          if (err) {
+            console.error(
+              chalk.red(`Cleanup failed for "${apiDir}/${jsonFile}"`),
+              chalk.yellow(err)
+            );
+          } else {
+            console.log(
+              chalk.green(`Cleanup succeeded for "${apiDir}/${jsonFile}"`)
+            );
+          }
+        })
+      );
     }
 
     try {

package/src/markdown/externalizeJsonProps.ts

@@ -0,0 +1,201 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+/**
+ * This module provides utilities for externalizing large JSON props in MDX files.
+ *
+ * The motivation is to improve MDX compilation performance. When large JSON objects
+ * are embedded directly as JSX props, MDX needs to parse them into AST and then
+ * serialize them back. By externalizing to JSON files and using require(), the
+ * MDX compiler can skip this expensive processing.
+ *
+ * @see https://github.com/facebook/docusaurus/discussions/11664
+ */
+
+export interface ExternalizedJsonFile {
+  /** The filename for the JSON file (without path) */
+  filename: string;
+  /** The JSON content to write */
+  content: string;
+}
+
+export interface ExternalizeResult {
+  /** The transformed MDX content with require() statements */
+  mdx: string;
+  /** List of JSON files that need to be written */
+  jsonFiles: ExternalizedJsonFile[];
+}
+
+/**
+ * Components and their props that should be externalized.
+ * These are the components that typically receive large JSON objects.
+ */
+const COMPONENTS_TO_EXTERNALIZE = [
+  { component: "StatusCodes", prop: "responses" },
+  { component: "ParamsDetails", prop: "parameters" },
+  { component: "RequestSchema", prop: "body" },
+  { component: "Schema", prop: "schema" },
+  { component: "SchemaItem", prop: "schema" },
+];
+
+/**
+ * Minimum size (in characters) for a JSON prop to be externalized.
+ * Props smaller than this threshold will remain inline.
+ */
+const MIN_SIZE_THRESHOLD = 500;
+
+/**
+ * Extracts the content between balanced braces starting at a given position.
+ * Returns the content (without outer braces) and the end position.
+ */
+function extractBalancedBraces(
+  str: string,
+  startIndex: number
+): { content: string; endIndex: number } | null {
+  if (str[startIndex] !== "{") {
+    return null;
+  }
+
+  let depth = 0;
+  let inString = false;
+  let stringChar = "";
+  let escaped = false;
+
+  for (let i = startIndex; i < str.length; i++) {
+    const char = str[i];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escaped = true;
+      continue;
+    }
+
+    if (!inString) {
+      if (char === '"' || char === "'") {
+        inString = true;
+        stringChar = char;
+      } else if (char === "{") {
+        depth++;
+      } else if (char === "}") {
+        depth--;
+        if (depth === 0) {
+          // Found the matching closing brace
+          return {
+            content: str.substring(startIndex + 1, i),
+            endIndex: i,
+          };
+        }
+      }
+    } else {
+      if (char === stringChar) {
+        inString = false;
+      }
+    }
+  }
+
+  return null; // Unbalanced braces
+}
+
+/**
+ * Externalizes large JSON props from MDX content.
+ * Uses brace-counting to correctly handle deeply nested JSON.
+ *
+ * @param mdx - The original MDX content
+ * @param baseFilename - The base filename (without extension) for the MDX file
+ * @returns The transformed MDX and list of JSON files to write
+ */
+export function externalizeJsonPropsSimple(
+  mdx: string,
+  baseFilename: string
+): ExternalizeResult {
+  const jsonFiles: ExternalizedJsonFile[] = [];
+  let transformedMdx = mdx;
+
+  for (const { component, prop } of COMPONENTS_TO_EXTERNALIZE) {
+    // Find pattern: prop={
+    const propPattern = new RegExp(`${prop}=\\{`, "g");
+    let match;
+
+    // Keep searching until no more matches (need to restart after each replacement)
+    let searchStart = 0;
+    while (true) {
+      propPattern.lastIndex = searchStart;
+      match = propPattern.exec(transformedMdx);
+
+      if (!match) break;
+
+      const propStart = match.index;
+      const braceStart = propStart + prop.length + 1; // Position of '{'
+
+      // Extract the balanced content
+      const extracted = extractBalancedBraces(transformedMdx, braceStart);
+      if (!extracted) {
+        searchStart = braceStart + 1;
+        continue;
+      }
+
+      const jsonContent = extracted.content;
+      const propEnd = extracted.endIndex + 1; // Position after '}'
+
+      // Skip small or non-JSON content
+      const trimmed = jsonContent.trim();
+      if (
+        jsonContent.length < MIN_SIZE_THRESHOLD ||
+        trimmed === "undefined" ||
+        trimmed === "null" ||
+        trimmed === "true" ||
+        trimmed === "false" ||
+        trimmed.startsWith("require(")
+      ) {
+        searchStart = propEnd;
+        continue;
+      }
+
+      // Check if this is within the target component
+      // Look backwards for the component tag
+      const beforeProp = transformedMdx.substring(0, propStart);
+      const componentTagPattern = new RegExp(`<${component}[\\s\\S]*$`);
+      if (!componentTagPattern.test(beforeProp)) {
+        searchStart = propEnd;
+        continue;
+      }
+
+      // Generate filename
+      const existingCount = jsonFiles.filter((f) =>
+        f.filename.includes(`.${prop}`)
+      ).length;
+      const suffix = existingCount > 0 ? `.${existingCount + 1}` : "";
+      const jsonFilename = `${baseFilename}.${prop}${suffix}.json`;
+
+      // Store the JSON file
+      jsonFiles.push({
+        filename: jsonFilename,
+        content: jsonContent.trim(),
+      });
+
+      // Replace the prop value with require()
+      const newProp = `${prop}={require("./${jsonFilename}")}`;
+
+      transformedMdx =
+        transformedMdx.substring(0, propStart) +
+        newProp +
+        transformedMdx.substring(propEnd);
+
+      // Continue searching after the replacement
+      searchStart = propStart + newProp.length;
+    }
+  }
+
+  return {
+    mdx: transformedMdx,
+    jsonFiles,
+  };
+}

package/src/options.ts

@@ -52,6 +52,7 @@ export const OptionsSchema = Joi.object({
         schemasOnly: Joi.boolean(),
         disableCompression: Joi.boolean(),
         maskCredentials: Joi.boolean(),
+        externalJsonProps: Joi.boolean().default(true),
         version: Joi.string().when("versions", {
           is: Joi.exist(),
           then: Joi.required(),

package/src/types.ts

@@ -55,6 +55,13 @@ export interface APIOptions {
   schemasOnly?: boolean;
   disableCompression?: boolean;
   maskCredentials?: boolean;
+  /**
+   * When enabled, large JSON props in generated MDX are written to external
+   * files and loaded via require(). This can significantly improve MDX
+   * compilation performance for large OpenAPI specs.
+   * @see https://github.com/facebook/docusaurus/discussions/11664
+   */
+  externalJsonProps?: boolean;
 }
 
 export interface MarkdownGenerator {