implement configurable markdown templates

Author: Russman12

src/application/Apexdocs.ts

@@ -19,6 +19,7 @@ import {
 import { resolveAndValidateSourceDirectories } from '#utils/source-directory-resolver';
 import { ReflectionError, ReflectionErrors, HookError } from '../core/errors/errors';
 import { FileReadingError, FileWritingError } from './errors';
+import * as path from 'path';
 
 /**
  * Application entry-point to generate documentation out of Apex source files.
@@ -29,6 +30,18 @@ export class Apexdocs {
    */
   static async generate(config: UserDefinedConfig, logger: Logger): Promise<E.Either<unknown[], string>> {
     logger.logSingle(`Generating ${config.targetGenerator} documentation...`);
+    
+    // Set custom template directory if provided (only for configs that support it)
+    if (
+      (config.targetGenerator === 'markdown' || config.targetGenerator === 'changelog') &&
+      typeof (config as UserDefinedMarkdownConfig).customTemplateDir === 'string' &&
+      (config as UserDefinedMarkdownConfig).customTemplateDir
+    ) {
+      const { Template } = await import('../core/template');
+      const dir = (config as UserDefinedMarkdownConfig).customTemplateDir!;
+      const absDir = path.isAbsolute(dir) ? dir : path.resolve(process.cwd(), dir);
+      Template.setCustomTemplateDir(absDir);
+    }
 
     try {
       switch (config.targetGenerator) {

src/cli/commands/markdown.ts

@@ -119,4 +119,8 @@ export const markdownOptions: Record<keyof CliConfigurableMarkdownConfig, Option
     type: 'boolean',
     describe: 'Whether to include the inline help text for fields in the generated files.',
   },
+  customTemplateDir: {
+    type: 'string',
+    describe: 'Directory where custom template overrides are stored.',
+  },
 };

src/core/shared/types.d.ts

@@ -45,6 +45,7 @@ export type CliConfigurableMarkdownConfig = {
   referenceGuideTitle: string;
   includeFieldSecurityMetadata: boolean;
   includeInlineHelpTextMetadata: boolean;
+  customTemplateDir?: string; // Optional directory for custom templates
 };
 
 export type UserDefinedMarkdownConfig = {

src/core/template.ts

@@ -10,6 +10,8 @@ import { fieldsPartialTemplate } from './markdown/templates/fieldsPartialTemplat
 import { classMarkdownTemplate } from './markdown/templates/class-template';
 import { enumMarkdownTemplate } from './markdown/templates/enum-template';
 import { interfaceMarkdownTemplate } from './markdown/templates/interface-template';
+import * as fs from 'fs';
+import * as path from 'path';
 
 export type CompilationRequest = {
   template: string;
@@ -18,17 +20,43 @@ export type CompilationRequest = {
 
 export class Template {
   private static instance: Template;
+  private static customTemplateDir: string | undefined;
+
+  /**
+   * Set the custom template directory to use for overrides.
+   * Should be called before getInstance().
+   */
+  public static setCustomTemplateDir(dir: string) {
+    Template.customTemplateDir = dir;
+  }
 
   private constructor() {
-    Handlebars.registerPartial('typeDocumentation', typeDocPartial);
-    Handlebars.registerPartial('documentablePartialTemplate', documentablePartialTemplate);
-    Handlebars.registerPartial('methodsPartialTemplate', methodsPartialTemplate);
-    Handlebars.registerPartial('constructorsPartialTemplate', constructorsPartialTemplate);
-    Handlebars.registerPartial('groupedMembersPartialTemplate', groupedMembersPartialTemplate);
-    Handlebars.registerPartial('fieldsPartialTemplate', fieldsPartialTemplate);
-    Handlebars.registerPartial('classTemplate', classMarkdownTemplate);
-    Handlebars.registerPartial('enumTemplate', enumMarkdownTemplate);
-    Handlebars.registerPartial('interfaceTemplate', interfaceMarkdownTemplate);
+    // Template name to default value mapping
+    const templates: Record<string, string> = {
+      typeDocumentation: typeDocPartial,
+      documentablePartialTemplate: documentablePartialTemplate,
+      methodsPartialTemplate: methodsPartialTemplate,
+      constructorsPartialTemplate: constructorsPartialTemplate,
+      groupedMembersPartialTemplate: groupedMembersPartialTemplate,
+      fieldsPartialTemplate: fieldsPartialTemplate,
+      classTemplate: classMarkdownTemplate,
+      enumTemplate: enumMarkdownTemplate,
+      interfaceTemplate: interfaceMarkdownTemplate,
+    };
+
+    // If customTemplateDir is set, try to load each template from it
+    for (const [name, defaultValue] of Object.entries(templates)) {
+      let value = defaultValue;
+      if (Template.customTemplateDir) {
+        const customPath = path.join(Template.customTemplateDir, `${name}.hbs`);
+
+        if (fs.existsSync(customPath)) {
+          value = fs.readFileSync(customPath, 'utf8');
+        }
+      }
+
+      Handlebars.registerPartial(name, value);
+    }
 
     Handlebars.registerHelper('link', link);
     Handlebars.registerHelper('code', convertCodeBlock);