Installation Guide

This guide will walk you through setting up Mixedbread Search in your Astro Starlight documentation site.

Prerequisites

Before you begin, you’ll need:

• Node.js version 18 or higher
• Mixedbread Account - Sign up for free
• Mixedbread API Key - Get yours from the Mixedbread Dashboard
• Store ID - Create a store for your documentation

1. Clone the Repository

git clone https://github.com/mixedbread-ai/mixedbread-starlight.git
cd mixedbread-starlight

2. Install Dependencies

pnpm install

3. Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Add your Mixedbread credentials:

MXBAI_API_KEY=your_api_key_here
MXBAI_STORE_ID=your_store_id_here

Where to Find Your Credentials

1. API Key: Go to Mixedbread Dashboard → API Keys
2. Store ID: Go to Stores → Select your store → Copy the Store ID

Security Warning

Never commit your .env file to version control! The .gitignore file already excludes it.

4. Sync Your Documentation

First, update the sync commands in package.json to use your store name:

{
  "scripts": {
    "docs:sync": "mxbai store sync \"mixedbread-starlight\" \"./src/content/**/*.mdx\" \"./src/content/**/*.md\"  --yes --strategy fast",
    "docs:sync:dry-run": "mxbai store sync \"mixedbread-starlight\" \"./src/content/**/*.mdx\" \"./src/content/**/*.md\" --dry-run"
  }
}

Replace "mixedbread-starlight" with your actual Mixedbread store name (the same one you created and added to your .env file).

Now sync your documentation to Mixedbread store:

pnpm docs:sync

To preview changes before syncing:

pnpm docs:sync:dry-run

Keep Search Fresh

Re-run pnpm docs:sync whenever you update your documentation to keep the search index up-to-date.

5. Start Development Server

pnpm dev

Integrating Into an Existing Project

If you want to add Mixedbread Search to an existing Starlight site instead of cloning this repository:

1. Copy the Plugin

Copy the plugins/starlight-mixedbread directory to your project:

cp -r plugins/starlight-mixedbread your-project/plugins/

2. Install Dependencies

Add the required dependencies to your project:

pnpm add @mixedbread/sdk github-slugger remove-markdown
pnpm add -D @mixedbread/cli

Add Astro React integration:

pnpm astro add react

3. Configure Environment Variables

Add your Mixedbread credentials to the .env file:

MXBAI_API_KEY=your_api_key_here
MXBAI_STORE_ID=your_store_id_here

Security Warning

Add .env to your .gitignore file to prevent committing secrets:

.gitignore

.env

4. Update Astro Config

Update your astro.config.mjs:

// @ts-check
import { defineConfig, envField } from 'astro/config';
import starlight from '@astrojs/starlight';
import react from '@astrojs/react';
import { starlightMixedbread } from './plugins/starlight-mixedbread/plugin';

export default defineConfig({
  env: {
    schema: {
      MXBAI_API_KEY: envField.string({ context: 'server', access: 'secret' }),
      MXBAI_STORE_ID: envField.string({ context: 'server', access: 'secret' }),
    },
  },
  integrations: [
    react(),
    starlight({
      title: 'Your Docs',
      plugins: [
        starlightMixedbread({
          apiKey: process.env.MXBAI_API_KEY ?? '',
          storeId: process.env.MXBAI_STORE_ID ?? '',
          maxResults: 8,
        }),
      ],
    }),
  ],
});

5. Create the API Route

Create src/pages/api/search.ts with the search endpoint (copy from this repository’s file).

Adjust Content Path Mapping

If your content is in a different directory structure (not /src/content/docs/), update the filePathToHref function in search.ts:

function filePathToHref(filePath: string): string {
  // Extract the path after /src/content/docs/
  const match = filePath.match(/\/src\/content\/docs\/(.+)$/);
  if (!match) return "/";
  let href = match[1];
  href = href.replace(/\.(md|mdx)$/, "");
  href = href.replace(/^index$/, "");
  return `/${href}`;
}

For example, if your docs are in /docs/content/, change the regex to:

const match = filePath.match(/\/docs\/content\/(.+)$/);

