Externalize using create() and drop size threshold requirement (#1280)

* refactor(plugin): externalize JSON props at source in create()

Implements slorber's suggestion from PR #1279 to handle externalization
at the source (in create()) rather than post-processing MDX strings.

Changes:
- Add externalization context system to utils.ts
- Modify create() to detect large JSON props and externalize inline
- Remove externalizeJsonProps.ts (no longer needed)
- Update index.ts to use context-based approach

This is more architecturally clean as the externalization decision
happens where the component is created, not via regex parsing afterward.

* refactor(plugin): drop size threshold for externalization

Always externalize eligible props (responses, parameters, body, schema)
regardless of size. This simplifies the logic and provides consistent
behavior - users either have externalization on or off, no edge cases.

* refactor(plugin): use one JSON file per component with spread props

Implements slorber's suggestion to externalize all props for a component
into a single JSON file and use spread syntax:

  <StatusCodes {...require('./add-pet.StatusCodes.json')} />

Instead of separate files per prop:

  <StatusCodes responses={require('./add-pet.responses.json')} />

Benefits:
- Cleaner file organization (one file per component vs per prop)
- Simpler logic (no need to track which props to externalize)
- All props for a component are colocated in one file

* refactor(plugin): use runWithExternalization wrapper for cleaner API

Provides a cleaner API similar to AsyncLocalStorage pattern but uses
module-level state internally (AsyncLocalStorage isn't available in
browser bundles that Docusaurus creates).

The runWithExternalization() function wraps generation with try/finally
to ensure context is always cleaned up, providing the same safety
guarantees as AsyncLocalStorage.run().

Author: sserrata

packages/docusaurus-plugin-openapi-docs/src/index.ts

@@ -21,10 +21,7 @@ import {
   createSchemaPageMD,
   createTagPageMD,
 } from "./markdown";
-import {
-  externalizeJsonPropsSimple,
-  ExternalizedJsonFile,
-} from "./markdown/externalizeJsonProps";
+import { ExternalFile, runWithExternalization } from "./markdown/utils";
 import { processOpenapiFiles, readOpenapiFiles } from "./openapi";
 import { OptionsSchema } from "./options";
 import generateSidebarSlice from "./sidebars";
@@ -337,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;
         }
@@ -388,32 +398,18 @@ custom_edit_url: null
                 );
               }
 
-              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}"`)
-                    );
-                  }
+              // 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`,
-                finalView,
-                "utf8"
-              );
+              fs.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
               console.log(
                 chalk.green(
                   `Successfully created "${outputDir}/${item.id}.api.mdx"`
@@ -499,24 +495,16 @@ custom_edit_url: null
                 throw Error("Schema must have title defined");
               }
               // eslint-disable-next-line testing-library/render-result-naming-convention
-              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}"`)
-                    );
-                  }
+              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}"`)
+                  );
                 }
               }