docusaurus-openapi-docs icon indicating copy to clipboard operation
docusaurus-openapi-docs copied to clipboard

Allow custom markdown templates for all generated docs

Open AnnaWinnick opened this issue 1 year ago • 0 comments

Is your feature request related to a problem?

I have been trying to create schema pages for my api within an autogenerated sidebar, but I have run into several situations where I feel like I am fighting this plugin to make the changes I would like.

Describe the solution you'd like

Along with solving this issue, enabling custom markdown templates for all api docs would be useful in allowing user customization and control.

I propose adding an additional templates section in the config (similar to markdown generators).

plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'openapi',
        docsPluginId: 'classic',
        config: {
          api-name: {
            specPath: "api.yaml",
            outputDir: "docs/generated",
            markdownGenerators: { 
              createApiPageMD: apiMarkdownGenerator,
              createSchemaPageMD: schemaMarkdownGenerator,
            }, 
            templates: {
              apiMDTemplate: apiMarkdownTemplate,
              schemaMDTemplate: schemaMarkdownTemplate,
            }
            showSchemas: true,
          } ,
        },
      },
    ]
  ],

Describe alternatives you've considered

Currently I have a patch package in place to edit the markdown templates in docusaurus-plugin-openapi-docs/lib/index.js. I considered proposing a change only to allow schema page template edits, however it seems like there is opportunity for more generalization here while looking at this code portion.

Another way to solve this problem may be to include front matter in the markdown generator, however this seems like a greater lift.

Happy to help with a PR.

Additional context

AnnaWinnick avatar Oct 17 '24 16:10 AnnaWinnick