docusaurus-plugin-openapi-docs 4.6.0 → 4.7.0

package/README.md

@@ -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 utils_2 = require("./markdown/utils");
 const openapi_1 = require("./openapi");
 const options_1 = require("./options");
 const sidebars_1 = __importDefault(require("./sidebars"));
@@ -238,8 +239,17 @@ custom_edit_url: null
                 if (downloadUrl) {
                     item.downloadUrl = downloadUrl;
                 }
-                const markdown = pageGeneratorByType[item.type](item);
-                item.markdown = markdown;
+                // Generate markdown, with externalization for API and schema pages
+                let externalFiles = [];
+                if (options.externalJsonProps &&
+                    (item.type === "api" || item.type === "schema")) {
+                    const result = (0, utils_2.runWithExternalization)(item.id, () => pageGeneratorByType[item.type](item));
+                    item.markdown = result.result;
+                    externalFiles = result.files;
+                }
+                else {
+                    item.markdown = pageGeneratorByType[item.type](item);
+                }
                 if (isSchemasOnly && item.type !== "schema") {
                     return;
                 }
@@ -281,6 +291,14 @@ custom_edit_url: null
                             if (item.id.length === 0) {
                                 throw Error("Operation must have summary or operationId defined");
                             }
+                            // Write externalized JSON files
+                            for (const jsonFile of externalFiles) {
+                                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`, view, "utf8");
                             console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.api.mdx"`));
                         }
@@ -331,6 +349,14 @@ custom_edit_url: null
                             }
                             // eslint-disable-next-line testing-library/render-result-naming-convention
                             const schemaView = (0, mustache_1.render)(schemaMdTemplate, item);
