Skip to content

Commit 58bbebd

Browse files
feat: add support to info, and tag, and schema custom tamplates (#1122)
* feat: add support to info, and tag, and schema custom tamplates * docs: enhance template samples * fix: ensure infoTemplate is used to generate the Introduction page
1 parent 404ddd1 commit 58bbebd

File tree

8 files changed

+109
-17
lines changed

8 files changed

+109
-17
lines changed

demo/docusaurus.config.ts

+4-1
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,10 @@ const config: Config = {
297297
groupPathsBy: "tag",
298298
categoryLinkSource: "tag",
299299
},
300-
template: "api.mustache", // Customize API MDX with mustache template
300+
template: "templates/api.mustache", // Customize API MDX with mustache template
301+
infoTemplate: "templates/info.mustache",
302+
tagTemplate: "templates/tag.mustache",
303+
schemaTemplate: "templates/schema.mustache",
301304
downloadUrl: "/petstore.yaml",
302305
hideSendButton: false,
303306
showSchemas: true,

demo/api.mustache renamed to demo/templates/api.mustache

+13-1
Original file line numberDiff line numberDiff line change
@@ -36,4 +36,16 @@ show_extensions: true
3636
{{/frontMatter.show_extensions}}
3737
---
3838

39-
{{{markdown}}}
39+
This is a Custom Api Page Generated by docusaurus-openapi-docs using `api.mustache` template
40+
41+
<hr />
42+
<br />
43+
<br />
44+
45+
{{{markdown}}}
46+
47+
<br />
48+
<br />
49+
<hr />
50+
51+
This is a Custom Api Page Generated by docusaurus-openapi-docs using `api.mustache` template

demo/templates/info.mustache

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
id: {{{id}}}
3+
title: "{{{title}}}"
4+
description: "{{{frontMatter.description}}}"
5+
sidebar_label: "{{{title}}}"
6+
hide_title: true
7+
custom_edit_url: null
8+
---
9+
10+
This is a Custom Info Page Generated by docusaurus-openapi-docs using `info.mustache` template
11+
12+
<hr />
13+
<br />
14+
<br />
15+
16+
{{{markdown}}}
17+
18+
<br />
19+
<br />
20+
<hr />
21+
22+
This is a Custom Info Page Generated by docusaurus-openapi-docs using `info.mustache` template

demo/templates/schema.mustache

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
id: {{{id}}}
3+
title: "{{{title}}}"
4+
description: "{{{frontMatter.description}}}"
5+
sidebar_label: "{{{title}}}"
6+
hide_title: true
7+
{{#schema}}
8+
hide_table_of_contents: true
9+
{{/schema}}
10+
schema: true
11+
sample: {{{frontMatter.sample}}}
12+
custom_edit_url: null
13+
---
14+
15+
This is a Custom Schema Page Generated by docusaurus-openapi-docs using `schema.mustache` template
16+
17+
<hr />
18+
<br />
19+
<br />
20+
21+
{{{markdown}}}
22+
23+
<br />
24+
<br />
25+
<hr />
26+
27+
This is a Custom Schema Page Generated by docusaurus-openapi-docs using `schema.mustache` template

demo/templates/tag.mustache

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
id: {{{id}}}
3+
title: "{{{frontMatter.description}}}"
4+
description: "{{{frontMatter.description}}}"
5+
custom_edit_url: null
6+
---
7+
8+
This is a Custom Tag Page Generated by docusaurus-openapi-docs using `tag.mustache` template
9+
10+
<hr />
11+
<br />
12+
<br />
13+
14+
{{{markdown}}}
15+
16+
<br />
17+
<br />
18+
<hr />
19+
20+
This is a Custom Tag Page Generated by docusaurus-openapi-docs using `tag.mustache` template

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

+17-15
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,9 @@ export default function pluginOpenAPIDocs(
117117
specPath,
118118
outputDir,
119119
template,
120+
infoTemplate,
121+
tagTemplate,
122+
schemaTemplate,
120123
markdownGenerators,
121124
downloadUrl,
122125
sidebarOptions,
@@ -236,7 +239,9 @@ show_extensions: true
236239
{{{markdown}}}
237240
`;
238241

239-
const infoMdTemplate = `---
242+
const infoMdTemplate = infoTemplate
243+
? fs.readFileSync(infoTemplate).toString()
244+
: `---
240245
id: {{{id}}}
241246
title: "{{{title}}}"
242247
description: "{{{frontMatter.description}}}"
@@ -255,7 +260,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
255260
\`\`\`
256261
`;
257262

258-
const tagMdTemplate = `---
263+
const tagMdTemplate = tagTemplate
264+
? fs.readFileSync(tagTemplate).toString()
265+
: `---
259266
id: {{{id}}}
260267
title: "{{{frontMatter.description}}}"
261268
description: "{{{frontMatter.description}}}"
@@ -272,7 +279,9 @@ import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
272279
\`\`\`
273280
`;
274281

275-
const schemaMdTemplate = `---
282+
const schemaMdTemplate = schemaTemplate
283+
? fs.readFileSync(schemaTemplate).toString()
284+
: `---
276285
id: {{{id}}}
277286
title: "{{{title}}}"
278287
description: "{{{frontMatter.description}}}"
@@ -371,21 +380,14 @@ custom_edit_url: null
371380
}
372381
}
373382

374-
// TODO: determine if we actually want/need this
375383
if (item.type === "info") {
376384
if (!fs.existsSync(`${outputDir}/${item.id}.info.mdx`)) {
377385
try {
378-
sidebarOptions?.categoryLinkSource === "info" // Only use utils template if set to "info"
379-
? fs.writeFileSync(
380-
`${outputDir}/${item.id}.info.mdx`,
381-
utils,
382-
"utf8"
383-
)
384-
: fs.writeFileSync(
385-
`${outputDir}/${item.id}.info.mdx`,
386-
view,
387-
"utf8"
388-
);
386+
fs.writeFileSync(
387+
`${outputDir}/${item.id}.info.mdx`,
388+
utils,
389+
"utf8"
390+
);
389391
console.log(
390392
chalk.green(
391393
`Successfully created "${outputDir}/${item.id}.info.mdx"`

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

+3
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ export const OptionsSchema = Joi.object({
3939
proxy: Joi.string(),
4040
outputDir: Joi.string().required(),
4141
template: Joi.string(),
42+
infoTemplate: Joi.string(),
43+
tagTemplate: Joi.string(),
44+
schemaTemplate: Joi.string(),
4245
downloadUrl: Joi.string(),
4346
hideSendButton: Joi.boolean(),
4447
showExtensions: Joi.boolean(),

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

+3
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@ export interface APIOptions {
3535
specPath: string;
3636
outputDir: string;
3737
template?: string;
38+
infoTemplate?: string;
39+
tagTemplate?: string;
40+
schemaTemplate?: string;
3841
downloadUrl?: string;
3942
hideSendButton?: boolean;
4043
showExtensions?: boolean;

0 commit comments

Comments
 (0)