Skip to main content

​
Configuration File

mint-tsdocs uses cosmiconfig to load configuration. It searches for configuration in the following locations (in order):
  1. mint-tsdocs.config.json (recommended)
  2. .mint-tsdocsrc
  3. .mint-tsdocsrc.json
  4. 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

​
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
  },

  "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:
ErrorFix
entryPoint is requiredAdd "entryPoint": "./lib/index.d.ts"
entryPoint file not foundRun bun run build to generate .d.ts files
Invalid docsJson pathCheck path or create docs.json file
Invalid template directoryRun 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:
  1. Keep your api-extractor.json: 
    {
  "apiExtractor": {
    "configPath": "./api-extractor.json"
  }
}
  2. Or let mint-tsdocs generate it: 
    {
  "entryPoint": "./lib/index.d.ts",
  "apiExtractor": {
    "compiler": {
      "tsconfigFilePath": "./tsconfig.json"
    }
  }
}

​
See Also