mint-tsdocs

Generate beautiful, Mintlify-native API documentation from your TypeScript code.

This tool automatically generates Mintlify-compatible MDX documentation for your TypeScript libraries and CLIs. It uses API Extractor and TSDoc to analyze your code and creates rich, interactive documentation with Mintlify components.

Who Is This For?

mint-tsdocs bridges the gap between TypeScript development and Mintlify's documentation platform:

• Library Authors - Generate comprehensive API reference docs for your npm packages
• CLI Tool Developers - Document command-line interfaces with the same quality as API SDKs
• Open Source Maintainers - Automate documentation updates for TypeScript projects
• Documentation Teams - Maintain up-to-date API references without manual effort

While Mintlify excels at API SDK documentation, mint-tsdocs makes it just as easy to document TypeScript libraries and CLIs.

Features

• Mintlify-Native Components - Uses <ParamField>, <ResponseField>, and <Expandable> for rich, interactive documentation
• Automatic Navigation - Updates your docs.json file automatically with proper tabs and groups
• Complex Type Support - Full support for nested objects, unions, intersections, and generics
• Smart Auto-Detection - Finds your TypeScript entry point, Mintlify config, and output folder automatically
• Zero Configuration - Works out of the box with sensible defaults
• Template Customization - Fully customizable Liquid templates for complete control over output

Quick Start

# Initialize and configure (auto-detects your TypeScript setup)
npx mint-tsdocs

# Build your TypeScript project to generate .d.ts files
bun run build  # or your build command

# Generate documentation
npx mint-tsdocs generate

That's it! Your API documentation is ready in the docs/reference folder.

Installation

You can use mint-tsdocs without installing it:

npx mint-tsdocs

Or install it locally/globally:

# Local (recommended)
bun add -D mint-tsdocs
# or: npm install -D mint-tsdocs

# Global
bun add -g mint-tsdocs
# or: npm install -g mint-tsdocs

The package provides two command aliases:

• mint-tsdocs (short, recommended)
• mintlify-tsdocs (full name)

Configuration

mint-tsdocs uses a single configuration file at the project root: mint-tsdocs.config.json

Auto-Detection

The tool auto-detects:

• TypeScript entry point (from package.json types/typings field or common paths)
• Mintlify docs.json location
• Output folder

Example Configuration

{
  "$schema": "./node_modules/mint-tsdocs/lib/schemas/config.schema.json",
  "entryPoint": "./lib/index.d.ts",
  "outputFolder": "./docs/reference",
  "docsJson": "./docs/docs.json",
  "tabName": "API Reference",
  "groupName": "API"
}

See the JSON Schema for all available options.

CLI Commands

mint-tsdocs or mint-tsdocs init

Initialize a project with mint-tsdocs configuration. Auto-detects your TypeScript entry point, Mintlify docs folder, and creates mint-tsdocs.config.json.

Options:

• --yes, -y - Skip prompts and use auto-detected defaults
• --skip-mintlify - Skip Mintlify initialization (if already set up)
• --project-dir <path> - Project directory (default: current directory)

mint-tsdocs generate

Generate documentation from TypeScript source. Automatically runs API Extractor and creates MDX files with Mintlify components.

Options:

• --skip-extractor - Skip API Extractor step (use cached .api.json files)
• --verbose, -v - Show detailed output
• --debug - Show debug output
• --quiet, -q - Suppress all output except errors

mint-tsdocs customize

Copy default Liquid templates to a directory for customization.

Options:

• -t, --template-dir <path> - Directory where templates should be created
• --force - Overwrite existing templates

mint-tsdocs show

Display current configuration or cache statistics.

Options:

• config - Show current configuration (default)
• stats - Show cache statistics and performance metrics

Documentation

• Full Documentation - Complete guide with examples
• Quick Start - Get started in 2 minutes
• CLI Reference - All commands and options
• Configuration - Configuration options
• API Reference - Generated API docs (dogfooding!)

Requirements

• Node.js 18 or higher
• TypeScript project with declaration: true in tsconfig.json

Current Status

mint-tsdocs is currently optimized for local development workflows. It runs on developer machines to generate documentation from locally-built TypeScript projects.

Coming Soon:

• CI/CD integration for automated documentation on every commit
• Enhanced security features for multi-tenant environments
• Potential SaaS offering for repository-triggered documentation updates

Built On

This project uses Microsoft's excellent API Extractor and TSDoc for TypeScript analysis, enhanced with Mintlify-specific features and components.

Contributing

Contributions are welcome! Please check out the Contributing Guide and Architecture Documentation.

License

MIT - See LICENSE file for details