> ## 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.
# llms.txt Optimization
> Write better TSDoc comments to improve AI navigation of your API reference
Mintlify automatically generates `llms.txt` from your documentation. This guide focuses on writing TSDoc comments that produce helpful descriptions for your generated API reference.
For general llms.txt information, see [Mintlify's llms.txt documentation](https://www.mintlify.com/docs/ai/llmstxt).
## Why llms.txt matters for mint-tsdocs
When you generate 400+ API reference pages, `llms.txt` acts as a table of contents for AI tools. It contains:
* Page titles (your class/interface names)
* Descriptions (from your TSDoc `@remarks`)
* Organization (from your `docs.json` structure)
Good descriptions help AI tools:
* Find relevant classes: "What caching options exist?" → Finds CacheManager with description
* Understand purpose: Knows CacheManager handles caching, not cache instances
* Navigate hierarchy: Understands relationships between classes
## How mint-tsdocs generates descriptions
mint-tsdocs extracts frontmatter descriptions from your TSDoc comments:
```typescript theme={null}
/**
* Centralized cache coordinator for TypeScript analysis and API resolution.
*
* @remarks
* Provides production and development presets with configurable cache sizes
* and optional statistics tracking for performance monitoring.
*/
export class CacheManager {
// ...
}
```
Generates:
```yaml theme={null}
---
title: "CacheManager"
description: "Centralized cache coordinator for TypeScript analysis and API resolution"
---
```
This description appears in:
* `llms.txt` (for AI tool indexing)
* Page frontmatter (for SEO and navigation)
* API reference page (below the title)
## Writing effective descriptions
### Classes
Focus on **what it does** and **key features**:
```typescript theme={null}
/**
* Main orchestrator for documentation generation.
*
* @remarks
* Coordinates template rendering, MDX generation, and navigation updates.
* Processes API models from API Extractor into Mintlify-compatible documentation.
*/
export class MarkdownDocumenter {
// ...
}
```
✅ Good: Explains role, lists main responsibilities, mentions output format
```typescript theme={null}
/**
* Manages markdown documentation.
*/
export class MarkdownDocumenter {
// ...
}
```
❌ Too vague: Doesn't explain what "manages" means or what it produces
### Interfaces
Describe **what data it represents** and **where it's used**:
```typescript theme={null}
/**
* Template variables available in Liquid templates.
*
* @remarks
* Provides semantic variables (properties, methods, parameters) and metadata
* (apiItem, page, navigation) for rendering API documentation pages.
*/
export interface ITemplateData {
// ...
}
```
✅ Good: Explains purpose, lists variable categories, mentions usage context
```typescript theme={null}
/**
* Template data structure.
*/
export interface ITemplateData {
// ...
}
```
❌ Too generic: Doesn't explain what template data this represents
### Functions
Explain **what it does** and **key parameters/behavior**:
```typescript theme={null}
/**
* Generates API Extractor configuration from mint-tsdocs config.
*
* @remarks
* Auto-detects entry points, creates .tsdocs cache directory, and generates
* api-extractor.json with proper paths for doc model output.
*/
export function generateApiExtractorConfig(config: ResolvedConfig): void {
// ...
}
```
✅ Good: Clear action, mentions auto-detection, explains what it creates
### Enums/Types
Describe **possible values** and **use case**:
```typescript theme={null}
/**
* Error codes for documentation generation failures.
*
* @remarks
* Includes validation errors (INVALID_CONFIG), file system errors (FILE_NOT_FOUND),
* template errors (TEMPLATE_ERROR), and API extraction errors (EXTRACTION_FAILED).
*/
export enum ErrorCode {
// ...
}
```
✅ Good: Explains purpose, groups error categories, provides examples
## Best practices
### Length
Aim for **10-25 words** in the first line (what becomes the description):
```typescript theme={null}
/**
* Centralized cache coordinator for TypeScript analysis and API resolution.
* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Perfect length - descriptive but scannable
*
* @remarks
* Additional details go here...
*/
```
### Specificity
Use concrete terms over vague ones:
✅ "Converts API models to template data for Liquid rendering"
❌ "Handles template data conversion"
✅ "LRU cache for type structure analysis with configurable size limits"
❌ "Cache implementation"
### Keywords
Include TypeScript/API terminology that users might search for:
```typescript theme={null}
/**
* Liquid template engine for rendering API documentation.
* ^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^
* Keywords: liquid, template, engine, rendering, API, documentation
*/
```
### Consistency
Use similar patterns for similar items:
```typescript theme={null}
/**
* Centralized cache coordinator for TypeScript analysis and API resolution.
*/
export class CacheManager { }
/**
* LRU cache for type structure analysis with eviction and statistics.
*/
export class TypeAnalysisCache { }
/**
* LRU cache for API reference resolution with cached decorator support.
*/
export class ApiResolutionCache { }
```
All cache classes follow the pattern: "\[Type] cache for \[purpose] with \[features]"
## Checking your descriptions
After generating docs, review your `llms.txt`:
```bash theme={null}
bun run mint-tsdocs generate
# Deploy to Mintlify
```
Visit `https://your-docs-url/llms.txt` to see the generated file.
```markdown theme={null}
## API Reference
- [CacheManager](reference/mint-tsdocs.cachemanager): Centralized cache coordinator...
- [MarkdownDocumenter](reference/mint-tsdocs.markdowndocumenter): Main orchestrator...
- [ITemplateData](reference/mint-tsdocs.itemplatedata): Template variables available...
```
Check that descriptions are:
* ✅ Descriptive (not just repeating the class name)
* ✅ Scannable (10-25 words)
* ✅ Accurate (match what the class actually does)
## Impact on AI tools
**Before optimization:**
```
User: "What caching options are available?"
AI: "I see CacheManager, TypeAnalysisCache, and ApiResolutionCache classes"
[Can't explain what each does without reading full pages]
```
**After optimization:**
```
User: "What caching options are available?"
AI: "There are three caching components:
- CacheManager: Centralized coordinator with presets
- TypeAnalysisCache: For type structure analysis
- ApiResolutionCache: For API reference resolution
Each supports LRU eviction and optional statistics."
```
The AI can answer from `llms.txt` alone, without fetching all pages.
## Updating descriptions
To improve a description:
1. **Edit TSDoc in source code**:
```typescript theme={null}
/**
* [New description here]
*
* @remarks
* Additional details...
*/
```
2. **Regenerate documentation**:
```bash theme={null}
bun run build # Build your TypeScript
bun run mint-tsdocs generate
```
3. **Verify in llms.txt** after deploying
Focus on your most commonly used classes first. Optimize CacheManager, MarkdownDocumenter, ITemplateData, etc. before less common utilities.
## Learn more
Full llms.txt specification and features
Supported TSDoc tags and syntax
Real-time search alternative to llms.txt
Configure frontmatter generation