fix: more finessing

Author: jshackell-sfdc

src/docs.ts

@@ -109,8 +109,9 @@ export class Docs {
     // The topic ditamap with all of the subtopic links.
     events.emit('subtopics', topic, subTopicNames);
 
-    await this.factory.createTopicCommands(topic, topicMeta).write();
-    await this.factory.createTopicIndex(topic, commandIds).write();
+    const topicCommands = this.factory.createTopicCommands(topic, topicMeta);
+    if (topicCommands) await topicCommands.write();
+    await this.factory.createTopicIndex(topic, commandIds, topicMeta).write();
     return subTopicNames;
   }
 
@@ -188,7 +189,7 @@ export class Docs {
       const commandIds = [...subtopics.values()]
         .flat()
         .filter((cmd) => !cmd.hidden || this.hidden)
-        .map((cmd) => ({ id: ensureString(cmd.id), state: cmd.state }));
+        .map((cmd) => ({ id: ensureString(cmd.id), state: cmd.state, deprecated: cmd.deprecated ?? false }));
       tocEntries.push({ topic, commandIds });
     }
 

src/generator-factory.ts

@@ -23,7 +23,6 @@ import { TopicCommands } from './ditamap/topic-commands.js';
 import { TopicDitamap } from './ditamap/topic-ditamap.js';
 import { MarkdownCliReference } from './markdown/cli-reference.js';
 import { MarkdownCommand } from './markdown/command.js';
-import { MarkdownTopicCommands } from './markdown/topic-commands.js';
 import { MarkdownTopicIndex } from './markdown/topic-index.js';
 import { MarkdownToc } from './markdown/toc.js';
 import { CommandClass, SfTopic } from './utils.js';
