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. 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:
/**
* 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 {
// ...
}
---
title: "CacheManager"
description: "Centralized cache coordinator for TypeScript analysis and API resolution"
---
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:
/**
* 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 {
// ...
}
/**
* Manages markdown documentation.
*/
export class MarkdownDocumenter {
// ...
}
Interfaces
Describe what data it represents and where it’s used:
/**
* 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 {
// ...
}
/**
* Template data structure.
*/
export interface ITemplateData {
// ...
}
Functions
Explain what it does and key parameters/behavior:
/**
* 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 {
// ...
}
Enums/Types
Describe possible values and use case:
/**
* 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 {
// ...
}
Best practices
Length
Aim for 10-25 words in the first line (what becomes the description):
/**
* 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:
/**
* Liquid template engine for rendering API documentation.
* ^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^
* Keywords: liquid, template, engine, rendering, API, documentation
*/
Consistency
Use similar patterns for similar items:
/**
* 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 { }
Checking your descriptions
After generating docs, review your llms.txt:
Generate and deploy
bun run mint-tsdocs generate
# Deploy to Mintlify
Access llms.txt
Visit https://your-docs-url/llms.txt to see the generated file.
Review API reference section
## 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...
- ✅ Descriptive (not just repeating the class name)
- ✅ Scannable (10-25 words)
- ✅ Accurate (match what the class actually does)
User: "What caching options are available?"
AI: "I see CacheManager, TypeAnalysisCache, and ApiResolutionCache classes"
[Can't explain what each does without reading full pages]
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."
llms.txt alone, without fetching all pages.
Updating descriptions
To improve a description:
-
Edit TSDoc in source code:
/**
* [New description here]
*
* @remarks
* Additional details...
*/
-
Regenerate documentation:
bun run build # Build your TypeScript
bun run mint-tsdocs generate
-
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
