Skip to main content
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

​
directory
string
default:"."
Directory containing MDX files to process. Defaults to current directory.

​
Options

​
Voice Configuration

​
--voices
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.
​
--voice-names
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

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

​
S3 Storage Configuration

​
--s3-bucket
string
required
S3 bucket name where audio files will be stored.Alternative: Set S3_BUCKET environment variable.
​
--s3-region
string
default:"us-east-1"
AWS region for your S3 bucket.Alternative: Set S3_REGION environment variable.
​
--s3-endpoint
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.
​
--s3-access-key-id
string
required
S3 access key ID for authentication.Alternative: Set S3_ACCESS_KEY_ID environment variable.
​
--s3-secret-access-key
string
required
S3 secret access key for authentication.Alternative: Set S3_SECRET_ACCESS_KEY environment variable.
​
--s3-public-url
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.
​
--s3-path-prefix
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

​
--component-import
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"
​
--component-name
string
default:"AudioTranscript"
Name of the audio player component to inject into MDX files.Example: --component-name "AudioPlayer"

​
File Selection

​
--pattern
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

​
--dry-run
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
​
--verbose
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

  1. File Discovery: Scans for MDX files matching the specified pattern
  2. Text Extraction: Extracts clean, readable text from each MDX file (removes code blocks, frontmatter, JSX)
  3. Hash Generation: Creates a content hash to track changes
  4. Change Detection: Skips files where content and voices haven’t changed
  5. TTS Generation: Calls Fish Audio API to generate audio for each voice
  6. S3 Upload: Uploads generated MP3 files to your S3 bucket
  7. Component Injection: Adds or updates the audio player component in MDX files
  8. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us