From 290555ebdbcc73b8b53dfc8ec42829cd9e1db6bd Mon Sep 17 00:00:00 2001 From: Devon White Date: Fri, 31 Oct 2025 19:52:26 -0400 Subject: [PATCH 1/3] Add ability to turn of info page generation --- demo/docusaurus.config.ts | 10 +++++++++- packages/docusaurus-plugin-openapi-docs/README.md | 12 ++++++------ .../src/openapi/openapi.ts | 7 +++++-- .../docusaurus-plugin-openapi-docs/src/options.ts | 3 ++- packages/docusaurus-plugin-openapi-docs/src/types.ts | 2 +- 5 files changed, 23 insertions(+), 11 deletions(-) diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts index b4a1baffb..a78d9585c 100644 --- a/demo/docusaurus.config.ts +++ b/demo/docusaurus.config.ts @@ -299,6 +299,10 @@ const config: Config = { groupPathsBy: "tag", categoryLinkSource: "tag", }, + markdownGenerators: { + // Explicitly disable info page generation for testing + createInfoPageMD: null, + }, // customize MDX with markdown generator template: "templates/api.mustache", // Customize API MDX with mustache template infoTemplate: "templates/info.mustache", tagTemplate: "templates/tag.mustache", @@ -318,7 +322,11 @@ const config: Config = { downloadUrl: "/petstore-3.1.yaml", hideSendButton: false, showSchemas: true, - markdownGenerators: { createApiPageMD: myCustomApiMdGenerator }, // customize MDX with markdown generator + markdownGenerators: { + createApiPageMD: myCustomApiMdGenerator, + // Explicitly disable info page generation for testing + createInfoPageMD: null, + }, // customize MDX with markdown generator } satisfies OpenApiPlugin.Options, cos: { specPath: "examples/openapi-cos.json", diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index c09d4eb19..cb81246dd 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/packages/docusaurus-plugin-openapi-docs/README.md @@ -209,12 +209,12 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following `markdownGenerators` can be configured with the following options: -| Name | Type | Default | Description | -| -------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | -| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.

**Function type:** `(pageData: InfoPageMetadata) => string` | -| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | -| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | +| Name | Type | Default | Description | +| -------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | +| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages. Set to `null` to explicitly disable info page generation.

**Function type:** `(pageData: InfoPageMetadata) => string` | +| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | +| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | ### sidebarGenerators diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts index 486a13751..4d31a8abc 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts @@ -96,8 +96,11 @@ function createItems( const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase(); const infoId = kebabCase(infoIdSpaces); - if (openapiData.info.description || openapiData.info.title) { - // Only create an info page if we have a description. + // Only create an info page if we have a description/title AND createInfoPageMD is not explicitly null + if ( + (openapiData.info.description || openapiData.info.title) && + options.markdownGenerators?.createInfoPageMD !== null + ) { const infoDescription = openapiData.info?.description; let splitDescription: any; if (infoDescription) { diff --git a/packages/docusaurus-plugin-openapi-docs/src/options.ts b/packages/docusaurus-plugin-openapi-docs/src/options.ts index 9bad1d90f..a5f6ee81c 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/options.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/options.ts @@ -22,7 +22,8 @@ const sidebarOptions = Joi.object({ const markdownGenerators = Joi.object({ createApiPageMD: Joi.function(), - createInfoPageMD: Joi.function(), + // Allow createInfoPageMD to be a function or explicitly null to disable info page generation + createInfoPageMD: Joi.alternatives().try(Joi.function(), Joi.valid(null)), createTagPageMD: Joi.function(), createSchemaPageMD: Joi.function(), }); diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index 0c65e4360..33b625528 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -57,7 +57,7 @@ export interface APIOptions { export interface MarkdownGenerator { createApiPageMD?: (pageData: ApiPageMetadata) => string; - createInfoPageMD?: (pageData: InfoPageMetadata) => string; + createInfoPageMD?: ((pageData: InfoPageMetadata) => string) | null; createTagPageMD?: (pageData: TagPageMetadata) => string; createSchemaPageMD?: (pageData: SchemaPageMetadata) => string; } From 49eafcdee5304482eb28f0f3e56de5da6a36dd0e Mon Sep 17 00:00:00 2001 From: Devon White Date: Sun, 2 Nov 2025 00:13:57 -0400 Subject: [PATCH 2/3] Change to bool type --- demo/docusaurus.config.ts | 4 ++-- packages/docusaurus-plugin-openapi-docs/README.md | 12 ++++++------ packages/docusaurus-plugin-openapi-docs/src/index.ts | 8 +++++++- .../src/openapi/openapi.ts | 4 ++-- .../docusaurus-plugin-openapi-docs/src/options.ts | 4 ++-- packages/docusaurus-plugin-openapi-docs/src/types.ts | 2 +- 6 files changed, 20 insertions(+), 14 deletions(-) diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts index a78d9585c..10138b79f 100644 --- a/demo/docusaurus.config.ts +++ b/demo/docusaurus.config.ts @@ -301,7 +301,7 @@ const config: Config = { }, markdownGenerators: { // Explicitly disable info page generation for testing - createInfoPageMD: null, + createInfoPageMD: true, }, // customize MDX with markdown generator template: "templates/api.mustache", // Customize API MDX with mustache template infoTemplate: "templates/info.mustache", @@ -325,7 +325,7 @@ const config: Config = { markdownGenerators: { createApiPageMD: myCustomApiMdGenerator, // Explicitly disable info page generation for testing - createInfoPageMD: null, + createInfoPageMD: false, }, // customize MDX with markdown generator } satisfies OpenApiPlugin.Options, cos: { diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index cb81246dd..ce22f43ff 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/packages/docusaurus-plugin-openapi-docs/README.md @@ -209,12 +209,12 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following `markdownGenerators` can be configured with the following options: -| Name | Type | Default | Description | -| -------------------- | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | -| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages. Set to `null` to explicitly disable info page generation.

**Function type:** `(pageData: InfoPageMetadata) => string` | -| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | -| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | +| Name | Type | Default | Description | +| -------------------- | --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.

**Function type:** `(pageData: ApiPageMetadata) => string` | +| `createInfoPageMD` | `function \| boolean` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages. Set to `false` to explicitly disable info page generation. Set to `true` to explicitly enable with default generator.

**Function type:** `(pageData: InfoPageMetadata) => string` | +| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.

**Function type:** `(pageData: TagPageMetadata) => string` | +| `createSchemaPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.

**Function type:** `(pageData: SchemaPageMetadata) => string` | ### sidebarGenerators diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 570fcf2b5..d05081f90 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -303,8 +303,14 @@ custom_edit_url: null const apiPageGenerator = markdownGenerators?.createApiPageMD ?? createApiPageMD; + + // Handle boolean values for createInfoPageMD + // true or undefined = use default, false = disabled (won't be called), function = use custom const infoPageGenerator = - markdownGenerators?.createInfoPageMD ?? createInfoPageMD; + typeof markdownGenerators?.createInfoPageMD === "function" + ? markdownGenerators.createInfoPageMD + : createInfoPageMD; + const tagPageGenerator = markdownGenerators?.createTagPageMD ?? createTagPageMD; const schemaPageGenerator = diff --git a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts index 4d31a8abc..146a88836 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/openapi/openapi.ts @@ -96,10 +96,10 @@ function createItems( const infoIdSpaces = openapiData.info.title.replace(" ", "-").toLowerCase(); const infoId = kebabCase(infoIdSpaces); - // Only create an info page if we have a description/title AND createInfoPageMD is not explicitly null + // Only create an info page if we have a description/title AND createInfoPageMD is not explicitly false if ( (openapiData.info.description || openapiData.info.title) && - options.markdownGenerators?.createInfoPageMD !== null + options.markdownGenerators?.createInfoPageMD !== false ) { const infoDescription = openapiData.info?.description; let splitDescription: any; diff --git a/packages/docusaurus-plugin-openapi-docs/src/options.ts b/packages/docusaurus-plugin-openapi-docs/src/options.ts index a5f6ee81c..acff02831 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/options.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/options.ts @@ -22,8 +22,8 @@ const sidebarOptions = Joi.object({ const markdownGenerators = Joi.object({ createApiPageMD: Joi.function(), - // Allow createInfoPageMD to be a function or explicitly null to disable info page generation - createInfoPageMD: Joi.alternatives().try(Joi.function(), Joi.valid(null)), + // Allow createInfoPageMD to be a function, true (use default), or false (disable) + createInfoPageMD: Joi.alternatives().try(Joi.function(), Joi.boolean()), createTagPageMD: Joi.function(), createSchemaPageMD: Joi.function(), }); diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index 33b625528..5f058edca 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -57,7 +57,7 @@ export interface APIOptions { export interface MarkdownGenerator { createApiPageMD?: (pageData: ApiPageMetadata) => string; - createInfoPageMD?: ((pageData: InfoPageMetadata) => string) | null; + createInfoPageMD?: ((pageData: InfoPageMetadata) => string) | boolean; createTagPageMD?: (pageData: TagPageMetadata) => string; createSchemaPageMD?: (pageData: SchemaPageMetadata) => string; } From e9c4609d09cdf2ff6757def6e1825e7d7dbf6438 Mon Sep 17 00:00:00 2001 From: Devon White Date: Sun, 2 Nov 2025 00:15:32 -0400 Subject: [PATCH 3/3] remove comment --- demo/docusaurus.config.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts index 10138b79f..e92349142 100644 --- a/demo/docusaurus.config.ts +++ b/demo/docusaurus.config.ts @@ -300,7 +300,6 @@ const config: Config = { categoryLinkSource: "tag", }, markdownGenerators: { - // Explicitly disable info page generation for testing createInfoPageMD: true, }, // customize MDX with markdown generator template: "templates/api.mustache", // Customize API MDX with mustache template