@@ -35,16 +34,16 @@ type WritableWithFilename = Writable & { getFilename(): string };
 
 export type TocTopicEntry = {
   topic: string;
-  commandIds: Array<{ id: string; state?: string }>;
+  commandIds: Array<{ id: string; state?: string; deprecated?: boolean }>;
 };
 
 export type GeneratorFactory = {
   createCliReference(topics: string[]): Writable;
   createHelpReference(): Writable | null;
   createRootIndex(topics: string[]): Writable | null;
   createToc(topicEntries: TocTopicEntry[]): Writable | null;
-  createTopicCommands(topic: string, topicMeta: SfTopic): Writable;
-  createTopicIndex(topic: string, commandIds: string[]): Writable;
+  createTopicCommands(topic: string, topicMeta: SfTopic): Writable | null;
+  createTopicIndex(topic: string, commandIds: string[], topicMeta: SfTopic): Writable;
   createCommand(
     topic: string,
     subtopic: string | null,
@@ -54,7 +53,6 @@ export type GeneratorFactory = {
 };
 
 export class DitaGeneratorFactory implements GeneratorFactory {
-  // eslint-disable-next-line class-methods-use-this
   // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
   public createCliReference(_topics: string[]): Writable {
     return new CLIReference();
@@ -80,8 +78,8 @@ export class DitaGeneratorFactory implements GeneratorFactory {
     return new TopicCommands(topic, topicMeta);
   }
 
-  // eslint-disable-next-line class-methods-use-this
-  public createTopicIndex(topic: string, commandIds: string[]): Writable {
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  public createTopicIndex(topic: string, commandIds: string[], _topicMeta: SfTopic): Writable {
     return new TopicDitamap(topic, commandIds);
   }
 
@@ -99,8 +97,9 @@ export class DitaGeneratorFactory implements GeneratorFactory {
 export class MarkdownGeneratorFactory implements GeneratorFactory {
   public constructor(private outputDir: string) {}
 
-  public createCliReference(topics: string[]): Writable {
-    return new MarkdownCliReference(Ditamap.cliVersion, Ditamap.pluginVersions, topics, this.outputDir);
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  public createCliReference(_topics: string[]): Writable {
+    return new MarkdownCliReference(Ditamap.cliVersion, Ditamap.pluginVersions, this.outputDir);
   }
 
   // eslint-disable-next-line class-methods-use-this
@@ -117,12 +116,13 @@ export class MarkdownGeneratorFactory implements GeneratorFactory {
     return new MarkdownToc(topicEntries, this.outputDir);
   }
 
-  public createTopicCommands(topic: string, topicMeta: SfTopic): Writable {
-    return new MarkdownTopicCommands(topic, topicMeta, this.outputDir);
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
+  public createTopicCommands(_topic: string, _topicMeta: SfTopic): null {
+    return null;
   }
 
-  public createTopicIndex(topic: string, commandIds: string[]): Writable {
-    return new MarkdownTopicIndex(topic, commandIds, this.outputDir);
+  public createTopicIndex(topic: string, commandIds: string[], topicMeta: SfTopic): Writable {
+    return new MarkdownTopicIndex(topic, commandIds, topicMeta, this.outputDir);
   }
 
   public createCommand(

src/markdown/cli-reference.ts

@@ -20,7 +20,6 @@ export class MarkdownCliReference extends MarkdownBase {
   public constructor(
     private cliVersion: string,
     private pluginVersions: Array<{ name: string; version: string }>,
-    private topics: string[],
     outputDir: string
   ) {
     super(MarkdownBase.file('cli_reference'), outputDir);
@@ -36,7 +35,7 @@ export class MarkdownCliReference extends MarkdownBase {
         ' scratch orgs and sandboxes, synchronize source to and from orgs, create and install packages, and more.'
     );
     lines.push('');
-    lines.push(`Salesforce CLI version: \`${this.cliVersion}\`.`);
+    lines.push(`Salesforce CLI version: \`${this.cliVersion}\``);
     lines.push('');
     if (this.pluginVersions.length > 0) {
       lines.push('## Plugin Versions');
@@ -48,14 +47,6 @@ export class MarkdownCliReference extends MarkdownBase {
       }
       lines.push('');
     }
-    if (this.topics.length > 0) {
-      lines.push('## Command Topic Index');
-      lines.push('');
-      for (const topic of this.topics.sort()) {
-        lines.push(`- [${topic}](./${topic}/cli_reference_${topic}.md)`);
-      }
-      lines.push('');
-    }
     return Promise.resolve(lines.join('\n'));
   }
 }

src/markdown/command.ts

@@ -34,6 +34,7 @@ export class MarkdownCommand extends MarkdownBase {
   private examples: ParsedExample[];
   private state: unknown;
   private deprecated: boolean;
+  private deprecationDetails: { version?: string; to?: string } | null;
 
   public constructor(
     topic: string,
@@ -81,6 +82,8 @@ export class MarkdownCommand extends MarkdownBase {
 
     this.state = command.state ?? this.commandMeta.state;
     this.deprecated = (command.deprecated as boolean) ?? this.state === 'deprecated' ?? false;
+    const dep = command.deprecated;
+    this.deprecationDetails = dep && typeof dep === 'object' ? (dep as { version?: string; to?: string }) : null;
   }
 
   protected async generate(): Promise<string> {
@@ -89,36 +92,28 @@ export class MarkdownCommand extends MarkdownBase {
 
     const lines: string[] = [];
 
-    lines.push(`# ${this.commandName}`);
+    const stateLabel = resolveStateLabel(this.state, this.deprecated);
+    lines.push(`# ${this.commandName}${stateLabel ? ` (${stateLabel})` : ''}`);
     lines.push('');
 
     if (this.summary) {
       lines.push(this.summary);
       lines.push('');
     }
 
-    if (this.deprecated) {
-      lines.push('> **Deprecated**');
-      lines.push('');
-    } else if (this.state === 'beta') {
-      lines.push('> **Beta**');
-      lines.push('');
-    } else if (this.state === 'preview') {
-      lines.push('> **Preview**');
-      lines.push('');
-    } else if (this.state === 'closedPilot') {
-      lines.push('> **Closed Pilot**');
-      lines.push('');
-    } else if (this.state === 'openPilot') {
-      lines.push('> **Open Pilot**');
+    const disclaimer = resolveDisclaimer(this.commandName, this.state, this.deprecated, this.deprecationDetails);
+    if (disclaimer) {
+      lines.push(':::note');
+      lines.push(disclaimer);
+      lines.push(':::');
       lines.push('');
     }
 
     if (this.help.length > 0) {
       lines.push(`## Description for ${this.commandName}`);
       lines.push('');
       for (const paragraph of this.help) {
-        lines.push(paragraph);
+        lines.push(applyCodeFormatting(escapeAngleBrackets(paragraph)));
         lines.push('');
       }
     }
@@ -144,7 +139,7 @@ export class MarkdownCommand extends MarkdownBase {
       lines.push('## Flags');
       lines.push('');
       lines.push('| Flag | Description |');
-      lines.push('|------|-------------|');
+      lines.push('|----------------------------------------|-------------|');
       for (const param of parameters) {
         lines.push(renderFlagRow(param));
       }
@@ -155,6 +150,58 @@ export class MarkdownCommand extends MarkdownBase {
   }
 }
 
+function escapeAngleBrackets(text: string): string {
+  return text.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function applyCodeFormatting(text: string): string {
+  // Wrap --flag-name tokens (not already in backticks)
+  let result = text.replace(/(?<!`)--([\w-]+)(?!`)/g, '`--$1`');
+  // Wrap file/directory paths: must be preceded by whitespace or opening punctuation (not part of a URL)
+  // Matches: ./foo/bar, ../foo, foo/bar/baz — but not https://foo/bar
+  result = result.replace(/(^|(?<=[\s(["]))(?!https?:\/\/)((?:\.{1,2}\/|[\w][\w-]*\/)[\w./-]+)/g, '$1`$2`');
+  return result;
+}
+
+function resolveStateLabel(state: unknown, deprecated: boolean): string | null {
+  if (deprecated) return 'Deprecated';
+  if (state === 'beta') return 'Beta';
+  if (state === 'preview') return 'Developer Preview';
+  if (state === 'closedPilot' || state === 'openPilot') return 'Pilot';
+  return null;
+}
+
+function resolveDisclaimer(
+  commandName: string,
+  state: unknown,
+  deprecated: boolean,
+  deprecationDetails: { version?: string; to?: string } | null
+): string | null {
+  if (deprecated) {
+    const versionNote = deprecationDetails?.version
+      ? ` and will be removed in v${deprecationDetails.version} or later`
+      : '';
+    const toNote = deprecationDetails?.to ? ` Use \`${deprecationDetails.to}\` instead.` : '';
+    return `The command \`${commandName}\` has been deprecated${versionNote}.${toNote}`;
+  }
+  if (state === 'closedPilot') {
+    // prettier-ignore
+    return `We provide the \`${commandName}\` command to selected customers through an invitation-only pilot program that requires agreement to specific terms and conditions. Pilot programs are subject to change, and we can\x27t guarantee acceptance. The \`${commandName}\` command isn\x27t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can\x27t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.`;
+  }
+  if (state === 'openPilot') {
+    // prettier-ignore
+    return `We provide the \`${commandName}\` command to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Pilot programs are subject to change, and we can\x27t guarantee acceptance. The \`${commandName}\` command isn\x27t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can\x27t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.`;
+  }
+  if (state === 'beta') {
+    return 'This feature is a Beta Service. Customers may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at [Agreements and Terms](https://www.salesforce.com/company/legal/agreements/).';
+  }
+  if (state === 'preview') {
+    // prettier-ignore
+    return 'This command is available as a developer preview. The command isn\'t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don\'t implement functionality developed with these commands or tools.';
+  }
+  return null;
+}
+
 function renderFlagRow(param: CommandParameterData): string {
   const flagLabel = renderFlagLabel(param);
   const desc = renderFlagDescription(param);
@@ -171,13 +218,18 @@ function renderFlagLabel(param: CommandParameterData): string {
 
 function renderFlagDescription(param: CommandParameterData): string {
   const parts: string[] = [];
-  if (!param.optional) parts.push('**Required.**');
-  const desc = param.description.join(' ').replace(/\|/g, '&#124;');
-  if (desc) parts.push(desc);
-  if (param.defaultFlagValue) parts.push(`Default: \`${param.defaultFlagValue}\`.`);
-  if (param.options?.length) parts.push(`Options: ${param.options.map((o) => `\`${o}\``).join(', ')}.`);
   if (param.deprecated) {
-    parts.push(`Deprecated${param.deprecated.to ? `, use \`--${param.deprecated.to}\`` : ''}.`);
+    const toNote = param.deprecated.to ? ` Use \`--${param.deprecated.to}\` instead.` : '';
+    parts.push(`**This flag is deprecated.${toNote}**`);
   }
-  return parts.join(' ').replace(/\n/g, ' ');
+  if (!param.optional) parts.push('**Required**');
+  if (param.options?.length) {
+    parts.push(`**Valid Values:** ${param.options.map((o) => `\`${o}\``).join(', ')}`);
+  }
+  if (param.defaultFlagValue) parts.push(`**Default value:** \`${param.defaultFlagValue}\``);
+  const desc = param.description
+    .map((p) => applyCodeFormatting(escapeAngleBrackets(p.replace(/\|/g, '&#124;'))))
+    .join('<br><br>');
+  if (desc) parts.push(desc);
+  return parts.join('<br>').replace(/\n/g, ' ');
 }

src/markdown/toc.ts

@@ -19,9 +19,10 @@ import { MarkdownBase } from './markdown-base.js';
 
 const STATE_LABELS: Record<string, string> = {
   beta: 'Beta',
-  preview: 'Preview',
+  preview: 'Developer Preview',
   closedPilot: 'Closed Pilot',
   openPilot: 'Open Pilot',
+  deprecated: 'Deprecated',
 };
 
 export class MarkdownToc extends MarkdownBase {
@@ -50,10 +51,14 @@ export class MarkdownToc extends MarkdownBase {
       lines.push(`- title: ${topic} Commands`);
       lines.push(`  link: ${topic}/cli_reference_${topic}.md`);
       lines.push('  topics:');
-      for (const { id, state } of [...commandIds].sort((a, b) => a.id.localeCompare(b.id))) {
+      for (const { id, state, deprecated } of [...commandIds].sort((a, b) => a.id.localeCompare(b.id))) {
         const commandWithUnderscores = id.replace(/:/g, '_');
         const commandWithSpaces = id.replace(/:/g, ' ');
-        const stateLabel = state && STATE_LABELS[state] ? ` (${STATE_LABELS[state]})` : '';
+        const stateLabel = deprecated
+          ? ' (Deprecated)'
+          : state && STATE_LABELS[state]
+          ? ` (${STATE_LABELS[state]})`
+          : '';
         lines.push(`    - title: ${commandWithSpaces}${stateLabel}`);
         lines.push(`      link: ${topic}/cli_reference_${commandWithUnderscores}.md`);
       }

src/markdown/topic-index.ts

@@ -15,20 +15,29 @@
  */
 
 import { join } from 'node:path';
+import { SfTopic } from '../utils.js';
 import { MarkdownBase } from './markdown-base.js';
 
 export class MarkdownTopicIndex extends MarkdownBase {
-  public constructor(private topic: string, private commandIds: string[], outputDir: string) {
+  public constructor(
+    private topic: string,
+    private commandIds: string[],
+    private topicMeta: SfTopic,
+    outputDir: string
+  ) {
     const filename = MarkdownBase.file(`cli_reference_${topic}`);
     super(filename, outputDir);
     this.destination = join(outputDir, topic, filename);
   }
 
   protected generate(): Promise<string> {
     const lines: string[] = [];
-    lines.push('');
     lines.push(`# ${this.topic} Commands`);
     lines.push('');
+    if (this.topicMeta.description) {
+      lines.push(this.topicMeta.description);
+      lines.push('');
+    }
     for (const id of [...this.commandIds].sort()) {
       const commandWithUnderscores = id.replace(/:/g, '_');
       const commandWithSpaces = id.replace(/:/g, ' ');

test/unit/markdown.test.ts

@@ -75,17 +75,12 @@ describe('markdown output: plugin-auth and user', () => {
     expect(md.includes('<codeph')).to.be.false;
   });
 
-  it('creates a topic index file', () => {
+  it('creates a topic index file with description and command links', () => {
     const md = loadMdFile(join('org', 'cli_reference_org.md'));
     expect(md.includes('# org Commands')).to.be.true;
     expect(md.includes('cli_reference_org_login_jwt.md')).to.be.true;
   });
 
-  it('creates a topic commands overview file', () => {
-    const md = loadMdFile(join('org', 'cli_reference_org_commands.md'));
-    expect(md.includes('# org Commands')).to.be.true;
-  });
-
   it('creates a toc file', () => {
     const toc = loadMdFile('sfclireference-toc.yml');
     expect(toc.includes('- title: Salesforce CLI Command Reference')).to.be.true;