Update template plugin configuration property to be either a string or file path #1243
Description
Is your feature request related to a problem?
The docusaurus-plugin-openapi-docs accepts a configuration object and one of it's properties is template. As defined in the README, this properties type is a string and it's description is "Optional: Customize MDX content with a desired template." In code, if this property is truthy, we attempt to fs.readFileSync the value of template, which implies that template is meant to be a file path, rather than an actual string template (which the type and description seem to imply).
Describe the solution you'd like
I would like to propose that template can be either a template string, or a file path string. This can be accomplished by doing an fs.existsSync or fs.fstatSync (and catching the error if the path is not valid). If that file path exists, then utilise it, and if it doesn't and the value of template is truthy than we can check if it's a string and use it.
Describe alternatives you've considered
Alternatively, we could change from using template as a string or as an object and the shape of the object could be the following or some variation.
interface TemplateOptions {
templateFilePath?: string;
templateString?: string;
}This would allow us to keep backwards compatibility with template still being allowed to be a string, for those stakeholders that are configuration the plugin that way.
Additional context
ℹ️ I'm happy to contribute this feature myself, and am open to feedback on the idea.
Additionally, the configuration options have template, as well as infoTemplate, tagTemplate, and schemaTemplate. All of these could be rolled into the TemplateOptions options configuration if we wanted to consolidate and give access to "templates" in a more uniform way (similar to how we're doing it with markdownGenerators).
interface TemplateConfig {
filePath?: string;
templateString?: string;
}
interface TemplateOptions {
introTemplate?: TemplateConfig;
infoTemplate?: TemplateConfig;
tagTemplate?: TemplateConfig;
schemaTemplate?: TemplateConfig;
}We could also go down a similar route as the markdownGenerators and expose a templateGenerators rather than the "template options".
interface TemplateGenerators {
// INFO: could provide the `item` to the function closure to allow more
// templating flexibility as well as the `render` method we get
// from `mustache` if we want to expose that to consumer
createIntroMDTemplate?: (render: pageData: ApiMetadata) => string;
createInfoMDTemplate?: (pageData: ApiMetadata) => string;
createTagMDTemplate?: (pageData: ApiMetadata) => string;
createSchemaMDTemplate?: (pageData: ApiMetadata) => string;
}