generate

The generate command processes your MDX documentation files, extracts text content, generates text-to-speech audio using Fish Audio, uploads the audio to S3-compatible storage, and automatically injects audio player components into your documentation.

Usage

speak-mintlify generate [directory] [options]

Arguments

string

default:"."

Directory containing MDX files to process. Defaults to current directory.

Options

Voice Configuration

string

Comma-separated list of Fish Audio voice IDs. You can specify multiple voices to generate audio in different styles or languages.Example: --voices "voice-id-1,voice-id-2"Alternative: Define voices in speaker-config.yaml instead of CLI.

string

Comma-separated list of human-readable voice names. Must match the number of voice IDs provided.Example: --voice-names "English,Spanish"These names appear in the audio player UI to help users select voices.

Fish Audio API

string

Your Fish Audio API key for generating TTS audio.Alternative: Set FISH_API_KEY environment variable.

S3 Storage Configuration

string

required

S3 bucket name where audio files will be stored.Alternative: Set S3_BUCKET environment variable.

string

default:"us-east-1"

AWS region for your S3 bucket.Alternative: Set S3_REGION environment variable.

string

Custom S3 endpoint URL. Required for S3-compatible services like Cloudflare R2, MinIO, or DigitalOcean Spaces.Example: --s3-endpoint "https://account-id.r2.cloudflarestorage.com"Alternative: Set S3_ENDPOINT environment variable.

string

required

S3 access key ID for authentication.Alternative: Set S3_ACCESS_KEY_ID environment variable.

string

required

S3 secret access key for authentication.Alternative: Set S3_SECRET_ACCESS_KEY environment variable.

string

required

Public CDN URL for accessing uploaded audio files. This URL is embedded in your documentation.Example: --s3-public-url "https://cdn.example.com"Alternative: Set S3_PUBLIC_URL environment variable.

string

default:"audio"

Directory prefix for organizing audio files in S3.Example: With prefix audio, files are stored as audio/page-slug/voice-id.mp3

Component Configuration

string

default:"/snippets/audio-transcript.jsx"

Import path for the audio player component. This is the path used in MDX imports.Example: --component-import "/components/AudioPlayer.jsx"

string

default:"AudioTranscript"

Name of the audio player component to inject into MDX files.Example: --component-name "AudioPlayer"

File Selection

string

default:"**/*.mdx"

Glob pattern for selecting MDX files to process.Examples:

**/*.mdx - All MDX files recursively
docs/**/*.mdx - Only files in docs directory
guides/*.mdx - Only top-level guides

Execution Options

boolean

default:false

Simulate the generation process without making actual changes. Shows a diff preview of what would be modified.Useful for:

Testing configuration before committing
Previewing component injection
Verifying file selection

boolean

default:false

Show detailed processing information including:

Extracted text content for each file
Content hashes
Full processing results
File-by-file status

Examples

Basic Usage

Generate audio for all MDX files in current directory:

speak-mintlify generate

Specify Directory

Process files in a specific directory:

speak-mintlify generate ./docs

Multiple Voices

Generate audio with multiple voices (e.g., different languages):

speak-mintlify generate \
  --voices "voice-en-us,voice-es-mx" \
  --voice-names "English,Spanish"

Complete Configuration

Full command with all S3 options:

speak-mintlify generate ./docs \
  --voices "7359a92bc1dc4f3dac94343da99a986f" \
  --voice-names "Sarah" \
  --api-key "your-fish-api-key" \
  --s3-bucket "my-docs-audio" \
  --s3-region "us-west-2" \
  --s3-access-key-id "AKIAIOSFODNN7EXAMPLE" \
  --s3-secret-access-key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  --s3-public-url "https://cdn.example.com" \
  --verbose

Using Cloudflare R2

speak-mintlify generate \
  --voices "your-voice-id" \
  --s3-bucket "my-bucket" \
  --s3-endpoint "https://account-id.r2.cloudflarestorage.com" \
  --s3-public-url "https://pub-123.r2.dev"

Dry Run Preview

Preview changes without modifying files:

speak-mintlify generate --dry-run --verbose

Output:

✔ Found 15 MDX file(s)
ℹ [DRY RUN] guides/quickstart.mdx

  Changes that would be made:
  @@ -1,3 +1,8 @@
  +import AudioTranscript from '/snippets/audio-transcript.jsx';
  +
   ---
   title: 'Quickstart'
   ---
  +
  +<AudioTranscript hash="a1b2c3d4" voices={[{"id":"voice-1","name":"English","url":"https://cdn.example.com/audio/guides-quickstart/voice-1.mp3"}]} />

Specific File Pattern

Process only files in a specific subdirectory:

speak-mintlify generate --pattern "guides/**/*.mdx"

