diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx index 7d3b74624..e6eb74db9 100644 --- a/demo/docs/intro.mdx +++ b/demo/docs/intro.mdx @@ -297,20 +297,21 @@ 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. | -| `ouputDir` | `string` | `null` | Desired output path for generated MDX files. | -| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | -| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | -| `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 API demo panel. | -| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | -| `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 single or micro-spec API specified in `specPath`. | -| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. | -| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. | -| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported 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. | +| `ouputDir` | `string` | `null` | Desired output path for generated MDX files. | +| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. | +| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. | +| `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 API demo panel. | +| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. | +| `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 single or micro-spec API specified in `specPath`. | +| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. | +| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. | +| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. | +| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for markdown generator configuration. See below for a list of supported options. | ### sidebarOptions @@ -344,6 +345,22 @@ You may optionally configure a `sidebarOptions`. In doing so, an individual `sid All versions will automatically inherit `sidebarOptions` from the parent/base config. ::: +### markdownGenerators + +`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` | + +:::info NOTE +If a config option is not provided, its default markdown generator will be used. + +This config option is intended for advanced users who wish to highly customize the markdown content and layout of generated pages. +::: + ## Installing from Template Run the following to bootstrap a Docsaurus v2 site (classic theme) with `docusaurus-openapi-docs`: @@ -397,4 +414,4 @@ For more insight into why we decided to completely fork see [#47](https://github See [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for our support agreement and guidelines. -If you believe you found a bug or have an idea you'd like to suggest you may [report an issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/new/choose) or [start a discussion](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/discussions/new/choose). \ No newline at end of file +If you believe you found a bug or have an idea you'd like to suggest you may [report an issue](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/new/choose) or [start a discussion](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/discussions/new/choose). diff --git a/packages/docusaurus-plugin-openapi-docs/src/index.ts b/packages/docusaurus-plugin-openapi-docs/src/index.ts index 4f26f8996..a50d17f3e 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/index.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/index.ts @@ -91,8 +91,14 @@ export default function pluginOpenAPIDocs( let docPath = docData ? (docData.path ? docData.path : "docs") : undefined; async function generateApiDocs(options: APIOptions, pluginId: any) { - let { specPath, outputDir, template, downloadUrl, sidebarOptions } = - options; + let { + specPath, + outputDir, + template, + markdownGenerators, + downloadUrl, + sidebarOptions, + } = options; // Remove trailing slash before proceeding outputDir = outputDir.replace(/\/$/, ""); @@ -237,6 +243,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; \`\`\` `; + const apiPageGenerator = + markdownGenerators?.createApiPageMD ?? createApiPageMD; + const infoPageGenerator = + markdownGenerators?.createInfoPageMD ?? createInfoPageMD; + const tagPageGenerator = + markdownGenerators?.createTagPageMD ?? createTagPageMD; + loadedApi.map(async (item) => { if (item.type === "info") { if (downloadUrl && isURL(downloadUrl)) { @@ -245,10 +258,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; } const markdown = item.type === "api" - ? createApiPageMD(item) + ? apiPageGenerator(item) : item.type === "info" - ? createInfoPageMD(item) - : createTagPageMD(item); + ? infoPageGenerator(item) + : tagPageGenerator(item); item.markdown = markdown; if (item.type === "api") { item.json = JSON.stringify(item.api); diff --git a/packages/docusaurus-plugin-openapi-docs/src/options.ts b/packages/docusaurus-plugin-openapi-docs/src/options.ts index 7525bc371..e3ca17ab7 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/options.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/options.ts @@ -16,6 +16,12 @@ const sidebarOptions = Joi.object({ sidebarCollapsed: Joi.boolean(), }); +const markdownGenerators = Joi.object({ + createApiPageMD: Joi.function(), + createInfoPageMD: Joi.function(), + createTagPageMD: Joi.function(), +}); + export const OptionsSchema = Joi.object({ id: Joi.string().required(), docsPluginId: Joi.string().required(), @@ -31,6 +37,7 @@ export const OptionsSchema = Joi.object({ hideSendButton: Joi.boolean(), showExtensions: Joi.boolean(), sidebarOptions: sidebarOptions, + markdownGenerators: markdownGenerators, version: Joi.string().when("versions", { is: Joi.exist(), then: Joi.required(), diff --git a/packages/docusaurus-plugin-openapi-docs/src/types.ts b/packages/docusaurus-plugin-openapi-docs/src/types.ts index 38d865a1e..ee6862285 100644 --- a/packages/docusaurus-plugin-openapi-docs/src/types.ts +++ b/packages/docusaurus-plugin-openapi-docs/src/types.ts @@ -43,6 +43,13 @@ export interface APIOptions { [key: string]: APIVersionOptions; }; proxy?: string; + markdownGenerators?: MarkdownGenerator; +} + +export interface MarkdownGenerator { + createApiPageMD?: (pageData: ApiPageMetadata) => string; + createInfoPageMD?: (pageData: InfoPageMetadata) => string; + createTagPageMD?: (pageData: TagPageMetadata) => string; } export interface SidebarOptions {