Skip to main content

Algolia Search Integration

This documentation site uses Algolia DocSearch to provide powerful, fast search functionality with AI-powered conversational search via Ask AI.

Features​

  • Fast, relevant search - Algolia's search engine returns results in milliseconds
  • Ask AI - Conversational search powered by AI for natural language queries
  • Contextual filtering - Results automatically filtered by section and category
  • Keyboard shortcuts - Press Ctrl+K (or Cmd+K on Mac) to open search
  • API-based indexing - Content is pushed via API, bypassing the need for crawlers
  • Dark mode support - Search UI matches the site's theme

How It Works​

Indexing Process​

  1. Build Time: When npm run build completes, the postbuild script runs automatically
  2. Content Extraction: The script reads all HTML files from the build directory
  3. Data Preparation: Extracts titles, content, headings, and metadata
  4. API Push: Sends records to Algolia via the Admin API
  5. Index Update: Algolia replaces all records with the new content

This approach works even though the production site is protected by Cloudflare Access, since we're pushing content directly via API rather than relying on a crawler.

Configuration​

Environment Variables​

The following environment variables are required:

# Algolia Search Configuration
ALGOLIA_APP_ID=OMNGM7GBAZ
ALGOLIA_SEARCH_API_KEY=f14b4b7b1389d1c28f199ed742b2b120  # Public, safe to commit
ALGOLIA_ADMIN_API_KEY=5d5aeac178410c1c738f1a1e2957aa18  # Secret, never commit
ALGOLIA_INDEX_NAME=PacingDocs1Index
ALGOLIA_ASSISTANT_ID=uS0228m9DgOG

Local Development: Add these to .env in the workspace root (gitignored)

Production: Add these to Cloudflare Pages environment variables in the dashboard

Docusaurus Config​

The Algolia configuration in docusaurus.config.ts:

algolia: {
  appId: 'OMNGM7GBAZ',
  apiKey: 'f14b4b7b1389d1c28f199ed742b2b120', // Public search-only key
  indexName: 'PacingDocs1Index',
  contextualSearch: true,
  askAi: {
    assistantId: 'uS0228m9DgOG',
    indexName: 'PacingDocs1Index',
    apiKey: 'f14b4b7b1389d1c28f199ed742b2b120',
    appId: 'OMNGM7GBAZ',
    suggestedQuestions: true,
  },
  searchPagePath: 'search',
},
  1. Open search: Click the search bar in the navbar or press Ctrl+K (Windows/Linux) or Cmd+K (Mac)
  2. Type your query: Start typing what you're looking for
  3. Navigate results: Use arrow keys to navigate, Enter to open, Esc to close
  4. View full results: Click "See all X results" to view the dedicated search page

Ask AI​

  1. Open search: Use the search bar or keyboard shortcut
  2. Switch to Ask AI: Click the "Ask AI" tab in the search modal
  3. Ask a question: Type a natural language question (e.g., "How do I set up tracking for a new client?")
  4. Get AI answer: The AI will provide a contextual answer based on the documentation
  5. View sources: Click on suggested pages to read the full documentation

Search Tips​

  • Be specific: "GTM server-side tracking" is better than "tracking"
  • Use keywords: Search for tool names, feature names, or key concepts
  • Try variations: If you don't find what you need, try alternative terms
  • Check filters: Results are automatically filtered by section, but you can adjust this

Manual Indexing​

To manually trigger indexing without rebuilding:

cd docusaurus
npm run index-algolia

This is useful when:

  • Testing indexing changes
  • The automatic postbuild hook failed
  • You want to verify content is indexed correctly

Troubleshooting​

Search Returns No Results​

Possible causes:

  • Content hasn't been indexed yet (wait for first build/deploy)
  • Index was cleared and needs repopulating
  • Search query is too specific or contains typos

Solution:

  1. Check the Algolia dashboard to verify records exist
  2. Trigger a manual indexing: npm run index-algolia
  3. Verify environment variables are set correctly

Ask AI Not Working​

Possible causes:

  • Assistant ID is incorrect or missing
  • Algolia Ask AI feature not enabled in dashboard
  • Network/API issues

Solution:

  1. Verify ALGOLIA_ASSISTANT_ID is set correctly
  2. Check Algolia dashboard that Ask AI is enabled
  3. Check browser console for errors

Indexing Fails in Production​

Possible causes:

  • ALGOLIA_ADMIN_API_KEY not set in Cloudflare Pages
  • Network issues during build
  • Build directory not found

Solution:

  1. Check Cloudflare Pages environment variables
  2. Review build logs for specific error messages
  3. Ensure postbuild script is running

Stale Search Results​

Possible causes:

  • Recent changes haven't been deployed yet
  • Cache needs clearing
  • Old records still in index

Solution:

  1. Wait for deployment to complete
  2. Clear browser cache
  3. Trigger manual reindex if needed

Index Configuration​

The indexing script configures the Algolia index with:

{
  searchableAttributes: [
    'title',          // Page title (highest priority)
    'hierarchy.lvl0', // Section (e.g., "Guides", "Tools")
    'hierarchy.lvl1', // Category (e.g., "Marketing", "Website")
    'hierarchy.lvl2', // Subcategory
    'content',        // Page content (lowest priority)
  ],
  attributesForFaceting: [
    'type',           // docs vs blog
    'hierarchy.lvl0', // Section filtering
  ],
  customRanking: [
    'desc(type)',     // Docs ranked higher than blog
  ],
}

This ensures:

  • Titles match first, then headings, then content
  • Results are relevant to the current section
  • Documentation pages rank higher than blog posts

Security Notes​

  • Search API Key is safe to commit - it's read-only and public
  • Admin API Key is secret - never commit it, only in environment variables
  • Keys are stored securely in Cloudflare Pages (encrypted)
  • .env file is gitignored by default

Performance​

  • Index size: ~50-100 records per build (depends on content)
  • Search speed: < 50ms average response time
  • Indexing time: ~5-10 seconds during build
  • API calls: 1 index replacement per build (~$0.00 cost)

Implementation Details​

Files involved:

  • docusaurus.config.ts - Algolia configuration
  • scripts/index-algolia.cjs - Indexing script
  • package.json - Postbuild hook
  • src/css/custom.css - Search styling
  • .env - Environment variables (local)

Last updated: 2026-01-07