> ## Documentation Index
> Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Complete reference for mint-tsdocs.config.json configuration options

## Configuration File

mint-tsdocs uses [cosmiconfig](https://github.com/cosmiconfig/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:

```json theme={null}
{
  "$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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

***

## Navigation Options

### tabName

**Type:** `string`

**Default:** `"API Reference"`

Name of the tab in Mintlify navigation where API docs will appear.

```json theme={null}
{
  "tabName": "API Reference"
}
```

**Example in docs.json:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "groupName": "API"
}
```

**Example in docs.json:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`).

```json theme={null}
{
  "readmeTitle": "Getting Started"
}
```

***

## Template Options

### templates

**Type:** `object`

Configuration for Liquid template customization.

```json theme={null}
{
  "templates": {
    "userTemplateDir": "./templates",
    "cache": true,
    "strict": true
  }
}
```

#### templates.userTemplateDir

**Type:** `string`

Path to directory containing custom Liquid templates.

```json theme={null}
{
  "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:**

```bash theme={null}
mint-tsdocs customize -t ./templates
```

***

#### templates.cache

**Type:** `boolean`

**Default:** `true`

Whether to cache compiled templates for better performance.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "lint": {
    "eslint": {
      "enabled": true
    }
  }
}
```

**Required packages (when enabled):**

```bash theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "lint": {
    "failOnError": false
  }
}
```

***

## Message Reporting Options

### apiExtractor.messages

**Type:** `object`

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:**

```json theme={null}
{
  "logLevel": "warning",
  "addToApiReportFile": true
}
```

***

## API Extractor Options

### apiExtractor

**Type:** `object`

Configuration for API Extractor integration.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "apiExtractor": {
    "apiReport": {
      "enabled": true
    }
  }
}
```

***

##### apiReport.reportFileName

**Type:** `string`

**Default:** `"<unscopedPackageName>.api.md"`

Name pattern for the API report file.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "apiExtractor": {
    "dtsRollup": {
      "enabled": true
    }
  }
}
```

***

##### dtsRollup.publicTrimmedFilePath

**Type:** `string`

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

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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`).

```json theme={null}
{
  "apiExtractor": {
    "dtsRollup": {
      "untrimmedFilePath": "./dist/<unscopedPackageName>-internal.d.ts"
    }
  }
}
```

**Use case:** Internal testing or monorepo development

***

## Complete Example

```json theme={null}
{
  "$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:**

```json theme={null}
{
  "templates": {
    "cache": false,
    "strict": true
  }
}
```

**Production:**

```json theme={null}
{
  "templates": {
    "cache": true,
    "strict": true
  }
}
```

**package.json scripts:**

```json theme={null}
{
  "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:**
   ```json theme={null}
   {
     "apiExtractor": {
       "configPath": "./api-extractor.json"
     }
   }
   ```

2. **Or let mint-tsdocs generate it:**
   ```json theme={null}
   {
     "entryPoint": "./lib/index.d.ts",
     "apiExtractor": {
       "compiler": {
         "tsconfigFilePath": "./tsconfig.json"
       }
     }
   }
   ```

***

## See Also

* **[Cheat Sheet](/cheat-sheet)** - Quick command reference
* **[CLI Reference](/cli-reference)** - Complete CLI documentation
* **[tsdoc.json Reference](/tsdoc-reference)** - TSDoc configuration file reference
* **[API Extractor Docs](https://api-extractor.com/)** - API Extractor configuration
* **[TSDoc Specification](https://tsdoc.org/)** - TSDoc tag reference