How It Works

File Discovery: Scans for MDX files matching the specified pattern
Text Extraction: Extracts clean, readable text from each MDX file (removes code blocks, frontmatter, JSX)
Hash Generation: Creates a content hash to track changes
Change Detection: Skips files where content and voices haven’t changed
TTS Generation: Calls Fish Audio API to generate audio for each voice
S3 Upload: Uploads generated MP3 files to your S3 bucket
Component Injection: Adds or updates the audio player component in MDX files
File Update: Writes modified MDX files back to disk

Smart Caching

The generate command intelligently skips files that haven’t changed:

Each file stores a hash of its text content in the audio component
On subsequent runs, if the hash matches and voice IDs are the same, generation is skipped
This saves API costs and processing time
Forces regeneration by modifying text content or changing voice IDs

Output

Successful execution shows progress for each file:

✔ Initializing...
✔ Found 10 MDX file(s)
✔ Generated TTS for introduction.mdx
ℹ Skipping quickstart.mdx - content unchanged (hash in MDX)
✔ Generated TTS for configuration.mdx

Summary:
  Successfully processed: 2
  Skipped: 8
  Failed: 0

Error Handling

Common errors and solutions:

Missing API key: Set FISH_API_KEY or use --api-key
S3 authentication failed: Verify access key ID and secret access key
Bucket not found: Check bucket name and region
No files found: Verify directory path and glob pattern
Invalid voice ID: Check voice ID exists in your Fish Audio account

Environment Variables

For convenience, set environment variables instead of CLI options:

export FISH_API_KEY="your-api-key"
export S3_BUCKET="my-docs-audio"
export S3_REGION="us-east-1"
export S3_ACCESS_KEY_ID="your-access-key"
export S3_SECRET_ACCESS_KEY="your-secret-key"
export S3_PUBLIC_URL="https://cdn.example.com"

# Now run with minimal options
speak-mintlify generate --voices "voice-id"

Configuration File

Create speaker-config.yaml in your project root:

voices:
  - id: 7359a92bc1dc4f3dac94343da99a986f
    name: English
  - id: 8460b03cd2ed5e4ebd05454eb00b097g
    name: Spanish

Then run without --voices and --voice-names:

speak-mintlify generate

Get Started

Configuration

Commands

Guides

Reference

Usage

Arguments

Options

Voice Configuration

Fish Audio API

S3 Storage Configuration

Component Configuration

File Selection

Execution Options

Examples

Basic Usage

Specify Directory

Multiple Voices

Complete Configuration

Using Cloudflare R2

Dry Run Preview

Specific File Pattern

How It Works

Smart Caching

Output

Error Handling

Environment Variables

Configuration File

​Usage

​Arguments

​Options

​Voice Configuration

​Fish Audio API

​S3 Storage Configuration

​Component Configuration

​File Selection

​Execution Options

​Examples

​Basic Usage

​Specify Directory

​Multiple Voices

​Complete Configuration

​Using Cloudflare R2

​Dry Run Preview

​Specific File Pattern

​How It Works

​Smart Caching

​Output

​Error Handling

​Environment Variables

​Configuration File

Usage

Arguments

Options

Voice Configuration

Fish Audio API

S3 Storage Configuration

Component Configuration

File Selection

Execution Options

Examples

Basic Usage

Specify Directory

Multiple Voices

Complete Configuration

Using Cloudflare R2

Dry Run Preview

Specific File Pattern

How It Works

Smart Caching

Output

Error Handling

Environment Variables

Configuration File