Configuration Reference

Configuration File

mint-tsdocs uses cosmiconfig to load configuration. It searches for configuration in the following locations (in order):

mint-tsdocs.config.json (recommended)
.mint-tsdocsrc
.mint-tsdocsrc.json
mintlifyTsdocs field in package.json

JSON Schema

Add the $schema field for IDE autocomplete and validation:

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

Core Options

entryPoint

Type: string (required) Path to the main TypeScript declaration file (.d.ts) that serves as the entry point for your API.

{
  "entryPoint": "./lib/index.d.ts"
}

Auto-detection:

Checks types field in package.json
Checks typings field in package.json
Searches common paths: ./lib/index.d.ts, ./dist/index.d.ts, ./build/index.d.ts

Notes:

Must point to a compiled .d.ts file (not .ts source)
Run TypeScript compiler before generating docs
Path is relative to project root

outputFolder

Type: string Default: ./docs/reference Directory where generated MDX documentation files will be written.

{
  "outputFolder": "./docs/reference"
}

Notes:

Directory will be created if it doesn’t exist
Existing files will be overwritten
Path is relative to project root

docsJson

Type: string Default: Auto-detected or ./docs/docs.json Path to Mintlify’s docs.json navigation file.

{
  "docsJson": "./docs/docs.json"
}

Auto-detection searches:

./docs/docs.json
./docs.json
./documentation/docs.json

Notes:

Navigation entries will be automatically added to this file
File must exist and be valid JSON
Set to false to skip navigation updates

tabName

Type: string Default: "API Reference" Name of the tab in Mintlify navigation where API docs will appear.

{
  "tabName": "API Reference"
}

Example in docs.json:

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",  // ← tabName
        "groups": [...]
      }
    ]
  }
}

groupName

Type: string Default: "API" Name of the group within the tab where API items will be organized.

{
  "groupName": "API"
}

Example in docs.json:

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "API",  // ← groupName
            "pages": [...]
          }
        ]
      }
    ]
  }
}

README Options

convertReadme

Type: boolean Default: false Whether to convert the project’s README.md to MDX and include it in the documentation.

{
  "convertReadme": true,
  "readmeTitle": "Overview"
}

Notes:

Searches for README.md in project root
Converts markdown to Mintlify-compatible MDX
Adds to navigation with specified title

readmeTitle

Type: string Default: "README" Title for the converted README page in navigation (only used if convertReadme: true).

{
  "readmeTitle": "Getting Started"
}

Template Options

templates

Type: object Configuration for Liquid template customization.

{
  "templates": {
    "userTemplateDir": "./templates",
    "cache": true,
    "strict": true
  }
}

templates.userTemplateDir

Type: string Path to directory containing custom Liquid templates.

{
  "templates": {
    "userTemplateDir": "./templates"
  }
}

Template files:

layout.liquid - Base layout wrapper
class.liquid - Class documentation
interface.liquid - Interface documentation
method.liquid - Method documentation
property.liquid - Property documentation
constructor.liquid - Constructor documentation
function.liquid - Function documentation
enum.liquid - Enum documentation
type-alias.liquid - Type alias documentation
namespace.liquid - Namespace documentation

Generate templates:

mint-tsdocs customize -t ./templates

templates.cache

Type: boolean Default: true Whether to cache compiled templates for better performance.

{
  "templates": {
    "cache": true
  }
}

Notes:

Recommended: true for production, false for template development
Clear cache by deleting node_modules/.cache/mint-tsdocs/

templates.strict

Type: boolean Default: true Whether to enable strict mode in Liquid template engine.

{
  "templates": {
    "strict": true
  }
}

Strict mode:

Throws errors on undefined variables
Throws errors on invalid filters
Helps catch template bugs during development

Lenient mode (strict: false):

Silently ignores undefined variables
Silently ignores invalid filters
May hide template errors

Lint Options

lint

Type: object Configuration for the lint command.

{
  "lint": {
    "eslint": {
      "enabled": true,
      "directories": ["src"],
      "configPath": "./eslint.config.js"
    },
    "failOnError": true
  }
}

lint.eslint.enabled

Type: boolean Default: Not set (auto-detect) Controls ESLint integration with eslint-plugin-tsdoc:

true - Force enable. Shows an error with install command if eslint is not installed.
false - Force disable. No ESLint analysis, no hints.
Not set - Auto-detect. Runs ESLint if installed, shows a hint with install instructions if not.

{
  "lint": {
    "eslint": {
      "enabled": true
    }
  }
}

Required packages (when enabled):

