Skip to content

Commit 746b809

Browse files
jgarrowjgarrow
authored
Add optional markdownGenerators config option (#567)
* Add optional markdownGenerators config option to allow high level of customization * Update docs to add markdownGenerators config option
1 parent 111dbd6 commit 746b809

File tree

4 files changed

+64
-20
lines changed

4 files changed

+64
-20
lines changed

‎demo/docs/intro.mdx‎

Lines changed: 32 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -297,20 +297,21 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
297297

298298
`config` can be configured with the following options:
299299

300-
| Name | Type | Default | Description |
301-
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
302-
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
303-
| `ouputDir` | `string` | `null` | Desired output path for generated MDX files. |
304-
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
305-
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
306-
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
307-
| `hideSendButton` | `boolean`| `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel. |
308-
| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. |
309-
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
310-
| `version` | `string` | `null` | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`. |
311-
| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
312-
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
313-
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
300+
| Name | Type | Default | Description |
301+
| -------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
302+
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
303+
| `ouputDir` | `string` | `null` | Desired output path for generated MDX files. |
304+
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
305+
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
306+
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
307+
| `hideSendButton` | `boolean`| `null` | _Optional:_ If set to `true`, hides the "Send API Request" button in API demo panel. |
308+
| `showExtensions` | `boolean`| `null` | _Optional:_ If set to `true`, renders operation-level vendor-extensions in description. |
309+
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
310+
| `version` | `string` | `null` | _Optional:_ Version assigned to single or micro-spec API specified in `specPath`. |
311+
| `label` | `string` | `null` | _Optional:_ Version label used when generating version selector dropdown menu. |
312+
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating version selector dropdown menu. |
313+
| `versions` | `object` | `null` | _Optional:_ Set of options for versioning configuration. See below for a list of supported options. |
314+
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content with a set of options for markdown generator configuration. See below for a list of supported options. |
314315

315316
### sidebarOptions
316317

@@ -344,6 +345,22 @@ You may optionally configure a `sidebarOptions`. In doing so, an individual `sid
344345
All versions will automatically inherit `sidebarOptions` from the parent/base config.
345346
:::
346347

348+
### markdownGenerators
349+
350+
`markdownGenerators` can be configured with the following options:
351+
352+
| Name | Type | Default | Description |
353+
| ------------------ | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------|
354+
| `createApiPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for API pages.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
355+
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
356+
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `(pageData: TagPageMetadata) => string` |
357+
358+
:::info NOTE
359+
If a config option is not provided, its default markdown generator will be used.
360+
361+
This config option is intended for advanced users who wish to highly customize the markdown content and layout of generated pages.
362+
:::
363+
347364
## Installing from Template
348365

349366
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
397414

398415
See [SUPPORT.md](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/main/SUPPORT.md) for our support agreement and guidelines.
399416

400-
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).
417+
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‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,14 @@ export default function pluginOpenAPIDocs(
9191
let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
9292

9393
async function generateApiDocs(options: APIOptions, pluginId: any) {
94-
let { specPath, outputDir, template, downloadUrl, sidebarOptions } =
95-
options;
94+
let {
95+
specPath,
96+
outputDir,
97+
template,
98+
markdownGenerators,
99+
downloadUrl,
100+
sidebarOptions,
101+
} = options;
96102

97103
// Remove trailing slash before proceeding
98104
outputDir = outputDir.replace(/\/$/, "");
@@ -237,6 +243,13 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
237243
\`\`\`
238244
`;
239245

246+
const apiPageGenerator =
247+
markdownGenerators?.createApiPageMD ?? createApiPageMD;
248+
const infoPageGenerator =
249+
markdownGenerators?.createInfoPageMD ?? createInfoPageMD;
250+
const tagPageGenerator =
251+
markdownGenerators?.createTagPageMD ?? createTagPageMD;
252+
240253
loadedApi.map(async (item) => {
241254
if (item.type === "info") {
242255
if (downloadUrl && isURL(downloadUrl)) {
@@ -245,10 +258,10 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
245258
}
246259
const markdown =
247260
item.type === "api"
248-
? createApiPageMD(item)
261+
? apiPageGenerator(item)
249262
: item.type === "info"
250-
? createInfoPageMD(item)
251-
: createTagPageMD(item);
263+
? infoPageGenerator(item)
264+
: tagPageGenerator(item);
252265
item.markdown = markdown;
253266
if (item.type === "api") {
254267
item.json = JSON.stringify(item.api);

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ const sidebarOptions = Joi.object({
1616
sidebarCollapsed: Joi.boolean(),
1717
});
1818

19+
const markdownGenerators = Joi.object({
20+
createApiPageMD: Joi.function(),
21+
createInfoPageMD: Joi.function(),
22+
createTagPageMD: Joi.function(),
23+
});
24+
1925
export const OptionsSchema = Joi.object({
2026
id: Joi.string().required(),
2127
docsPluginId: Joi.string().required(),
@@ -31,6 +37,7 @@ export const OptionsSchema = Joi.object({
3137
hideSendButton: Joi.boolean(),
3238
showExtensions: Joi.boolean(),
3339
sidebarOptions: sidebarOptions,
40+
markdownGenerators: markdownGenerators,
3441
version: Joi.string().when("versions", {
3542
is: Joi.exist(),
3643
then: Joi.required(),

‎packages/docusaurus-plugin-openapi-docs/src/types.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,13 @@ export interface APIOptions {
4343
[key: string]: APIVersionOptions;
4444
};
4545
proxy?: string;
46+
markdownGenerators?: MarkdownGenerator;
47+
}
48+
49+
export interface MarkdownGenerator {
50+
createApiPageMD?: (pageData: ApiPageMetadata) => string;
51+
createInfoPageMD?: (pageData: InfoPageMetadata) => string;
52+
createTagPageMD?: (pageData: TagPageMetadata) => string;
4653
}
4754

4855
export interface SidebarOptions {

0 commit comments

Comments
 (0)