feat: template generators

[mikemimik]

Description

Motivation and Context

• Feature Request: Update template plugin configuration property to be either a string or file path #1243
• We want more control over the mustache templates that are used

How Has This Been Tested?

• Manually tested using the demo/ package
  • Added example usage to the configuration

Screenshots (if appropriate)

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[github-actions]

Visit the preview URL for this PR (updated for commit 4644633):

https://docusaurus-openapi-36b86--pr1244-bu0qur03.web.app

_{(expires Fri, 16 Jan 2026 17:41:47 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

[sserrata]

Thanks @mikemimik!

Questions:

Would it make sense to rename createIntroTemplateMD → createApiTemplateMD? I imagine this is for API endpoint pages, not intro pages and createApiTemplateMD might align better with markdownGenerators.createApiPageMD.

Could you clarify when to use templateGenerators vs markdownGenerators?

• templateGenerators → controls frontmatter/wrapper (mustache template, no args)
• markdownGenerators → controls body content (receives pageData)

Use markdownGenerators to:

• Add/remove/reorder page sections
• Use different React components
• Add custom content based on the OpenAPI spec
• Skip certain details (e.g., hide callbacks)

Use templateGenerators to:

• Add custom frontmatter fields
• Change sidebar labels or positions
• Add MDX wrapper imports
• Modify page-level metadata

Limited flexibility: Template generators take no arguments, so they can only return static templates. Was this intentional? Could passing context be useful for dynamic frontmatter?

[sserrata]

Thanks for the well-structured PR and for raising this — the issue is real (inline template strings are hard to override).

After review, I don't think the API is the right shape for this. The proposed functions are zero-argument: . A zero-arg function that returns a string is equivalent to just passing the string directly — there's no benefit over accepting in the existing /// options. It adds API surface without adding flexibility.

The underlying problem is simpler to fix: today the code always does , which assumes the value is a file path. The fix is to check first:

const content = fs.existsSync(template)
  ? fs.readFileSync(template).toString()
  : template;

That lets users pass either a file path or an inline template string through the existing option — no new API needed.

The one part of this PR worth keeping as a separate refactor: extracting the hardcoded inline template strings out of index.ts into a dedicated src/markdown/templates.ts module. That's a clean improvement regardless of the templating approach.

Closing in favor of the simpler path-or-string fix in the existing options. Happy to review a follow-up PR for the templates.ts extraction.