fix: claude code's first pass at generating markdown

Author: jshackell-sfdc

messages/main.md

@@ -28,7 +28,11 @@ fail the command if there are any warnings
 
 # flags.ditamap-suffix.summary
 
-unique suffix to append to generated ditamap
+unique suffix to append to generated DITA files
+
+# flags.output-format.summary
+
+output format for generated documentation; 'dita' (default) generates DITA XML files, 'markdown' generates Markdown files
 
 # flags.config-path.summary
 

package.json

@@ -196,6 +196,17 @@
         "messages/**/*.md"
       ],
       "output": []
+    },
+    "test:command-reference-markdown": {
+      "command": "node --loader ts-node/esm --no-warnings=ExperimentalWarning \"./bin/dev.js\" commandreference generate --plugins auth --plugins user --output-format markdown --outputdir test/tmp-md",
+      "files": [
+        "src/**/*.ts",
+        "messages/**",
+        "package.json"
+      ],
+      "output": [
+        "test/tmp-md"
+      ]
     }
   }
 }

src/commands/commandreference/generate.ts

@@ -73,6 +73,11 @@ export default class CommandReferenceGenerate extends SfCommand<CommandReference
       summary: messages.getMessage('flags.config-path.summary'),
       char: 'c',
     }),
+    'output-format': Flags.string({
+      summary: messages.getMessage('flags.output-format.summary'),
+      options: ['dita', 'markdown'],
+      default: 'dita',
+    }),
   };
 
   private loadedConfig!: Interfaces.Config;
