CLI Layer

Overview

The CLI layer is the entry point for mint-tsdocs, responsible for parsing user commands and initiating the documentation generation process. Built on @rushstack/ts-command-line, it provides a robust, typed command-line interface.

Entry Point: src/start.ts creates the CLI instance and runs the parser

Component Architecture

start.ts
ApiDocumenterCommandLine
BaseAction
MarkdownAction

The Executable Entry Point

src/start.ts

import { DocumenterCli } from './cli/ApiDocumenterCommandLine';

const parser: DocumenterCli = new DocumenterCli();
parser.executeAsync().catch(console.error);

Responsibilities:

Display version banner
Create CLI parser instance
Execute command and handle errors

Main CLI ParserConfigures the tool’s identity and registers available commands.

export class DocumenterCli extends CommandLineParser {
  constructor() {
    super({
      toolFilename: 'mint-tsdocs',
      toolDescription: 'Generates Mintlify-compatible MDX documentation'
    });
    this._populateActions();
  }

  private _populateActions(): void {
    this.addAction(new MarkdownAction(this));
  }
}

Currently registers only the markdown action.

Abstract Action BaseProvides foundational functionality for all actions.Key Method: buildApiModel()

Parse Parameters

Reads --input-folder and --output-folder

Validate Input

Ensures input folder exists

Create ApiModel

Instantiates model from @microsoft/api-extractor-model

Load Packages

Finds all *.api.json files and loads them

Apply Workarounds

Handles @inheritDoc TSDoc tags

Concrete ImplementationImplements the markdown command with Mintlify-specific parameters.CLI Parameters Defined:

input-folder

string

required

Folder containing *.api.json files (default: ./input)

output-folder

string

required

Output folder for MDX files - contents will be deleted! (default: ./markdown)

docs-json

string

Path to Mintlify docs.json file to update with navigation

tab-name

string

Tab name in Mintlify navigation (default: “Code Reference”)

group

string

Group name within the tab for organizing pages

Enable menu for the group in navigation

readme

boolean

Convert project README.md to index.mdx

readme-title

string

Custom title for the README page (only with --readme)

Execution Flow

Detailed Flow Breakdown

1. Command Invocation

User runs the command:

mint-tsdocs markdown -i ./temp -o ./docs/api --docs-json ./docs/docs.json

Binary executes lib/start.js
Version banner is displayed
DocumenterCli instance is created

2. CLI Parsing

DocumenterCli.executeAsync() processes the command:

Identifies action: markdown
Validates required parameters
Parses all flags and values
Routes to MarkdownAction.onExecuteAsync()

3. API Model Building

BaseAction.buildApiModel() loads the API data:

const apiModel: ApiModel = new ApiModel();
const inputFolder = this._inputFolderParameter.value || './input';

// Find and load all *.api.json files
for (const filename of FileSystem.readFolderItemNames(inputFolder)) {
  if (filename.match(/\.api\.json$/i)) {
    apiModel.loadPackage(path.join(inputFolder, filename));
  }
}

// Apply @inheritDoc workarounds
this._applyInheritDoc(apiModel, apiModel);

return { apiModel, inputFolder, outputFolder };

4. Documenter Instantiation

MarkdownAction creates and configures the documenter:

const markdownDocumenter = new MarkdownDocumenter({
  apiModel,
  outputFolder,
  docsJsonPath: this._docsJsonParameter.value,
  tabName: this._tabNameParameter.value,
  groupName: this._groupParameter.value,
  enableMenu: this._menuParameter.value,
  convertReadme: this._readmeParameter.value,
  readmeTitle: this._readmeTitleParameter.value || 'README'
});

5. Generation Handoff

Control passes to the generation layer:

markdownDocumenter.generateFiles();

The CLI layer’s work is complete - the generation layer takes over.

Parameter Validation

The CLI layer ensures all parameters are valid before proceeding:

const inputFolder = this._inputFolderParameter.value || './input';
if (!FileSystem.exists(inputFolder)) {
  throw new Error('The input folder does not exist: ' + inputFolder);
}

const outputFolder = this._outputFolderParameter.value || './markdown';
FileSystem.ensureFolder(outputFolder);

const apiJsonFiles = FileSystem.readFolderItemNames(inputFolder)
  .filter(f => f.match(/\.api\.json$/i));

if (apiJsonFiles.length === 0) {
  throw new Error('No *.api.json files found in input folder');
}

Error Handling

The CLI layer provides early validation to fail fast with clear error messages

Common errors caught at the CLI layer:

Error	Cause	Solution
Input folder not found	Invalid `-i` path	Verify path exists
No .api.json files	Wrong input folder	Run `api-extractor` first
Invalid docs.json	Malformed JSON	Validate JSON syntax
Permission denied	Output folder protected	Check file permissions

Extending the CLI

Adding a New Parameter

Define in Action

this._myParameter = this.defineStringParameter({
  parameterLongName: '--my-option',
  argumentName: 'VALUE',
  description: 'My new option'
});

Pass to Documenter

const markdownDocumenter = new MarkdownDocumenter({
  // ... existing options
  myOption: this._myParameter.value
});

Update Interface

export interface IMarkdownDocumenterOptions {
  // ... existing properties
  myOption?: string;
}

Use in Generation

Use the new option in MarkdownDocumenter logic

Adding a New Command

To add a new command (e.g., yaml):

Create YamlAction.ts extending BaseAction
Implement onExecuteAsync()
Register in ApiDocumenterCommandLine._populateActions()

private _populateActions(): void {
  this.addAction(new MarkdownAction(this));
  this.addAction(new YamlAction(this));  // New command
}

Generation Layer

See how the CLI hands off to the generation layer

Architecture Overview

Understand the full pipeline

Concepts

Guides

OpenDocs Specification

Architecture

Overview

Component Architecture

Execution Flow

Detailed Flow Breakdown

Parameter Validation

Error Handling

Extending the CLI

Adding a New Parameter

Adding a New Command

Generation Layer

Architecture Overview

​Overview

​Component Architecture

​Execution Flow

​Detailed Flow Breakdown

​Parameter Validation

​Error Handling

​Extending the CLI

​Adding a New Parameter

​Adding a New Command

​Related Documentation

Generation Layer

Architecture Overview

Overview

Component Architecture

Execution Flow

Detailed Flow Breakdown

Parameter Validation

Error Handling

Extending the CLI

Adding a New Parameter

Adding a New Command

Related Documentation