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 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 Parser Configures 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 Base Provides 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 Implementation Implements the markdown command with Mintlify-specific parameters. CLI Parameters Defined: Folder containing *.api.json files (default: ./input)
Output folder for MDX files - contents will be deleted! (default: ./markdown)
Path to Mintlify docs.json file to update with navigation
Tab name in Mintlify navigation (default: “Code Reference”)
Group name within the tab for organizing pages
Enable menu for the group in navigation
Convert project README.md to index.mdx
Custom title for the README page (only with --readme)
Execution Flow Detailed Flow Breakdown
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
DocumenterCli.executeAsync() processes the command:
Identifies action: markdown
Validates required parameters
Parses all flags and values
Routes to MarkdownAction.onExecuteAsync()
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' });
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:
Input Folder Validation
Output Folder Preparation
API File Detection
const inputFolder = this . _inputFolderParameter . value || './input' ; if ( ! FileSystem . exists ( inputFolder )) { throw new Error ( 'The input folder does not exist: ' + inputFolder ); }
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 }
