Emission Layer

Overview

The emission layer transforms TSDoc AST (Abstract Syntax Tree) into Mintlify-compatible MDX format. It handles the final rendering step, converting semantic document structures into formatted markdown with Mintlify-specific components.

Primary Component: src/markdown/CustomMarkdownEmitter.ts

Recent Enhancement: The emission layer now includes API resolution caching for improved performance during cross-reference resolution.

Key Responsibilities

AST to MDX Conversion

Transforms TSDoc AST nodes into MDX strings

Mintlify Component Generation

Creates specialized components like <ParamField> and <ResponseField>

API Resolution Caching

Caches cross-reference resolution for performance

Link Resolution

Resolves cross-references between API items

Architecture

Core Components

CustomMarkdownEmitter

Constructor and Initialization

Initializes with API model and caching:

export class CustomMarkdownEmitter extends MarkdownEmitter {
  private _apiModel: ApiModel;
  private _docHelper: DocumentationHelper;
  private _apiResolutionCache: ApiResolutionCache;

  public constructor(apiModel: ApiModel) {
    super();

    this._apiModel = apiModel;
    this._docHelper = new DocumentationHelper();
    this._apiResolutionCache = new ApiResolutionCache({
      enabled: true,
      maxSize: 500
    });
  }
}

Caching Integration: Automatically creates API resolution cache for improved performance

Main Emission Method

Primary method for AST to MDX conversion:

public emit(stringBuilder: StringBuilder, docNode: DocNode, context: IMarkdownEmitterContext): void

Process:

Traverse TSDoc AST recursively
Identify node types and apply appropriate rendering
Handle special cases (tables, links, etc.)
Generate Mintlify-specific components
Resolve cross-references with caching

Node Type Handling

Specialized rendering for different DocNode types:

protected writeNode(docNode: DocNode, context: IMarkdownEmitterContext, docNodeSiblings: boolean): void {
  switch (docNode.kind) {
    case CustomDocNodeKind.Table:
      this._writeTable(docNode as DocTable, context);
      break;
    case CustomDocNodeKind.Heading:
      this._writeHeading(docNode as DocHeading, context);
      break;
    case CustomDocNodeKind.Expandable:
      this._writeExpandable(docNode as DocExpandable, context);
      break;
    // ... other node types
  }
}

Mintlify Component Generation

Intelligent Table Conversion

DocTable to Mintlify Components

The emitter’s most critical feature is intelligent table handling:

private _writeTable(docTable: DocTable, context: IMarkdownEmitterContext): void {
  // Analyze table content to determine type
  const isPropertyTable = this._isPropertyTable(docTable);
  const isMethodTable = this._isMethodTable(docTable);
  const isParameterTable = this._isParameterTable(docTable);

  if (isPropertyTable) {
    this._writePropertySection(docTable, context);
  } else if (isMethodTable) {
    this._writeMethodSection(docTable, context);
  } else if (isParameterTable) {
    this._writeParameterSection(docTable, context);
  } else {
    // Default to standard markdown table
    this._writeGenericTable(docTable, context);
  }
}

Detection Logic: Analyzes table headers and content to identify the appropriate Mintlify component

Property Section Generation

Converts property tables to <ParamField> components:

private _writePropertySection(docTable: DocTable, context: IMarkdownEmitterContext): void {
  for (const row of docTable.rows) {
    const propertyName = this._getCellContent(row.cells[0]);
    const propertyType = this._getCellContent(row.cells[1]);
    const description = this._getCellContent(row.cells[2]);

    // Use DocumentationHelper for type analysis
    const propertyInfo = this._docHelper.analyzeTypeProperties(propertyType);

    // Generate ParamField component
    stringBuilder.appendLine(`\u003cParamField body={\`${propertyName}\`} type="${propertyInfo.type}"\u003e`);
    stringBuilder.appendLine(`  ${description}`);

    // Add nested properties if complex type
    if (propertyInfo.properties.length > 0) {
      this._writeNestedProperties(propertyInfo.properties, stringBuilder, 1);
    }

    stringBuilder.appendLine(`\u003c/ParamField\u003e`);
  }
}

