Skip to content

Commit 4975f0e

Browse files
mikemimikmikemimik
committed
chore: update docs in demo
- update intro page with section on template generators
1 parent 88bc79d commit 4975f0e

File tree

1 file changed

+46
-15
lines changed

1 file changed

+46
-15
lines changed

‎demo/docs/intro.mdx‎

Lines changed: 46 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ OpenAPI plugin for generating API reference docs in Docusaurus v3.
2929

3030
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/LICENSE) [![npm latest package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/latest.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm downloads](https://img.shields.io/npm/dm/docusaurus-plugin-openapi-docs.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm canary package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/canary.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm beta package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/beta.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs)
3131

32-
3332
<iframe
3433
src="https://ghbtns.com/github-btn.html?user=PaloAltoNetworks&amp;repo=docusaurus-openapi-docs&amp;type=star&amp;count=true&amp;size=large"
3534
width={160}
@@ -82,7 +81,6 @@ Other ReDoc specific extensions such as `x-circular-ref`, `x-code-samples` (depr
8281
| 2.2.3 (legacy) | `2.4.1 - 2.4.3` |
8382
| 1.7.3 (end-of-support) | `2.0.1 - 2.2.0` |
8483

85-
8684
:::tip
8785
If you're building a Docusaurus site from scratch, the easiest way to get started is by [installing from template](#bootstrapping-from-template-new-docusaurus-site).
8886
:::
@@ -207,20 +205,21 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
207205
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
208206
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
209207
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
210-
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
211-
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
212-
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
213-
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
214-
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
215-
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
216-
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
208+
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template _(path to file holding template)_. |
209+
| `templateGenerators` | `object` | `null` | _Optional:_ Customize MDX content with generator functions. See below for a list of supported options. |
210+
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
211+
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
212+
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
213+
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
214+
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
215+
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
217216
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
218-
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
219-
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
220-
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
221-
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
222-
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
223-
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
217+
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
218+
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
219+
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
220+
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
221+
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
222+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
224223

225224
### sidebarOptions
226225

@@ -246,8 +245,40 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
246245
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version selector dropdown menu. |
247246
| `baseUrl` | `string` | `null` | _Optional:_ Version base URL used when generating the version selector dropdown menu. |
248247
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading the versioned OpenAPI specification. |
248+
249249
> All versions will automatically inherit `sidebarOptions` from the parent/base config.
250250

251+
### templateGenerators
252+
253+
`templateGenerators` can be configured with the following options:
254+
255+
| Name | Type | Default | Description |
256+
| ---------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
257+
| `createIntroTemplateMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for introduction page.<br/><br/>**Function type:** `() => string` |
258+
| `createInfoTemplateMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for info pages.<br/><br/>**Function type:** `() => string` |
259+
| `createTagTemplateMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for tag pages.<br/><br/>**Function type:** `() => string` |
260+
| `createSchemaTemplateMD` | `function` | `null` | _Optional:_ Returns a string of the raw markdown body for schema pages.<br/><br/>**Function type:** `() => string` |
261+
262+
Example:
263+
264+
```typescript
265+
petstore31: {
266+
specPath: "examples/petstore-3.1.yaml",
267+
proxy: "https://cors.pan.dev",
268+
outputDir: "docs/petstore31",
269+
sidebarOptions: {
270+
groupPathsBy: "tag",
271+
categoryLinkSource: "tag",
272+
},
273+
downloadUrl: "/petstore-3.1.yaml",
274+
hideSendButton: false,
275+
showSchemas: true,
276+
markdownGenerators: {
277+
createIntroTemplateMD: myCustomInfroMdGenerator
278+
}, // customize markdown generator
279+
} satisfies OpenApiPlugin.Options,
280+
```
281+
251282
### markdownGenerators
252283

253284
`markdownGenerators` can be configured with the following options:

0 commit comments

Comments
 (0)