bun add -D eslint eslint-plugin-tsdoc @typescript-eslint/parser

lint.eslint.directories

Type: string[] Default: ["src"] Directories to lint. ESLint discovers TypeScript files automatically within these directories.

{
  "lint": {
    "eslint": {
      "directories": ["src", "lib"]
    }
  }
}

lint.eslint.configPath

Type: string Default: Auto-discovered Path to custom ESLint configuration file. If not set, ESLint auto-discovers eslint.config.js and other standard config files.

{
  "lint": {
    "eslint": {
      "configPath": "./config/eslint.config.js"
    }
  }
}

lint.failOnError

Type: boolean Default: true Whether the lint command should exit with code 1 when errors are found. Set to false to treat errors as non-blocking.

{
  "lint": {
    "failOnError": false
  }
}

Message Reporting Options

apiExtractor.messages

Type: object Configuration for controlling how different types of diagnostic messages are reported during API extraction.

{
  "apiExtractor": {
    "messages": {
      "compilerMessageReporting": {
        "TS2551": {
          "logLevel": "warning"
        }
      },
      "extractorMessageReporting": {
        "ae-missing-release-tag": {
          "logLevel": "none"
        }
      },
      "tsdocMessageReporting": {
        "tsdoc-param-tag-missing-hyphen": {
          "logLevel": "warning"
        }
      }
    }
  }
}

messages.compilerMessageReporting

Type: Record<string, MessageReportingItem> Configuration for TypeScript compiler diagnostic messages.

{
  "apiExtractor": {
    "messages": {
      "compilerMessageReporting": {
        "TS2551": {
          "logLevel": "warning",
          "addToApiReportFile": false
        }
      }
    }
  }
}

Message IDs:

TypeScript error codes (e.g., TS2551, TS2322)
Use default to set default behavior for all messages

messages.extractorMessageReporting

Type: Record<string, MessageReportingItem> Configuration for API Extractor diagnostic messages.

{
  "apiExtractor": {
    "messages": {
      "extractorMessageReporting": {
        "ae-missing-release-tag": {
          "logLevel": "none"
        }
      }
    }
  }
}

Common message IDs:

ae-missing-release-tag - Missing @public, @beta, @alpha, or @internal tag
ae-undocumented - Missing documentation comment
ae-forgotten-export - Exported type references unexported declaration

messages.tsdocMessageReporting

Type: Record<string, MessageReportingItem> Configuration for TSDoc parser diagnostic messages.

{
  "apiExtractor": {
    "messages": {
      "tsdocMessageReporting": {
        "tsdoc-param-tag-missing-hyphen": {
          "logLevel": "warning"
        }
      }
    }
  }
}

Common message IDs:

tsdoc-param-tag-missing-hyphen - @param tag missing hyphen
tsdoc-undefined-tag - Unrecognized TSDoc tag
tsdoc-param-tag-with-invalid-name - Invalid parameter name in @param

MessageReportingItem

Configuration for how a specific message should be reported. Properties:

logLevel

Type: 'error' | 'warning' | 'none' How to report this message type:

error - Report as an error (fails the build)
warning - Report as a warning (doesn’t fail the build)
none - Suppress the message entirely

addToApiReportFile

Type: boolean Default: false Whether to include this message in the API report file (.api.md). Example:

{
  "logLevel": "warning",
  "addToApiReportFile": true
}

API Extractor Options

apiExtractor

Type: object Configuration for API Extractor integration.

{
  "apiExtractor": {
    "configPath": "./api-extractor.json",
    "bundledPackages": ["@internal/utils"],
    "compiler": {
      "tsconfigFilePath": "./tsconfig.json",
      "skipLibCheck": true
    },
    "docModel": {
      "enabled": true,
      "projectFolderUrl": "https://github.com/user/repo/tree/main"
    }
  }
}

apiExtractor.configPath

Type: string Default: Auto-generated in .tsdocs/api-extractor.json Path to custom API Extractor configuration file.

{
  "apiExtractor": {
    "configPath": "./api-extractor.json"
  }
}

Notes:

If specified, mint-tsdocs will use your custom config
If not specified, config is auto-generated from other settings
Custom config gives you full control over API Extractor

apiExtractor.bundledPackages

Type: string[] Default: [] List of package names to treat as bundled (include their declarations in the documentation).

{
  "apiExtractor": {
    "bundledPackages": ["@internal/utils", "@internal/types"]
  }
}

Use case:

Document internal packages alongside main package
Include types from dependencies in your documentation

apiExtractor.compiler

Type: object TypeScript compiler configuration for API Extractor.

