Cherry-pick markdown generator changes #567 from v1

demo/docs/intro.mdx

@@ -415,4 +415,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).
+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).

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

@@ -92,8 +92,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(/\/$/, "");
@@ -238,12 +244,26 @@ 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)) {
             item.downloadUrl = downloadUrl;
           }
         }
+        const markdown =
+          item.type === "api"
+            ? apiPageGenerator(item)
+            : item.type === "info"
+            ? infoPageGenerator(item)
+            : tagPageGenerator(item);
+        item.markdown = markdown;
         if (item.type === "api") {
           // opportunity to compress JSON
           // const serialize = (o: any) => {
@@ -263,13 +283,6 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
           }
           if (item.infoId) item.infoPath = infoBasePath;
         }
-        const markdown =
-          item.type === "api"
-            ? createApiPageMD(item)
-            : item.type === "info"
-            ? createInfoPageMD(item)
-            : createTagPageMD(item);
-        item.markdown = markdown;
 
         const view = render(mdTemplate, item);
         const utils = render(infoMdTemplate, item);

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

@@ -15,6 +15,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(),
@@ -30,6 +36,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(),

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 {