Typesense Search Setup Guide

Why Typesense?

Typesense is an excellent choice for your documentation search needs:

✅ Advantages over Current Plugin

Feature	Current Plugin	Typesense
Grouping/Filtering	❌ Not supported	✅ Built-in faceting
Rich Previews	❌ Limited	✅ Full control
Descriptions	❌ Not displayed	✅ Customizable
Typo Tolerance	⚠️ Basic	✅ Advanced
Relevance Tuning	❌ No	✅ Highly configurable
Semantic Search	❌ No	✅ Vector search (v0.25.1+)
Cost	Free	Free (self-hosted) or ~$0.03/hr (cloud)

✅ Advantages over Algolia

Feature	Algolia	Typesense
Cost	Free (with limits) or $$$	Free (self-hosted) or $
Open Source	❌ No	✅ Yes
Self-hosting	❌ No	✅ Yes
Control	Limited	Full control
Application Process	Required (~1 week)	No approval needed
Setup Time	1 week+	~1-2 hours

Setup Options

Option A: Typesense Cloud (Recommended for Start)

Pros: Easy, managed, fast setup Cons: Small monthly cost (~$20-40/month for small sites) Time: 1-2 hours

Option B: Self-Hosted

Pros: Free, full control Cons: Need to manage infrastructure Time: 2-3 hours

Quick Start Guide

Step 1: Choose Hosting

Option A: Typesense Cloud

1. Go to https://cloud.typesense.org/
2. Sign up for an account
3. Create a new cluster (starts at $0.03/hour)
4. Note your:
   • Host URL (e.g., xxx.a1.typesense.net)
   • Port (usually 443)
   • API Key

Option B: Self-Host with Docker

# Create docker-compose.yml
docker-compose up -d

# Or use their quick install script
curl -O https://dl.typesense.org/releases/0.25.1/typesense-server-0.25.1-linux-amd64.tar.gz
tar -xzf typesense-server-0.25.1-linux-amd64.tar.gz
./typesense-server --data-dir=/tmp/data --api-key=xyz

Step 2: Install Dependencies

npm install docusaurus-theme-search-typesense@next --save
npm install typesense@latest --save-dev

Step 3: Update Configuration

Edit docusaurus.config.ts:

export default {
  // ...other config

  // REMOVE the old search plugin
  // plugins: [
  //   [require.resolve("@easyops-cn/docusaurus-search-local"), { ... }],
  // ],

  // ADD Typesense theme
  themes: [
    [
      require.resolve("docusaurus-theme-search-typesense"),
      {
        // Options here
      }
    ]
  ],

  themeConfig: {
    // ...other theme config

    typesense: {
      // Replace with your Typesense config
      typesenseCollectionName: 'mambu-docs', // Name you'll give your index

      typesenseServerConfig: {
        nodes: [
          {
            host: 'xxx.a1.typesense.net', // Your Typesense host
            port: 443,
            protocol: 'https',
          },
        ],
        apiKey: 'your-search-only-api-key', // Search-only key (safe for frontend)
      },

      // Optional: Customize search behavior
      typesenseSearchParameters: {
        query_by: 'title,content,description',
        query_by_weights: '3,2,1', // Title most important
        num_typos: 2,
        typo_tokens_threshold: 1,
      },

      // Optional: Customize the search modal
      contextualSearch: true,
    },
  },
};

Step 4: Set Up Scraper

The scraper indexes your documentation into Typesense.

Create typesense-scraper-config.json:

{
  "index_name": "mambu-docs",
  "start_urls": [
    {
      "url": "https://docs.mambu.com/docs/",
      "selectors_key": "docs",
      "tags": ["docs"]
    },
    {
      "url": "https://docs.mambu.com/api/api-v2/",
      "selectors_key": "api-v2",
      "tags": ["api-v2"]
    },
    {
      "url": "https://docs.mambu.com/api/api-v1/",
      "selectors_key": "api-v1",
      "tags": ["api-v1"]
    }
  ],
  "selectors": {
    "default": {
      "lvl0": {
        "selector": ".menu__link--sublist.menu__link--active",
        "defaultValue": "Documentation"
      },
      "lvl1": "article h1",
      "lvl2": "article h2",
      "lvl3": "article h3",
      "lvl4": "article h4",
      "text": "article p, article li",
      "description": "meta[name='description']"
    },
    "docs": {
      "lvl0": {
        "selector": ".menu__link--sublist.menu__link--active",
        "defaultValue": "User Guide"
      },
      "lvl1": "article h1",
      "lvl2": "article h2",
      "lvl3": "article h3",
      "text": "article p, article li",
      "description": "meta[name='description']"
    },
    "api-v2": {
      "lvl0": {
        "selector": "",
        "defaultValue": "API v2 Reference"
      },
      "lvl1": "article h1",
      "lvl2": "article h2",
      "text": "article p, article li",
      "description": "meta[name='description']"
    },
    "api-v1": {
      "lvl0": {
        "selector": "",
        "defaultValue": "API v1 Reference"
      },
      "lvl1": "article h1",
      "lvl2": "article h2",
      "text": "article p, article li",
      "description": "meta[name='description']"
    }
  },
  "strip_chars": " .,;:#",
  "custom_settings": {
    "attributesForFaceting": ["type", "lang", "language", "version", "tags"]
  }
}

Create .env file for scraper:

TYPESENSE_API_KEY=your-admin-api-key
TYPESENSE_HOST=xxx.a1.typesense.net
TYPESENSE_PORT=443
TYPESENSE_PROTOCOL=https

Run the scraper:

# Using Docker (recommended)
docker run -it --env-file=.env \
  -e "CONFIG=$(cat typesense-scraper-config.json)" \
  typesense/docsearch-scraper

Step 5: Test Search

1. Build your site: npm run build
2. Serve it: npm run serve
3. Open http://localhost:3000
4. Try searching - you should see the Typesense search modal

Customizing Search Results

Show Descriptions (Stripe-style)

The Typesense theme supports custom result templates. Create a custom component:

src/theme/SearchBar/Hit.tsx:

import React from 'react';

export default function Hit({ hit }) {
  return (
    <div className="typesense-hit">
      {/* Category/Type badge */}
      <div className="typesense-hit-category">
        {hit.tags && hit.tags.includes('api-v2') && '🟢 API v2'}
        {hit.tags && hit.tags.includes('api-v1') && '🔵 API v1'}
        {hit.tags && hit.tags.includes('docs') && '📖 User Guide'}
      </div>

      {/* Title */}
      <div className="typesense-hit-title">
        {hit._highlightResult?.title?.value || hit.title}
      </div>

      {/* Description */}
      {hit.description && (
        <div className="typesense-hit-description">
          {hit.description}
        </div>
      )}

      {/* Path */}
      <div className="typesense-hit-path">
        {hit.hierarchy?.lvl0} › {hit.hierarchy?.lvl1}
      </div>
    </div>
  );
}

Group Results by Type

Configure faceting in your scraper config:

{
  "custom_settings": {
    "attributesForFaceting": ["tags"],
    "searchableAttributes": ["title", "description", "content"],
    "attributesToHighlight": ["title", "description"]
  }
}

Then in your search config:

typesenseSearchParameters: {
  query_by: 'title,description,content',
  facet_by: 'tags',
  group_by: 'tags', // Groups results by tag
  group_limit: 3, // Show 3 results per group
}

Automation

GitHub Actions for Auto-Indexing

Create .github/workflows/index-search.yml:

name: Index Documentation

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * *' # Daily at midnight

jobs:
  index:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run Typesense Scraper
        uses: typesense/docsearch-scraper-action@v1
        with:
          config-file-path: typesense-scraper-config.json
        env:
          TYPESENSE_API_KEY: ${{ secrets.TYPESENSE_API_KEY }}
          TYPESENSE_HOST: ${{ secrets.TYPESENSE_HOST }}
          TYPESENSE_PORT: 443
          TYPESENSE_PROTOCOL: https

Cost Comparison

Typesense Cloud

• Small site (~1000 docs): ~$20-40/month
• Medium site (~10000 docs): ~$50-80/month
• Benefits: No maintenance, automatic scaling, 99.9% uptime

Self-Hosted

• Cost: Server costs only (~$5-20/month on DigitalOcean/Linode)
• Effort: Need to manage updates, backups, scaling

Algolia (for comparison)

• Free tier: 10k searches/month, 10k records
• Paid: Starts at $1/month per 1000 records + $0.50 per 1000 searches
• Typical docs site: $100-500/month

Migration Path

Phase 1: Setup (Week 1)

• Sign up for Typesense Cloud
• Configure scraper
• Run initial indexing
• Install plugin
• Test in development

Phase 2: Customization (Week 2)

• Add page descriptions
• Customize result templates
• Set up grouping/faceting
• Style search modal

Phase 3: Deploy (Week 3)

• Set up GitHub Actions
• Deploy to production
• Monitor performance
• Gather user feedback

Recommended Next Steps

1. Sign up for Typesense Cloud trial - Test it risk-free
2. Run the scraper locally - See how it indexes your docs
3. Install the plugin - Test search in development
4. Decide: If you like it, go to production. If not, revert easily.

Support & Resources

• Documentation: https://typesense.org/docs/guide/docsearch.html
• GitHub: https://github.com/typesense/docusaurus-theme-search-typesense
• Community: https://typesense.org/community
• Cloud Console: https://cloud.typesense.org/

Comparison Matrix

Feature	Current	Typesense	Algolia
Setup Time	✅ 0 min	⚠️ 2 hours	⚠️ 1 week
Cost	✅ Free	⚠️ ~$30/mo	⚠️ ~$200/mo
Grouping	❌ No	✅ Yes	✅ Yes
Descriptions	❌ Limited	✅ Full	✅ Full
Customization	⚠️ Limited	✅ Full	⚠️ Limited
Self-host	❌ No	✅ Yes	❌ No
Typo tolerance	⚠️ Basic	✅ Advanced	✅ Advanced
Analytics	❌ No	✅ Yes	✅ Yes
Support	⚠️ GitHub	✅ Slack + GitHub	✅ Email + Chat

My Recommendation

Start with Typesense Cloud trial:

1. Takes 1-2 hours to set up
2. Test it with your real docs
3. See if the results meet your needs
4. If yes → deploy to production
5. If no → can always switch to Algolia later

Why Typesense over Algolia for you:

• ✅ No approval process (start today)
• ✅ More cost-effective
• ✅ Full control over indexing
• ✅ Open source (can self-host later)
• ✅ Better for technical documentation (vector search, semantic matching)

Ready to try it? I can help you set it up step-by-step!