compiler.tsconfigFilePath

Type: string Default: Auto-detected Path to tsconfig.json file.

{
  "apiExtractor": {
    "compiler": {
      "tsconfigFilePath": "./tsconfig.build.json"
    }
  }
}

Auto-detection searches:

./tsconfig.json
./tsconfig.build.json
./tsconfig.prod.json

compiler.skipLibCheck

Type: boolean Default: true Whether to skip type checking of declaration files.

{
  "apiExtractor": {
    "compiler": {
      "skipLibCheck": true
    }
  }
}

Recommended: true for faster builds

apiExtractor.docModel

Type: object Configuration for API Extractor’s documentation model output.

docModel.enabled

Type: boolean Default: true Whether to generate .api.json files.

{
  "apiExtractor": {
    "docModel": {
      "enabled": true
    }
  }
}

Note: Must be true for mint-tsdocs to work

docModel.projectFolderUrl

Type: string Base URL for source code links in generated documentation.

{
  "apiExtractor": {
    "docModel": {
      "projectFolderUrl": "https://github.com/username/repo/tree/main"
    }
  }
}

Example link:

https://github.com/username/repo/tree/main/src/MyClass.ts#L42

apiExtractor.apiReport

Type: object Configuration for API report file generation (optional). API reports show a text summary of your public API surface and can be committed to track API changes over time.

apiReport.enabled

Type: boolean Default: false Whether to generate API report files (.api.md).

{
  "apiExtractor": {
    "apiReport": {
      "enabled": true
    }
  }
}

apiReport.reportFileName

Type: string Default: "<unscopedPackageName>.api.md" Name pattern for the API report file.

{
  "apiExtractor": {
    "apiReport": {
      "reportFileName": "my-package.api.md"
    }
  }
}

Supported tokens:

<unscopedPackageName> - Package name without @scope/
<packageName> - Full package name

apiReport.reportFolder

Type: string Default: "<projectFolder>/temp/" Folder where the API report file will be written.

{
  "apiExtractor": {
    "apiReport": {
      "reportFolder": "./api-reports"
    }
  }
}

Supported tokens:

<projectFolder> - Project root directory

apiReport.reportTempFolder

Type: string Default: "<projectFolder>/temp/" Temporary folder used during API report generation.

{
  "apiExtractor": {
    "apiReport": {
      "reportTempFolder": "./temp/api-reports"
    }
  }
}

Note: This folder is used for intermediate files during generation.

apiExtractor.dtsRollup

Type: object Configuration for .d.ts rollup generation (optional). Rollups combine multiple .d.ts files into a single file, optionally trimmed by release level.

dtsRollup.enabled

Type: boolean Default: false Whether to generate rolled-up .d.ts declaration files.

{
  "apiExtractor": {
    "dtsRollup": {
      "enabled": true
    }
  }
}

dtsRollup.publicTrimmedFilePath

Type: string Path for the public-trimmed .d.ts rollup file. Includes only declarations marked with @public.

{
  "apiExtractor": {
    "dtsRollup": {
      "publicTrimmedFilePath": "./dist/<unscopedPackageName>.d.ts"
    }
  }
}

Supported tokens:

<unscopedPackageName> - Package name without @scope/
<packageName> - Full package name
<projectFolder> - Project root directory

Use case: Ship this file as your package’s main type definitions

dtsRollup.betaTrimmedFilePath

Type: string Path for the beta-trimmed .d.ts rollup file. Includes declarations marked with @public and @beta.

{
  "apiExtractor": {
    "dtsRollup": {
      "betaTrimmedFilePath": "./dist/<unscopedPackageName>-beta.d.ts"
    }
  }
}

Use case: Provide early access to beta APIs for testing

dtsRollup.alphaTrimmedFilePath

Type: string Path for the alpha-trimmed .d.ts rollup file. Includes declarations marked with @public, @beta, and @alpha.

{
  "apiExtractor": {
    "dtsRollup": {
      "alphaTrimmedFilePath": "./dist/<unscopedPackageName>-alpha.d.ts"
    }
  }
}

Use case: Provide experimental APIs for early adopters

dtsRollup.untrimmedFilePath

Type: string Path for the untrimmed .d.ts rollup file. Includes all declarations regardless of release level (including @internal).

{
  "apiExtractor": {
    "dtsRollup": {
      "untrimmedFilePath": "./dist/<unscopedPackageName>-internal.d.ts"
    }
  }
}

Use case: Internal testing or monorepo development

Complete Example

