Skip to content

Commit

Permalink
Add optional markdownGenerators config option (#567)
Browse files Browse the repository at this point in the history
* Add optional markdownGenerators config option to allow high level of customization

* Update docs to add markdownGenerators config option
  • Loading branch information
jgarrow authored May 5, 2023
1 parent 111dbd6 commit 746b809
Show file tree
Hide file tree
Showing 4 changed files with 64 additions and 20 deletions.
47 changes: 32 additions & 15 deletions demo/docs/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.<br/><br/>**Function type:** `(pageData: ApiPageMetadata) => string` |
| `createInfoPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `(pageData: InfoPageMetadata) => string` |
| `createTagPageMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**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`:
Expand Down Expand Up @@ -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).
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).
23 changes: 18 additions & 5 deletions packages/docusaurus-plugin-openapi-docs/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(/\/$/, "");
Expand Down Expand Up @@ -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)) {
Expand All @@ -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);
Expand Down
7 changes: 7 additions & 0 deletions packages/docusaurus-plugin-openapi-docs/src/options.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
Expand All @@ -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(),
Expand Down
7 changes: 7 additions & 0 deletions packages/docusaurus-plugin-openapi-docs/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down

0 comments on commit 746b809

Please sign in to comment.