+                            // Write externalized JSON files in schemas directory
+                            for (const jsonFile of externalFiles) {
+                                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 +387,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 +408,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/schema.js

@@ -10,6 +10,11 @@ exports.getSchemaName = getSchemaName;
 exports.getQualifierMessage = getQualifierMessage;
 function prettyName(schema, circular) {
     var _a, _b, _c, _d, _e;
+    // Handle enum-only schemas (valid in JSON Schema)
+    // When enum is present without explicit type, treat as string
+    if (schema.enum && !schema.type) {
+        return "string";
+    }
     if (schema.format) {
         if (schema.type) {
             return `${schema.type}<${schema.format}>`;

package/lib/markdown/utils.d.ts

@@ -1,6 +1,38 @@
+/**
+ * Represents an external JSON file to be written alongside the MDX.
+ */
+export interface ExternalFile {
+    /** The filename for the JSON file (relative to outputDir) */
+    filename: string;
+    /** The JSON content to write */
+    content: string;
+}
+/**
+ * Result of running MDX generation with externalization.
+ */
+export interface ExternalizationResult<T> {
+    /** The result of the generation function */
+    result: T;
+    /** External JSON files to write */
+    files: ExternalFile[];
+}
+/**
+ * Runs a function with externalization enabled.
+ * Any calls to create() within the function will externalize eligible component props.
+ *
+ * @param baseFilename - Base filename for the MDX file (without extension)
+ * @param fn - Function to run with externalization enabled
+ * @returns The function result and any external files that were collected
+ *
+ * @example
+ * const { result: mdx, files } = runWithExternalization("add-pet", () => {
+ *   return createApiPageMD(item);
+ * });
+ */
+export declare function runWithExternalization<T>(baseFilename: string, fn: () => T): ExternalizationResult<T>;
 /**
  * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
- * It is designed for rendering HTML a strings.
+ * It is designed for rendering HTML as strings.
  */
 export type Children = string | undefined | (string | string[] | undefined)[];
 export type Props = Record<string, any> & {
@@ -9,6 +41,11 @@ export type Props = Record<string, any> & {
 export type Options = {
     inline?: boolean;
 };
+/**
+ * Creates a JSX component string with the given tag, props, and options.
+ * When called within runWithExternalization(), props for eligible
+ * components are externalized to a single JSON file and spread.
+ */
 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;

package/lib/markdown/utils.js

@@ -7,15 +7,82 @@
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codeBlock = exports.curlyBrackets = exports.codeFence = exports.greaterThan = exports.lessThan = void 0;
+exports.runWithExternalization = runWithExternalization;
 exports.create = create;
 exports.guard = guard;
 exports.render = render;
 exports.clean = clean;
+/**
+ * Module-level externalization context.
+ * Note: AsyncLocalStorage would be cleaner but isn't available in browser bundles.
+ */
+let externalizationContext = null;
+/**
+ * Components whose props should be externalized to separate JSON files.
+ * These are the components that typically receive large JSON objects.
+ */
+const EXTERNALIZABLE_COMPONENTS = new Set([
+    "StatusCodes",
+    "ParamsDetails",
+    "RequestSchema",
+    "Schema",
+    "SchemaItem",
+]);
+/**
+ * Runs a function with externalization enabled.
+ * Any calls to create() within the function will externalize eligible component props.
+ *
+ * @param baseFilename - Base filename for the MDX file (without extension)
+ * @param fn - Function to run with externalization enabled
+ * @returns The function result and any external files that were collected
+ *
+ * @example
+ * const { result: mdx, files } = runWithExternalization("add-pet", () => {
+ *   return createApiPageMD(item);
+ * });
+ */
+function runWithExternalization(baseFilename, fn) {
+    // Set up context
+    externalizationContext = {
+        baseFilename,
+        componentCounters: {},
+        files: [],
+    };
+    try {
+        const result = fn();
+        const files = externalizationContext.files;
+        return { result, files };
+    }
+    finally {
+        // Always clear context
+        externalizationContext = null;
+    }
+}
+/**
+ * Creates a JSX component string with the given tag, props, and options.
+ * When called within runWithExternalization(), props for eligible
+ * components are externalized to a single JSON file and spread.
+ */
 function create(tag, props, options = {}) {
     const { children, ...rest } = props;
     let propString = "";
-    for (const [key, value] of Object.entries(rest)) {
-        propString += `\n  ${key}={${JSON.stringify(value)}}`;
+    // Check if this component's props should be externalized
+    if (shouldExternalizeComponent(tag, rest)) {
+        const filename = generateExternalFilename(tag);
+        const content = JSON.stringify(rest);
+        // Add to external files
+        externalizationContext.files.push({
+            filename,
+            content,
+        });
+        // Use spread syntax with require
+        propString = `\n  {...require("./${filename}")}`;
+    }
+    else {
+        // Inline props as usual
+        for (const [key, value] of Object.entries(rest)) {
+            propString += `\n  ${key}={${JSON.stringify(value)}}`;
+        }
     }
     let indentedChildren = render(children).replace(/^/gm, "  ");
     if (options.inline) {
@@ -26,6 +93,37 @@ function create(tag, props, options = {}) {
     indentedChildren += indentedChildren ? "\n" : "";
     return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
+/**
+ * Determines if a component's props should be externalized.
+ */
+function shouldExternalizeComponent(tag, props) {
+    // No context means externalization is not enabled
+    if (!externalizationContext) {
+        return false;
+    }
+    if (!EXTERNALIZABLE_COMPONENTS.has(tag)) {
+        return false;
+    }
+    // Don't externalize if props are empty or only contain undefined/null
+    const hasContent = Object.values(props).some((v) => v !== undefined && v !== null);
+    if (!hasContent) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Generates a unique filename for an externalized component's props.
+ */
+function generateExternalFilename(componentName) {
+    var _a;
+    if (!externalizationContext) {
+        throw new Error("Externalization context not set");
+    }
+    const count = ((_a = externalizationContext.componentCounters[componentName]) !== null && _a !== void 0 ? _a : 0) + 1;
+    externalizationContext.componentCounters[componentName] = count;
+    const suffix = count > 1 ? `.${count}` : "";
+    return `${externalizationContext.baseFilename}.${componentName}${suffix}.json`;
+}
 function guard(value, cb) {
     if (!!value || value === 0) {
         const children = cb(value);

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "c7c5ca9934031d166faa0740746ef1a39e72982d"
+  "gitHead": "f5829b8e478b0ee76344ba31edd67efdfea18990"
 }

package/src/index.ts

@@ -21,6 +21,7 @@ import {
   createSchemaPageMD,
   createTagPageMD,
 } from "./markdown";
+import { ExternalFile, runWithExternalization } from "./markdown/utils";
 import { processOpenapiFiles, readOpenapiFiles } from "./openapi";
 import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
@@ -333,8 +334,21 @@ custom_edit_url: null
         if (downloadUrl) {
           item.downloadUrl = downloadUrl;
         }
-        const markdown = pageGeneratorByType[item.type](item as any);
-        item.markdown = markdown;
+
+        // Generate markdown, with externalization for API and schema pages
+        let externalFiles: ExternalFile[] = [];
+        if (
+          options.externalJsonProps &&
+          (item.type === "api" || item.type === "schema")
+        ) {
+          const result = runWithExternalization(item.id, () =>
+            pageGeneratorByType[item.type](item as any)
+          );
+          item.markdown = result.result;
+          externalFiles = result.files;
+        } else {
+          item.markdown = pageGeneratorByType[item.type](item as any);
+        }
         if (isSchemasOnly && item.type !== "schema") {
           return;
         }
@@ -383,6 +397,18 @@ custom_edit_url: null
                   "Operation must have summary or operationId defined"
                 );
               }
+
+              // Write externalized JSON files
+              for (const jsonFile of externalFiles) {
+                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`, view, "utf8");
               console.log(
                 chalk.green(
@@ -470,6 +496,18 @@ custom_edit_url: null
               }
               // eslint-disable-next-line testing-library/render-result-naming-convention
               const schemaView = render(schemaMdTemplate, item);
+
+              // Write externalized JSON files in schemas directory
+              for (const jsonFile of externalFiles) {
+                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 +555,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 +589,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/schema.ts

@@ -8,6 +8,12 @@
 import { SchemaObject } from "../openapi/types";
 
 function prettyName(schema: SchemaObject, circular?: boolean) {
+  // Handle enum-only schemas (valid in JSON Schema)
+  // When enum is present without explicit type, treat as string
+  if (schema.enum && !schema.type) {
+    return "string";
+  }
+
   if (schema.format) {
     if (schema.type) {
       return `${schema.type}<${schema.format}>`;

package/src/markdown/utils.ts

@@ -5,9 +5,93 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
+/**
+ * Represents an external JSON file to be written alongside the MDX.
+ */
+export interface ExternalFile {
+  /** The filename for the JSON file (relative to outputDir) */
+  filename: string;
+  /** The JSON content to write */
+  content: string;
+}
+
+/**
+ * Result of running MDX generation with externalization.
+ */
+export interface ExternalizationResult<T> {
+  /** The result of the generation function */
+  result: T;
+  /** External JSON files to write */
+  files: ExternalFile[];
+}
+
+/**
+ * Context for externalization during MDX generation.
+ */
+interface ExternalizationContext {
+  /** Base filename for external files (e.g., "add-pet" for "add-pet.api.mdx") */
+  baseFilename: string;
+  /** Counter for generating unique filenames per component type */
+  componentCounters: Record<string, number>;
+  /** Collected external files during generation */
+  files: ExternalFile[];
+}
+
+/**
+ * Module-level externalization context.
+ * Note: AsyncLocalStorage would be cleaner but isn't available in browser bundles.
+ */
+let externalizationContext: ExternalizationContext | null = null;
+
+/**
+ * Components whose props should be externalized to separate JSON files.
+ * These are the components that typically receive large JSON objects.
+ */
+const EXTERNALIZABLE_COMPONENTS = new Set([
+  "StatusCodes",
+  "ParamsDetails",
+  "RequestSchema",
+  "Schema",
+  "SchemaItem",
+]);
+
+/**
+ * Runs a function with externalization enabled.
+ * Any calls to create() within the function will externalize eligible component props.
+ *
+ * @param baseFilename - Base filename for the MDX file (without extension)
+ * @param fn - Function to run with externalization enabled
+ * @returns The function result and any external files that were collected
+ *
+ * @example
+ * const { result: mdx, files } = runWithExternalization("add-pet", () => {
+ *   return createApiPageMD(item);
+ * });
+ */
+export function runWithExternalization<T>(
+  baseFilename: string,
+  fn: () => T
+): ExternalizationResult<T> {
+  // Set up context
+  externalizationContext = {
+    baseFilename,
+    componentCounters: {},
+    files: [],
+  };
+
+  try {
+    const result = fn();
+    const files = externalizationContext.files;
+    return { result, files };
+  } finally {
+    // Always clear context
+    externalizationContext = null;
+  }
+}
+
 /**
  * Children in the plugin does not accept DOM elements, when compared with Children in the theme.
- * It is designed for rendering HTML a strings.
+ * It is designed for rendering HTML as strings.
  */
 export type Children = string | undefined | (string | string[] | undefined)[];
 
@@ -15,6 +99,11 @@ export type Props = Record<string, any> & { children?: Children };
 
 export type Options = { inline?: boolean };
 
+/**
+ * Creates a JSX component string with the given tag, props, and options.
+ * When called within runWithExternalization(), props for eligible
+ * components are externalized to a single JSON file and spread.
+ */
 export function create(
   tag: string,
   props: Props,
@@ -23,9 +112,27 @@ export function create(
   const { children, ...rest } = props;
 
   let propString = "";
-  for (const [key, value] of Object.entries(rest)) {
-    propString += `\n  ${key}={${JSON.stringify(value)}}`;
+
+  // Check if this component's props should be externalized
+  if (shouldExternalizeComponent(tag, rest)) {
+    const filename = generateExternalFilename(tag);
+    const content = JSON.stringify(rest);
+
+    // Add to external files
+    externalizationContext!.files.push({
+      filename,
+      content,
+    });
+
+    // Use spread syntax with require
+    propString = `\n  {...require("./${filename}")}`;
+  } else {
+    // Inline props as usual
+    for (const [key, value] of Object.entries(rest)) {
+      propString += `\n  ${key}={${JSON.stringify(value)}}`;
+    }
   }
+
   let indentedChildren = render(children).replace(/^/gm, "  ");
 
   if (options.inline) {
@@ -38,6 +145,49 @@ export function create(
   return `<${tag}${propString}>\n${indentedChildren}</${tag}>`;
 }
 
+/**
+ * Determines if a component's props should be externalized.
+ */
+function shouldExternalizeComponent(
+  tag: string,
+  props: Record<string, any>
+): boolean {
+  // No context means externalization is not enabled
+  if (!externalizationContext) {
+    return false;
+  }
+
+  if (!EXTERNALIZABLE_COMPONENTS.has(tag)) {
+    return false;
+  }
+
+  // Don't externalize if props are empty or only contain undefined/null
+  const hasContent = Object.values(props).some(
+    (v) => v !== undefined && v !== null
+  );
+  if (!hasContent) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Generates a unique filename for an externalized component's props.
+ */
+function generateExternalFilename(componentName: string): string {
+  if (!externalizationContext) {
+    throw new Error("Externalization context not set");
+  }
+
+  const count =
+    (externalizationContext.componentCounters[componentName] ?? 0) + 1;
+  externalizationContext.componentCounters[componentName] = count;
+
+  const suffix = count > 1 ? `.${count}` : "";
+  return `${externalizationContext.baseFilename}.${componentName}${suffix}.json`;
+}
+
 export function guard<T>(
   value: T | undefined,
   cb: (value: T) => Children

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 → types.d.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 {

package/lib/types.d.ts

@@ -1,138 +0,0 @@
-import type { SidebarItemDoc } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
-import { InfoObject, OperationObject, SchemaObject, SecuritySchemeObject, TagObject } from "./openapi/types";
-export type { PropSidebarItemCategory, SidebarItemLink, PropSidebar, PropSidebarItem, } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
-export interface PluginOptions {
-    id?: string;
-    docsPlugin?: string;
-    docsPluginId: string;
-    config: {
-        [key: string]: APIOptions;
-    };
-}
-export interface APIOptions {
-    specPath: string;
-    outputDir: string;
-    template?: string;
-    infoTemplate?: string;
-    tagTemplate?: string;
-    schemaTemplate?: string;
-    downloadUrl?: string;
-    hideSendButton?: boolean;
-    showExtensions?: boolean;
-    sidebarOptions?: SidebarOptions;
-    version?: string;
-    label?: string;
-    baseUrl?: string;
-    versions?: {
-        [key: string]: APIVersionOptions;
-    };
-    proxy?: string;
-    markdownGenerators?: MarkdownGenerator;
-    showSchemas?: boolean;
-    showInfoPage?: boolean;
-    schemasOnly?: boolean;
-    disableCompression?: boolean;
-    maskCredentials?: boolean;
-}
-export interface MarkdownGenerator {
-    createApiPageMD?: (pageData: ApiPageMetadata) => string;
-    createInfoPageMD?: (pageData: InfoPageMetadata) => string;
-    createTagPageMD?: (pageData: TagPageMetadata) => string;
-    createSchemaPageMD?: (pageData: SchemaPageMetadata) => string;
-}
-export type ApiDocItemGenerator = (item: ApiPageMetadata | SchemaPageMetadata, context: {
-    sidebarOptions: SidebarOptions;
-    basePath: string;
-}) => SidebarItemDoc;
-export interface SidebarGenerators {
-    createDocItem?: ApiDocItemGenerator;
-}
-export interface SidebarOptions {
-    groupPathsBy?: string;
-    categoryLinkSource?: "info" | "tag" | "auto";
-    customProps?: {
-        [key: string]: unknown;
-    };
-    sidebarCollapsible?: boolean;
-    sidebarCollapsed?: boolean;
-    sidebarGenerators?: SidebarGenerators;
-}
-export interface APIVersionOptions {
-    specPath: string;
-    outputDir: string;
-    label: string;
-    baseUrl: string;
-    downloadUrl?: string;
-}
-export interface LoadedContent {
-    loadedApi: ApiMetadata[];
-}
-export type ApiMetadata = ApiPageMetadata | InfoPageMetadata | TagPageMetadata | SchemaPageMetadata;
-export interface ApiMetadataBase {
-    sidebar?: string;
-    previous?: ApiNavLink;
-    next?: ApiNavLink;
-    id: string;
-    unversionedId: string;
-    infoId?: string;
-    infoPath?: string;
-    downloadUrl?: string;
-    title: string;
-    description: string;
-    source: string;
-    sourceDirName: string;
-    slug?: string;
-    permalink: string;
-    sidebarPosition?: number;
-    frontMatter: Record<string, unknown>;
-    method?: string;
-    path?: string;
-    position?: number;
-}
-export interface ApiPageMetadata extends ApiMetadataBase {
-    json?: string;
-    type: "api";
-    api: ApiItem;
-    markdown?: string;
-}
-export interface ApiItem extends OperationObject {
-    method: string;
-    path: string;
-    jsonRequestBodyExample: string;
-    securitySchemes?: {
-        [key: string]: SecuritySchemeObject;
-    };
-    postman?: Request;
-    proxy?: string;
-    info: InfoObject;
-    extensions?: object;
-}
-export interface InfoPageMetadata extends ApiMetadataBase {
-    type: "info";
-    info: ApiInfo;
-    markdown?: string;
-    securitySchemes?: {
-        [key: string]: SecuritySchemeObject;
-    };
-}
-export interface TagPageMetadata extends ApiMetadataBase {
-    type: "tag";
-    tag: TagObject;
-    markdown?: string;
-}
-export interface SchemaPageMetadata extends ApiMetadataBase {
-    type: "schema";
-    schema: SchemaObject;
-    markdown?: string;
-}
-export interface TagGroupPageMetadata extends ApiMetadataBase {
-    type: "tagGroup";
-    name: string;
-    tags: TagObject[];
-    markdown?: string;
-}
-export type ApiInfo = InfoObject;
-export interface ApiNavLink {
-    title: string;
-    permalink: string;
-}

package/lib/types.js

@@ -1,8 +0,0 @@
-"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 });