Skip to main content

​
Introduction

mint-tsdocs transforms structured API data into beautiful Mintlify documentation through a multi-stage pipeline.

​
Core Libraries

The tool is built on three foundational libraries from Microsoft’s Rush Stack:

ts-command-line

Command-line interface framework with typed parameters and actions

api-extractor-model

Loads .api.json files into a traversable object model (ApiModel)

tsdoc

Creates an Abstract Syntax Tree (AST) of documentation content

​
Component Layers

The codebase is organized into distinct layers, each with a specific responsibility:

CLI Layer

Location: src/cli/Parses user commands and initializes the documentation generation process.
  • start.ts - Executable entry point
  • ApiDocumenterCommandLine.ts - Main CLI parser
  • BaseAction.ts - Common action functionality
  • MarkdownAction.ts - Mintlify-specific command implementation

Generation Layer

Location: src/documenters/Orchestrates the conversion from API model to documentation pages.
  • MarkdownDocumenter.ts - Core orchestrator (now modular)
  • Builds TSDoc AST for each page
  • Delegates navigation to NavigationManager
  • Integrates caching for performance optimization

Emission Layer

Location: src/markdown/Serializes the TSDoc AST into Mintlify-compatible MDX.
  • CustomMarkdownEmitter.ts - Mintlify-specific rendering with API resolution caching
  • MarkdownEmitter.ts - Base markdown functionality
  • Generates <ParamField> and <ResponseField> components

Navigation Layer

Location: src/navigation/Dedicated navigation management for Mintlify documentation.
  • NavigationManager.ts - Hierarchical navigation generation
  • docs.json structure management
  • Mintlify v4 compatibility
  • API item categorization

Caching Layer

Location: src/cache/Performance optimization through intelligent caching.
  • CacheManager.ts - Centralized cache coordination
  • TypeAnalysisCache.ts - Caches expensive type parsing operations
  • ApiResolutionCache.ts - Caches API model cross-reference resolution
  • LRU eviction with configurable sizes

Utilities & Nodes

Location: src/utils/, src/nodes/Supporting components for type analysis and AST nodes.
  • Custom TSDoc nodes (DocTable, DocHeading, etc.)
  • Type analysis utilities (ObjectTypeAnalyzer with caching)
  • Documentation helpers (DocumentationHelper)
  • Security utilities and error handling

​
Data Flow

​
1. CLI Parsing

User runs mint-tsdocs markdown ...
  • start.ts creates DocumenterCli instance
  • CLI parser invokes MarkdownAction.onExecuteAsync()
  • Parameters are validated and processed

​
2. API Model Building

BaseAction.buildApiModel() loads the API data:
  • Reads all *.api.json files from input folder
  • Creates ApiModel instance
  • Loads each package into the model
  • Applies @inheritDoc workarounds

​
3. Document Generation

MarkdownDocumenter.generateFiles() orchestrates:
  • Deletes old output files
  • Traverses API model recursively
  • Calls _writeApiItemPage() for each item
  • Builds TSDoc AST (not markdown strings!)

​
4. AST Construction

For each page, MarkdownDocumenter:
  • Creates DocSection root node
  • Adds DocHeading for titles
  • Creates DocTable nodes for member lists
  • Builds DocTableRow and DocTableCell for each member
  • This AST represents semantic structure

​
5. MDX Emission

CustomMarkdownEmitter.emit() serializes the AST:
  • Traverses TSDoc AST recursively
  • Identifies DocTable nodes with properties/methods
  • Calls DocumentationHelper for type analysis
  • Generates Mintlify components
  • Writes formatted MDX string

​
6. Navigation Update

NavigationManager.generateNavigation():
  • Reads existing docs.json
  • Merges new page paths hierarchically
  • Organizes by API item categories
  • Supports Mintlify v4 tab structure
  • Writes updated docs.json

​
7. Cache Statistics

CacheManager.printStats() reports:
  • Type analysis cache performance
  • API resolution cache performance
  • Overall hit rates and usage

​
Key Components Deep Dive

The Central OrchestratorResponsibilities:
  • File management (delete old, write new)
  • API traversal (recursive iteration)
  • AST construction (build document structure)
  • Frontmatter generation (YAML blocks)
  • Navigation management (docs.json updates)
Key Method: _writeApiItemPage() - Generates a single documentation page
The Mintlify RendererResponsibilities:
  • TSDoc AST → MDX conversion
  • Custom node rendering
  • Mintlify component generation
  • Link resolution
  • Type analysis integration
Key Feature: Intelligent DocTable conversion to <ParamField>/<ResponseField> components
The Type AnalyzerResponsibilities:
  • Parse TypeScript type strings
  • Extract nested object properties
  • Enrich with JSDoc descriptions
  • Generate property metadata
Key Method: analyzeTypeProperties() - Recursively analyzes complex types
The Performance OptimizerResponsibilities:
  • Centralized cache coordination
  • Type analysis caching (30-50% performance improvement)
  • API resolution caching (20-40% performance improvement)
  • LRU eviction with configurable sizes
  • Hit rate monitoring and statistics
Key Feature: Intelligent caching with environment-specific configurations
The Type Parser (now with caching)Handles all TypeScript type patterns:
  • Primitives (string, number)
  • Arrays (string[])
  • Unions (A | B)
  • Intersections (A & B)
  • Generics (Promise<T>)
  • Object literals ({ a: string; b: number })
New: Integrated with TypeAnalysisCache for 30-50% performance improvement Returns structured TypeAnalysis objects for processing

​
Custom TSDoc Nodes

We extend the standard TSDoc nodes with custom types:
Represents section headings with levels (h1-h4)
interface DocHeading {
  title: string;
  level: number; // 1-4
}

​
How to Contribute

Understanding the pipeline helps you contribute effectively:

Change MDX Output

Modify CustomMarkdownEmitter or DocumentationHelper

Change Page Structure

Modify MarkdownDocumenter and AST construction

Add CLI Options

Start in MarkdownAction, pass to MarkdownDocumenter

Support New Types

Enhance ObjectTypeAnalyzer type detection

​
Architecture Diagrams

​
Next Steps

CLI Layer

Understand command-line parsing

Generation Layer

Learn about document generation

Emission Layer

Explore MDX rendering

Navigation Layer

Master navigation management

Caching Layer

Optimize performance with caching

Utilities

Discover helper utilities