Features:

Type analysis with nested property support
Automatic required/optional detection
Complex type expansion

Method Section Generation

Converts method tables to <ResponseField> components:

private _writeMethodSection(docTable: DocTable, context: IMarkdownEmitterContext): void {
  for (const row of docTable.rows) {
    const methodName = this._getCellContent(row.cells[0]);
    const returnType = this._getCellContent(row.cells[1]);
    const description = this._getCellContent(row.cells[2]);

    // Generate ResponseField component
    stringBuilder.appendLine(`\u003cResponseField name="${methodName}" type="${returnType}"\u003e`);
    stringBuilder.appendLine(`  ${description}`);
    stringBuilder.appendLine(`\u003c/ResponseField\u003e`);
  }
}

Output Example:

<ResponseField name="getUser" type="User">
  Retrieves a user by ID
</ResponseField>

API Resolution Caching

Cached Resolution Strategy

Implements intelligent caching for API resolution:

private _resolveApiItemReference(declarationReference: string, context: IMarkdownEmitterContext): IResolveDeclarationReferenceResult {
  // Check cache first
  const cachedResult = this._apiResolutionCache.get(
    declarationReference,
    context.apiItem
  );

  if (cachedResult) {
    return cachedResult;
  }

  // Perform resolution
  const result = this._apiModel.resolveDeclarationReference(
    declarationReference,
    context.apiItem
  );

  // Cache result
  this._apiResolutionCache.set(
    declarationReference,
    context.apiItem,
    result
  );

  return result;
}

Cache Key Strategy:

const refString = JSON.stringify(declarationReference);
const contextString = contextApiItem?.canonicalReference?.toString() || '';
return `${refString}|${contextString}`;

Performance Benefits: 20-40% improvement for documentation with dense cross-references

Link Generation

Generates proper relative links for cross-references:

private _writeLinkTagWithCodeDestination(docLinkTag: DocLinkTag, context: IMarkdownEmitterContext): void {
  const result = this._resolveApiItemReference(docLinkTag.codeDestination, context);

  if (result.resolvedApiItem) {
    // Generate relative link to resolved item
    const relativePath = this._getLinkFilenameForApiItem(result.resolvedApiItem);
    const linkText = docLinkTag.linkText || result.resolvedApiItem.displayName;

    stringBuilder.append(`[${linkText}](${relativePath})`);
  } else {
    // Fallback to plain text
    stringBuilder.append(docLinkTag.linkText || docLinkTag.codeDestination);
  }
}

Features:

Automatic path resolution
Relative link generation
Fallback for unresolved references

Type Analysis Integration

DocumentationHelper Integration

Leverages DocumentationHelper for sophisticated type analysis:

private _writeParameterSection(docTable: DocTable, context: IMarkdownEmitterContext): void {
  for (const row of docTable.rows) {
    const paramName = this._getCellContent(row.cells[0]);
    const paramType = this._getCellContent(row.cells[1]);
    const description = this._getCellContent(row.cells[2]);

    // Analyze type with nested property detection
    const propertyInfo = this._docHelper.analyzeTypeProperties(paramType);

    // Generate ParamField with full type information
    stringBuilder.appendLine(`\u003cParamField body={\`${paramName}\`} type="${propertyInfo.type}"\u003e`);
    stringBuilder.appendLine(`  ${description}`);

    // Add nested properties for complex types
    if (propertyInfo.properties.length > 0) {
      this._writeNestedProperties(propertyInfo.properties, stringBuilder, 1);
    }

    stringBuilder.appendLine(`\u003c/ParamField\u003e`);
  }
}

Capabilities:

Recursive type analysis
Nested property documentation
Union and intersection type handling
Generic type parameter support

Complex Type Handling

Sophisticated handling of complex TypeScript types:

// Example: Complex generic type
const complexType = "Promise<Array<{ id: string; data: T }\u003e\u003e";

