Skip to main content
This guide walks you through adding voice narration to your Mintlify documentation from start to finish.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18.0.0 or higher installed
  • A Mintlify documentation project with MDX files
  • A Fish Audio API key
  • An S3-compatible storage service (AWS S3, Cloudflare R2, MinIO, etc.)
1

Install speak-mintlify

Install speak-mintlify in your documentation repository:
npm install speak-mintlify
You can also use npx speak-mintlify without installing to run commands directly
2

Create speaker-config.yaml

Create a speaker-config.yaml file at your repository root to configure voices and component settings:
speaker-config.yaml
# Voice Configuration (map of voice ID -> display name)
voices:
  8ef4a238714b45718ce04243307c57a7: E-girl
  bf322df2096a46f18c579d0baa36f41d: Adrian
  # Add more voices as needed

# Component Configuration (optional)
component:
  import: /snippets/audio-transcript.jsx
  name: AudioTranscript
Voice IDs come from Fish Audio. You can find available voices in your Fish Audio dashboard.
3

Configure environment variables

Create a .env file at your repository root with your API credentials:
.env
# Secrets (required)
FISH_API_KEY=your_api_key
S3_ACCESS_KEY_ID=your_access_key_id
S3_SECRET_ACCESS_KEY=your_secret_key

# S3 Config (required)
S3_BUCKET=your-bucket
S3_PUBLIC_URL=https://s3.example.com
S3_REGION=us-east-1
S3_ENDPOINT=https://s3-endpoint.example.com
Never commit your .env file to version control. Add it to your .gitignore.
4

Create your audio component

Create an audio player component that matches the import path in your speaker-config.yaml.Your component needs to accept a voices prop with this structure:
{
  voices: Array<{
    name: string;    // Display name for the voice
    url: string;     // Audio file URL from S3
  }>
}
Example usage in your MDX:
<AudioTranscript
  voices={[
    { name: "Natural Voice", url: "https://s3.../audio1.mp3" },
    { name: "Professional Voice", url: "https://s3.../audio2.mp3" }
  ]}
/>
5

Generate audio for your docs

Run the generator on your documentation directory:
npx speak-mintlify generate .
If your documentation is in a subdirectory:
npx speak-mintlify generate ./docs
Use --dry-run to preview what changes will be made before generating:
npx speak-mintlify generate . --dry-run
6

Verify the results

Check your MDX files to see the injected audio components. You should see something like:
<AudioTranscript
  voices={[
    { name: "E-girl", url: "https://your-cdn.com/audio/abc123.mp3" },
    { name: "Adrian", url: "https://your-cdn.com/audio/def456.mp3" }
  ]}
/>
Preview your documentation locally to test the audio playback.

​
Next steps

Installation

Learn about different installation options and requirements

Configuration

Explore advanced configuration options for voices, S3, and components

CI/CD Integration

Automate audio generation with GitHub Actions or other CI/CD tools

Commands

See all available commands and options

​
Common issues

Verify your S3 credentials in .env are correct and that your bucket has the proper permissions. Test with --verbose flag to see detailed error messages.
Make sure the component import path in speaker-config.yaml matches your actual component location. The component will be automatically injected at the top of each MDX file.
This usually means the hash tracking isn’t working properly. Check that you have write permissions in your documentation directory for the hash cache file.

Build docs developers (and LLMs) love

Get started for freeTalk to us