diff --git a/demo/docusaurus.config.ts b/demo/docusaurus.config.ts index b4a1baffb..e92349142 100644 --- a/demo/docusaurus.config.ts +++ b/demo/docusaurus.config.ts @@ -299,6 +299,9 @@ const config: Config = { groupPathsBy: "tag", categoryLinkSource: "tag", }, + markdownGenerators: { + createInfoPageMD: true, + }, // 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 +321,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: false, + }, // 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..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.

**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 486a13751..146a88836 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 false + if ( + (openapiData.info.description || openapiData.info.title) && + options.markdownGenerators?.createInfoPageMD !== false + ) { 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..acff02831 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, 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 0c65e4360..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; + createInfoPageMD?: ((pageData: InfoPageMetadata) => string) | boolean; createTagPageMD?: (pageData: TagPageMetadata) => string; createSchemaPageMD?: (pageData: SchemaPageMetadata) => string; }