Quickstart

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.)

Install speak-mintlify

Install speak-mintlify in your documentation repository:

npm install speak-mintlify

yarn add speak-mintlify

pnpm add speak-mintlify

You can also use npx speak-mintlify without installing to run commands directly

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.

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.

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" }
  ]}
/>

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

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

Audio files not uploading to S3

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.

Component not appearing in MDX files

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.

Audio regenerating every time

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.

Get Started

Configuration

Commands

Guides

Reference

Prerequisites

Next steps

Installation

Configuration

CI/CD Integration

Commands

Common issues

​Prerequisites

​Next steps

Installation

Configuration

CI/CD Integration

Commands

​Common issues

Prerequisites

Next steps

Common issues