// Analyzed output:
{
  type: "Promise<Array<Object\u003e\u003e",
  properties: [
    {
      name: "id",
      type: "string",
      description: "Unique identifier",
      required: true
    },
    {
      name: "data",
      type: "T",
      description: "Generic data payload",
      required: true
    }
  ],
  isGeneric: true,
  generics: ["T"]
}

Supported Patterns:

Nested object literals
Generic types with parameters
Union types (A | B)
Intersection types (A & B)
Array and Promise wrappers
Conditional types

Performance Optimization

Caching Benefits

API resolution caching provides significant performance improvements:Before Caching:

// Each resolution requires full API model traversal
const result1 = apiModel.resolveDeclarationReference(ref1, context); // ~5ms
const result2 = apiModel.resolveDeclarationReference(ref2, context); // ~5ms
const result3 = apiModel.resolveDeclarationReference(ref1, context); // ~5ms (duplicate!)

After Caching:

// First resolution cached, subsequent hits are instant
const result1 = cachedResolve(ref1, context); // ~5ms (cache miss)
const result2 = cachedResolve(ref2, context); // ~5ms (cache miss)
const result3 = cachedResolve(ref1, context); // ~0.1ms (cache hit!)

Measured Improvements:

20-40% faster for documentation with dense cross-references
Significant improvement for large codebases
Reduced memory pressure from repeated traversals

Cache Configuration

Configurable cache settings for different use cases:

// Development configuration
const emitter = new CustomMarkdownEmitter(apiModel, {
  apiResolutionCache: {
    enabled: true,
    maxSize: 200 // Smaller for development
  }
});

// Production configuration
const emitter = new CustomMarkdownEmitter(apiModel, {
  apiResolutionCache: {
    enabled: true,
    maxSize: 1000 // Larger for production
  }
});

Tuning Guidelines:

Small Projects: 200-500 items
Medium Projects: 500-1000 items
Large Projects: 1000+ items
Memory-Constrained: Disable or reduce size

Error Handling and Fallbacks

Graceful Degradation

Robust error handling with fallback strategies:

private _writeLinkTagWithCodeDestination(docLinkTag: DocLinkTag, context: IMarkdownEmitterContext): void {
  try {
    const result = this._resolveApiItemReference(docLinkTag.codeDestination, context);

    if (result.resolvedApiItem) {
      // Success: Generate proper link
      const relativePath = this._getLinkFilenameForApiItem(result.resolvedApiItem);
      stringBuilder.append(`[${linkText}](${relativePath})`);
    } else {
      // Fallback: Plain text
      stringBuilder.append(docLinkTag.linkText || docLinkTag.codeDestination);
    }
  } catch (error) {
    // Error fallback: Plain text
    console.warn(`Failed to resolve link: ${docLinkTag.codeDestination}`, error);
    stringBuilder.append(docLinkTag.linkText || docLinkTag.codeDestination);
  }
}

Fallback Hierarchy:

Success: Generate proper relative link
Unresolved: Use plain text with warning
Error: Use plain text with error logging

Cache Error Handling

Defensive programming for cache operations:

private _resolveApiItemReference(declarationReference: string, context: IMarkdownEmitterContext): IResolveDeclarationReferenceResult {
  try {
    // Attempt cache lookup
    const cachedResult = this._apiResolutionCache.get(declarationReference, context.apiItem);
    if (cachedResult) {
      return cachedResult;
    }
  } catch (cacheError) {
    console.warn('Cache lookup failed, proceeding with resolution:', cacheError);
  }

  try {
    // Perform actual resolution
    const result = this._apiModel.resolveDeclarationReference(declarationReference, context.apiItem);

    // Attempt to cache result (don't fail if caching fails)
    try {
      this._apiResolutionCache.set(declarationReference, context.apiItem, result);
    } catch (cacheError) {
      console.warn('Failed to cache resolution result:', cacheError);
    }

    return result;
  } catch (resolutionError) {
    console.error('API resolution failed:', resolutionError);
    throw resolutionError;
  }
}

