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 {