6. Add Sync Commands

Add sync commands to your package.json:

{
  "scripts": {
    "docs:sync": "mxbai store sync \"your-store-name\" \"./src/content/**/*.mdx\" \"./src/content/**/*.md\" --yes --strategy fast",
    "docs:sync:dry-run": "mxbai store sync \"your-store-name\" \"./src/content/**/*.mdx\" \"./src/content/**/*.md\" --dry-run"
  }
}

Replace "your-store-name" with your actual Mixedbread store name.

Adjust Content Path

Update the glob patterns (./src/content/**/*.mdx) to match your documentation structure if it differs from the default Starlight setup.

7. Sync Your Documentation

Sync your documentation to Mixedbread store:

pnpm docs:sync

To preview changes before syncing:

pnpm docs:sync:dry-run

Keep Search Fresh

Re-run pnpm docs:sync whenever you update your documentation to keep the search index up-to-date.

8. Test the Integration

Start your development server:

pnpm dev

Press ⌘K (Mac) or Ctrl+K (Windows/Linux) to open the search modal and test the search functionality.

Optional: Automate Documentation Sync

You can automate documentation syncing with GitHub Actions. Create .github/workflows/sync-docs.yml:

name: Sync docs to Mixedbread Store

on:
  workflow_dispatch:
  push:
    branches: [main]
    paths:
      - src/content/**/*.md
      - src/content/**/*.mdx

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  sync:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install Mixedbread CLI
        run: npm i -g @mixedbread/cli

      - name: Sync store
        shell: bash
        env:
          MXBAI_API_KEY: ${{ secrets.MXBAI_API_KEY }}
          MXBAI_STORE_ID: ${{ secrets.MXBAI_STORE_ID }}
        run: mxbai store sync "${MXBAI_STORE_ID}" "./src/content/**/*.mdx" "./src/content/**/*.md" --yes --strategy fast

Add MXBAI_API_KEY and MXBAI_STORE_ID to your GitHub repository secrets (Settings → Secrets and variables → Actions).

Adjust File Paths

If your documentation is in a different directory, update both the trigger paths and sync command:

# Update trigger paths (what files trigger the workflow)
paths:
  - docs/content/**/*.md
  - docs/content/**/*.mdx

# Update sync command (what files get synced)
run: mxbai store sync "${MXBAI_STORE_ID}" "./docs/content/**/*.mdx" "./docs/content/**/*.md" --yes --strategy fast

Make sure these paths match your content structure and the paths in your package.json sync commands.

Monorepo Setup

If your Astro project is in a subdirectory (e.g., monorepo), use working-directory for the sync step:

name: Sync docs to Mixedbread Store

on:
  workflow_dispatch:
  push:
    branches: [main]
    paths:
      - docs/src/content/**/*.md        # Trigger when docs change
      - docs/src/content/**/*.mdx

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install Mixedbread CLI
        run: npm i -g @mixedbread/cli

      - name: Sync store
        working-directory: ./docs    # Set working directory to docs folder
        shell: bash
        env:
          MXBAI_API_KEY: ${{ secrets.MXBAI_API_KEY }}
          MXBAI_STORE_ID: ${{ secrets.MXBAI_STORE_ID }}
        run: mxbai store sync "${MXBAI_STORE_ID}" "./src/content/**/*.mdx" "./src/content/**/*.md" --yes --strategy fast

The working-directory ensures the CLI runs from the correct subdirectory.

Troubleshooting

1. Check API credentials: Verify MXBAI_API_KEY and MXBAI_STORE_ID are set
2. Check Store ID: Double-check your store identifier
3. Sync your content: Run pnpm docs:sync to upload your documentation
4. Verify build: Run pnpm check for type errors

Search not working?

Make sure:

• The plugin is properly configured in astro.config.mjs
• React integration is enabled
• No other components override the Search component
• MXBAI_API_KEY and MXBAI_STORE_ID are set with correct API key and Store ID
• You’ve synced your docs with pnpm docs:sync

Next Steps

• Configure the plugin to customize search behavior

Need Help?

• Open an issue
• Join the Mixedbread Discord