@@ -146,9 +151,13 @@ export default class CommandReferenceGenerate extends SfCommand<CommandReference
     const commands = await this.loadCommands(plugins);
     const topicMetadata = this.loadTopicMetadata(commands);
     const cliMeta = this.loadCliMeta();
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore
-    const docs = new Docs(Ditamap.outputDir, flags.hidden, topicMetadata, cliMeta);
+    const docs = new Docs(
+      Ditamap.outputDir,
+      flags['output-format'] as 'dita' | 'markdown',
+      flags.hidden,
+      topicMetadata ?? new Map<string, never>(),
+      cliMeta
+    );
 
     events.on('topic', ({ topic }: { topic: string }) => {
       this.log(chalk.green(`Generating topic '${topic}'`));

src/ditamap/command-helpers.ts

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Dictionary, Optional } from '@salesforce/ts-types';
+import { CommandParameterData, replaceConfigVariables } from '../utils.js';
+
+export type FlagInfo = {
+  hidden: boolean;
+  description: string;
+  summary: string;
+  required: boolean;
+  kind: string;
+  type: string;
+  defaultHelpValue?: string;
+  default: string | (() => Promise<string>);
+  aliases?: string[];
+  options?: string[];
+  char?: string;
+  deprecated?: { version: string; to: string };
+};
+
+export const getDefault = async (flag: FlagInfo, flagName: string): Promise<string> => {
+  if (!flag) {
+    return '';
+  }
+  if (flagName === 'target-org' || flagName === 'target-dev-hub') {
+    return '';
+  }
+  if (typeof flag.default === 'function') {
+    try {
+      const help = await flag.default();
+      return help.includes('[object Object]') ? '' : help ?? '';
+    } catch {
+      return '';
+    }
+  } else {
+    return flag.default;
+  }
+};
+
+export const flagIsDefined = (input: [string, Optional<FlagInfo>]): input is [string, FlagInfo] =>
+  input[1] !== undefined;
+
+export const buildDescription =
+  (commandName: string) =>
+  (binary: string) =>
+  (flag: FlagInfo): string[] => {
+    const description = replaceConfigVariables(
+      Array.isArray(flag?.description) ? flag?.description.join('\n') : flag?.description ?? '',
+      binary,
+      commandName
+    );
+    return formatParagraphs(
+      flag.summary ? `${replaceConfigVariables(flag.summary, binary, commandName)}\n${description}` : description
+    );
+  };
+
+export const formatParagraphs = (textToFormat?: string): string[] =>
+  textToFormat ? textToFormat.split('\n').filter((n) => n !== '') : [];
+
+export const readBinary = (commandMeta: Record<string, unknown>): string =>
+  'binary' in commandMeta && typeof commandMeta.binary === 'string' ? commandMeta.binary : 'unknown';
+
+export const buildCommandParameters = async (
+  commandName: string,
+  binary: string,
+  flags: Dictionary<FlagInfo>
+): Promise<CommandParameterData[]> => {
+  const descriptionBuilder = buildDescription(commandName)(binary);
+  return Promise.all(
+    [...Object.entries(flags)]
+      .filter(flagIsDefined)
+      .filter(([, flag]) => !flag.hidden)
+      .map(
+        async ([flagName, flag]) =>
+          ({
+            ...flag,
+            name: flagName,
+            description: descriptionBuilder(flag),
+            optional: !flag.required,
+            kind: flag.kind ?? flag.type,
+            hasValue: flag.type !== 'boolean',
+            defaultFlagValue: await getDefault(flag, flagName),
+          } satisfies CommandParameterData)
+      )
+  );
+};

src/ditamap/command.ts

@@ -15,40 +15,10 @@
  */
 
 import { join } from 'node:path';
-import { asString, Dictionary, ensureObject, ensureString, Optional } from '@salesforce/ts-types';
-import { CommandClass, CommandData, CommandParameterData, punctuate, replaceConfigVariables } from '../utils.js';
+import { asString, Dictionary, ensureObject, ensureString } from '@salesforce/ts-types';
+import { CommandClass, CommandData, punctuate, replaceConfigVariables } from '../utils.js';
 import { Ditamap } from './ditamap.js';
-
-type FlagInfo = {
-  hidden: boolean;
-  description: string;
-  summary: string;
-  required: boolean;
-  kind: string;
-  type: string;
-  defaultHelpValue?: string;
-  default: string | (() => Promise<string>);
-};
-
-const getDefault = async (flag: FlagInfo, flagName: string): Promise<string> => {
-  if (!flag) {
-    return '';
-  }
-  if (flagName === 'target-org' || flagName === 'target-dev-hub') {
-    // special handling to prevent global/local default usernames from appearing in the docs, but they do appear in user's help
-    return '';
-  }
-  if (typeof flag.default === 'function') {
-    try {
-      const help = await flag.default();
-      return help.includes('[object Object]') ? '' : help ?? '';
-    } catch {
-      return '';
-    }
-  } else {
-    return flag.default;
-  }
-};
+import { buildCommandParameters, FlagInfo, readBinary, formatParagraphs } from './command-helpers.js';
 
 export class Command extends Ditamap {
   private flags: Dictionary<FlagInfo>;
@@ -131,57 +101,14 @@ export class Command extends Ditamap {
     this.destination = join(Ditamap.outputDir, topic, filename);
   }
 
-  public async getParametersForTemplate(flags: Dictionary<FlagInfo>): Promise<CommandParameterData[]> {
-    const descriptionBuilder = buildDescription(this.commandName)(readBinary(this.commandMeta));
-    return Promise.all(
-      [...Object.entries(flags)]
-        .filter(flagIsDefined)
-        .filter(([, flag]) => !flag.hidden)
-        .map(
-          async ([flagName, flag]) =>
-            ({
-              ...flag,
-              name: flagName,
-              description: descriptionBuilder(flag),
-              optional: !flag.required,
-              kind: flag.kind ?? flag.type,
-              hasValue: flag.type !== 'boolean',
-              defaultFlagValue: await getDefault(flag, flagName),
-            } satisfies CommandParameterData)
-        )
-    );
-  }
-
   // eslint-disable-next-line class-methods-use-this
   public getTemplateFileName(): string {
     return 'command.hbs';
   }
 
   protected async transformToDitamap(): Promise<string> {
-    const parameters = await this.getParametersForTemplate(this.flags);
+    const parameters = await buildCommandParameters(this.commandName, readBinary(this.commandMeta), this.flags);
     this.data = Object.assign({}, this.data, { parameters });
     return super.transformToDitamap();
   }
 }
-
-const flagIsDefined = (input: [string, Optional<FlagInfo>]): input is [string, FlagInfo] => input[1] !== undefined;
-
-const buildDescription =
-  (commandName: string) =>
-  (binary: string) =>
-  (flag: FlagInfo): string[] => {
-    const description = replaceConfigVariables(
-      Array.isArray(flag?.description) ? flag?.description.join('\n') : flag?.description ?? '',
-      binary,
-      commandName
-    );
-    return formatParagraphs(
-      flag.summary ? `${replaceConfigVariables(flag.summary, binary, commandName)}\n${description}` : description
-    );
-  };
-
-const formatParagraphs = (textToFormat?: string): string[] =>
-  textToFormat ? textToFormat.split('\n').filter((n) => n !== '') : [];
-
-const readBinary = (commandMeta: Record<string, unknown>): string =>
-  'binary' in commandMeta && typeof commandMeta.binary === 'string' ? commandMeta.binary : 'unknown';

src/docs.ts

@@ -17,13 +17,8 @@
 import fs from 'node:fs/promises';
 import { AnyJson, ensureString } from '@salesforce/ts-types';
 import chalk from 'chalk';
-import { BaseDitamap } from './ditamap/base-ditamap.js';
-import { CLIReference } from './ditamap/cli-reference.js';
-import { Command } from './ditamap/command.js';
-import { TopicCommands } from './ditamap/topic-commands.js';
-import { TopicDitamap } from './ditamap/topic-ditamap.js';
 import { CliMeta, events, punctuate, SfTopic, SfTopics, CommandClass } from './utils.js';
-import { HelpReference } from './ditamap/help-reference.js';
+import { DitaGeneratorFactory, GeneratorFactory, MarkdownGeneratorFactory, OutputFormat } from './generator-factory.js';
 
 type TopicsByTopicsByTopLevel = Map<string, Map<string, CommandClass[]>>;
 
@@ -37,12 +32,17 @@ function emitNoTopicMetadataWarning(topic: string): void {
 }
 
 export class Docs {
+  private factory: GeneratorFactory;
+
   public constructor(
     private outputDir: string,
+    outputFormat: OutputFormat,
     private hidden: boolean,
     private topicMeta: SfTopics,
     private cliMeta: CliMeta
-  ) {}
+  ) {
+    this.factory = outputFormat === 'markdown' ? new MarkdownGeneratorFactory(outputDir) : new DitaGeneratorFactory();
+  }
 
   public async build(commands: CommandClass[]): Promise<void> {
     // Create if doesn't exist
@@ -77,13 +77,6 @@ export class Docs {
 
     for (const [subtopic, classes] of subtopics.entries()) {
       try {
-        // const subTopicsMeta = topicMeta.subtopics;
-
-        // if (!subTopicsMeta?.get(subtopic)) {
-        //   emitNoTopicMetadataWarning(`${topic}:${subtopic}`);
-        //   continue;
-        // }
-
         subTopicNames.push(subtopic);
 
         // Commands within the sub topic
@@ -110,8 +103,8 @@ export class Docs {
     // The topic ditamap with all of the subtopic links.
     events.emit('subtopics', topic, subTopicNames);
 
-    await new TopicCommands(topic, topicMeta).write();
-    await new TopicDitamap(topic, commandIds).write();
+    await this.factory.createTopicCommands(topic, topicMeta).write();
+    await this.factory.createTopicIndex(topic, commandIds).write();
     return subTopicNames;
   }
 
@@ -123,7 +116,6 @@ export class Docs {
    * @returns The commands grouped by topics/subtopic/commands.
    */
   private groupTopicsAndSubtopics(commands: CommandClass[]): TopicsByTopicsByTopLevel {
-    // const topLevelTopics: Dictionary<Dictionary<CommandClass | CommandClass[]>> = {};
     const topLevelTopics = new Map<string, Map<string, CommandClass[]>>();
 
     for (const command of commands) {
@@ -135,17 +127,14 @@ export class Docs {
 
       const plugin = command.plugin;
       if (plugin) {
-        // Also include the namespace on the commands so we don't need to do the split at other times in the code.
         command.topic = topLevelTopic;
 
         const existingTopicsForTopLevel = topLevelTopics.get(topLevelTopic) ?? new Map<string, CommandClass[]>();
 
         if (commandParts.length === 1) {
-          // This is a top-level topic that is also a command
           const existingTarget = existingTopicsForTopLevel.get(commandParts[0]) ?? [];
           existingTopicsForTopLevel.set(commandParts[0], [...existingTarget, command]);
         } else if (commandParts.length === 2) {
-          // This is a command directly under the top-level topic
           const existingTarget = existingTopicsForTopLevel.get(commandParts[1]) ?? [];
           existingTopicsForTopLevel.set(commandParts[1], [...existingTarget, command]);
         } else {
@@ -177,11 +166,12 @@ export class Docs {
   private async populateTemplate(commands: CommandClass[]): Promise<void> {
     const topicsAndSubtopics = this.groupTopicsAndSubtopics(commands);
 
-    await new CLIReference().write();
-    await new HelpReference().write();
+    await this.factory.createCliReference().write();
+
+    const helpReference = this.factory.createHelpReference();
+    if (helpReference) await helpReference.write();
 
-    // Generate one base file with all top-level topics.
-    await new BaseDitamap(Array.from(topicsAndSubtopics.keys())).write();
+    await this.factory.createRootIndex(Array.from(topicsAndSubtopics.keys())).write();
 
     for (const [topic, subtopics] of topicsAndSubtopics.entries()) {
       events.emit('topic', { topic });
@@ -240,8 +230,8 @@ export class Docs {
       return '';
     }
 
-    const commandDitamap = new Command(topic, subtopic, command, commandMeta);
-    await commandDitamap.write();
-    return commandDitamap.getFilename();
+    const commandGenerator = this.factory.createCommand(topic, subtopic, command, commandMeta);
+    await commandGenerator.write();
+    return commandGenerator.getFilename();
   }
 }