{
  "$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",

  "convertReadme": true,
  "readmeTitle": "Overview",

  "templates": {
    "userTemplateDir": "./templates",
    "cache": true,
    "strict": true
  },

  "lint": {
    "eslint": {
      "enabled": true,
      "directories": ["src"]
    },
    "failOnError": true
  },

  "apiExtractor": {
    "bundledPackages": [],
    "compiler": {
      "tsconfigFilePath": "./tsconfig.json",
      "skipLibCheck": true
    },
    "docModel": {
      "enabled": true,
      "projectFolderUrl": "https://github.com/username/repo/tree/main"
    },
    "apiReport": {
      "enabled": false
    },
    "dtsRollup": {
      "enabled": false
    },
    "messages": {
      "compilerMessageReporting": {
        "default": {
          "logLevel": "warning"
        }
      },
      "extractorMessageReporting": {
        "default": {
          "logLevel": "warning"
        },
        "ae-missing-release-tag": {
          "logLevel": "none"
        }
      },
      "tsdocMessageReporting": {
        "default": {
          "logLevel": "warning"
        }
      }
    }
  }
}

Validation

mint-tsdocs validates your configuration on startup. Common validation errors:

Error	Fix
`entryPoint is required`	Add `"entryPoint": "./lib/index.d.ts"`
`entryPoint file not found`	Run `bun run build` to generate .d.ts files
`Invalid docsJson path`	Check path or create docs.json file
`Invalid template directory`	Run `mint-tsdocs customize -t ./templates`

Environment-Specific Configs

Use different configs for different environments: Development:

{
  "templates": {
    "cache": false,
    "strict": true
  }
}

Production:

{
  "templates": {
    "cache": true,
    "strict": true
  }
}

package.json scripts:

{
  "scripts": {
    "docs:dev": "mint-tsdocs --verbose",
    "docs:build": "mint-tsdocs --quiet"
  }
}

Migration from api-documenter

If migrating from @microsoft/api-documenter:

Keep your api-extractor.json:

{
  "apiExtractor": {
    "configPath": "./api-extractor.json"
  }
}

Or let mint-tsdocs generate it:

{
  "entryPoint": "./lib/index.d.ts",
  "apiExtractor": {
    "compiler": {
      "tsconfigFilePath": "./tsconfig.json"
    }
  }
}

​Configuration File

​JSON Schema

​Core Options

​entryPoint

​outputFolder

​docsJson

​Navigation Options

​tabName

​groupName

​README Options

​convertReadme

​readmeTitle

​Template Options

​templates

​templates.userTemplateDir

​templates.cache

​templates.strict

​Lint Options

​lint

​lint.eslint.enabled

​lint.eslint.directories

​lint.eslint.configPath

​lint.failOnError

​Message Reporting Options

​apiExtractor.messages

​messages.compilerMessageReporting

​messages.extractorMessageReporting

​messages.tsdocMessageReporting

​MessageReportingItem

​logLevel

​addToApiReportFile

​API Extractor Options

​apiExtractor

​apiExtractor.configPath

​apiExtractor.bundledPackages

​apiExtractor.compiler

compiler.tsconfigFilePath

compiler.skipLibCheck

​apiExtractor.docModel

docModel.enabled

docModel.projectFolderUrl

​apiExtractor.apiReport

apiReport.enabled

apiReport.reportFileName

apiReport.reportFolder

apiReport.reportTempFolder

​apiExtractor.dtsRollup

dtsRollup.enabled

dtsRollup.publicTrimmedFilePath

dtsRollup.betaTrimmedFilePath

dtsRollup.alphaTrimmedFilePath

dtsRollup.untrimmedFilePath

​Complete Example

​Validation

​Environment-Specific Configs

​Migration from api-documenter

​See Also

Configuration File

JSON Schema

Core Options

entryPoint

outputFolder

docsJson

Navigation Options

tabName

groupName

README Options

convertReadme

readmeTitle

Template Options

templates

templates.userTemplateDir

templates.cache

templates.strict

Lint Options

lint

lint.eslint.enabled

lint.eslint.directories

lint.eslint.configPath

lint.failOnError

Message Reporting Options

apiExtractor.messages

messages.compilerMessageReporting

messages.extractorMessageReporting

messages.tsdocMessageReporting

MessageReportingItem

logLevel

addToApiReportFile

API Extractor Options

apiExtractor

apiExtractor.configPath

apiExtractor.bundledPackages

apiExtractor.compiler

apiExtractor.docModel

apiExtractor.apiReport

apiExtractor.dtsRollup

Complete Example

Validation

Environment-Specific Configs

Migration from api-documenter

See Also