Resilience Features:

Cache failures don’t break resolution
Resolution failures are properly logged
Always returns valid result or throws clear error

Best Practices

Cache Optimization

Monitor Cache Performance:

// Check cache statistics
const cacheStats = emitter.getApiResolutionCache().getStats();
console.log(`API Resolution Cache: ${cacheStats.hitRate * 100}% hit rate`);

Tune Cache Size:

Start with default (500 items)
Monitor hit rates during development
Increase size for large codebases
Consider memory usage vs. performance trade-offs

When to Disable:

Very small projects (minimal benefit)
Memory-constrained environments
Debugging resolution issues

Component Generation

Consistent Table Structure:

Maintain standard column order: Name, Type, Description
Use consistent header names for detection
Include modifier information in type column

Type Documentation:

Provide complete type information
Include examples for complex types
Document nested object structures

Link Resolution:

Use proper declaration references
Maintain consistent naming conventions
Test cross-references in generated docs

Troubleshooting

Component Generation Issues

Symptoms: Tables not converted to Mintlify componentsCauses:

Incorrect table header format
Missing required columns
Non-standard table structure

Solutions:

Verify table headers match expected patterns
Ensure consistent column structure
Check detection logic in _isPropertyTable() etc.

Debugging:

    console.log('Table headers:', this._getTableHeaders(docTable));
    console.log('Is property table:', this._isPropertyTable(docTable));

Cache Performance Issues

Symptoms: Low cache hit rates or poor performanceCauses:

Cache size too small for project
Too many unique references
Cache key collisions

Solutions:

Increase cache size
Analyze reference patterns
Check cache key generation
Consider disabling for small projects

Monitoring:

    const stats = emitter.getApiResolutionCache().getStats();
    console.log(`Hit rate: ${stats.hitRate}, Size: ${stats.size}/${stats.maxSize}`);

Link Resolution Failures

Symptoms: Broken links or unresolved referencesCauses:

Invalid declaration references
Missing API items
Incorrect context resolution

Solutions:

Verify declaration reference format
Check API model completeness
Validate context item
Review fallback behavior

Debugging:

    console.log('Declaration reference:', declarationReference);
    console.log('Context item:', context.apiItem?.displayName);
    console.log('Resolution result:', result.resolvedApiItem);

Generation Layer

See how AST is constructed and emitted

Caching Layer

Learn about API resolution caching

Utilities Layer

Explore DocumentationHelper and type analysis

AST Nodes

Understand custom TSDoc nodes

Concepts

Guides

OpenDocs Specification

Architecture

Overview

Key Responsibilities

AST to MDX Conversion

Mintlify Component Generation

API Resolution Caching

Link Resolution

Architecture

Core Components

CustomMarkdownEmitter

Mintlify Component Generation

Intelligent Table Conversion

API Resolution Caching

Type Analysis Integration

Performance Optimization

Error Handling and Fallbacks

Best Practices

Troubleshooting

Generation Layer

Caching Layer

Utilities Layer

AST Nodes

Concepts

Guides

OpenDocs Specification

Architecture

​Overview

​Key Responsibilities

AST to MDX Conversion

Mintlify Component Generation

API Resolution Caching

Link Resolution

​Architecture

​Core Components

​CustomMarkdownEmitter

​Mintlify Component Generation

​Intelligent Table Conversion

​API Resolution Caching

​Type Analysis Integration

​Performance Optimization

​Error Handling and Fallbacks

​Best Practices

​Troubleshooting

​Related Documentation

Generation Layer

Caching Layer

Utilities Layer

AST Nodes

Overview

Key Responsibilities

Architecture

Core Components

CustomMarkdownEmitter

Mintlify Component Generation

Intelligent Table Conversion

API Resolution Caching

Type Analysis Integration

Performance Optimization

Error Handling and Fallbacks

Best Practices

Troubleshooting

Related Documentation