Skip to main content

Algolia Search Integration

This documentation site uses Algolia DocSearch for fast keyword search, plus Ask AI for conversational answers.

Features​

  • Fast, relevant search: Algolia returns results in milliseconds.
  • Ask AI: Conversational answers based on indexed documentation content.
  • Contextual filtering: Results are filtered by docs metadata.
  • Keyboard shortcuts: Press Ctrl+K (or Cmd+K on macOS) to open search.
  • API-based indexing: Content is pushed directly via API instead of crawler-based indexing.
  • Dark mode support: Search UI follows site theme.

How It Works​

We maintain two Algolia indexes, each serving a different purpose:

IndexPurposeRecords
PacingDocs1IndexKeyword search with per-heading records and hierarchy~2,800
PacingDocs1Index-markdownAsk AI context with one full-page record per document~200

Indexing Process​

  1. Build time: npm run build triggers the postbuild hook, which runs index-algolia.cjs.
  2. Keyword index: Built HTML is split into heading-based records and pushed to PacingDocs1Index.
  3. Markdown index: The same HTML is converted into one full-page text record per page and pushed to PacingDocs1Index-markdown.
  4. Index settings: Applied during indexing, so manual dashboard reconfiguration is minimal.

This works even though production is protected by Cloudflare Access, because indexing uses API push from build output.

Why Two Indexes?​

The keyword index (PacingDocs1Index) is excellent for fast section-level retrieval.

The markdown index (PacingDocs1Index-markdown) provides whole-page context (up to 100 KB text per record), improving Ask AI answer quality.

Configuration​

Environment Variables​

Use environment variables for values that should vary by environment, especially secrets:

# Algolia configuration
ALGOLIA_APP_ID=your-app-id
ALGOLIA_SEARCH_API_KEY=your-search-only-key
ALGOLIA_ADMIN_API_KEY=your-admin-api-key
ALGOLIA_INDEX_NAME=PacingDocs1Index

Security notes:

  • ALGOLIA_SEARCH_API_KEY is public/search-only.
  • ALGOLIA_ADMIN_API_KEY is secret and must never be committed.

Assistant ID note:

  • Ask AI assistantId is currently set in docusaurus.config.ts.
  • If you want env-based configuration, update code to read ALGOLIA_ASSISTANT_ID explicitly.

Local development: Store variables in .env at the docusaurus/ root (gitignored).

Production: Set variables in Cloudflare Pages environment settings.

Docusaurus Config​

Current config in docusaurus.config.ts:

algolia: {
  appId: 'OMNGM7GBAZ',
  apiKey: 'your-search-only-key',
  indexName: 'PacingDocs1Index',
  contextualSearch: true,
  searchParameters: { hitsPerPage: 20 },
  askAi: {
    indexName: 'PacingDocs1Index-markdown',
    apiKey: 'your-search-only-key',
    appId: 'OMNGM7GBAZ',
    assistantId: 'your-assistant-id',
  },
  searchPagePath: 'search',
},
  1. Open search via the navbar or Ctrl+K / Cmd+K.
  2. Type your query.
  3. Navigate with arrow keys, press Enter to open.
  4. Click "See all results" for the dedicated search page.

Ask AI​

  1. Open search.
  2. Switch to the Ask AI tab.
  3. Ask a natural-language question.
  4. Review the answer and open cited source pages.

Search Tips​

  • Use specific phrases (GTM server-side tracking instead of tracking).
  • Try alternate terms if no good results appear.
  • Use section context and filters when narrowing results.

Manual Indexing​

To re-run indexing without a full rebuild:

cd docusaurus
npm run index-algolia

Useful when:

  • testing indexing changes
  • recovering from a failed postbuild index step
  • validating fresh content in both indexes

Troubleshooting​

Search Returns No Results​

Possible causes:

  • no records indexed yet
  • index was cleared
  • query too narrow

Solution:

  1. Confirm records exist in Algolia.
  2. Run npm run index-algolia.
  3. Verify environment variables.

Ask AI Not Working​

Possible causes:

  • markdown index is empty
  • wrong Ask AI assistant configuration
  • API/network failures

Solution:

  1. Run npm run index-algolia to repopulate both indexes.
  2. Verify assistantId in docusaurus.config.ts.
  3. Confirm Ask AI is enabled in Algolia.
  4. Check browser console/network logs.

Indexing Fails in Production​

Possible causes:

  • missing ALGOLIA_ADMIN_API_KEY
  • transient network failure during build
  • build output not available

Solution:

  1. Check Cloudflare Pages environment variables.
  2. Review build logs.
  3. Confirm postbuild executes successfully.

Stale Search Results​

Possible causes:

  • latest deploy not completed
  • browser cache
  • stale index contents

Solution:

  1. Wait for deploy completion.
  2. Refresh with cache bypass.
  3. Trigger manual reindex if needed.

Index Configuration​

Keyword Index (PacingDocs1Index)​

Per-heading records with hierarchy fields (lvl0 to lvl3) and content-focused ranking.

{
  searchableAttributes: [
    'unordered(hierarchy.lvl0)',
    'unordered(hierarchy.lvl1)',
    'unordered(hierarchy.lvl2)',
    'unordered(hierarchy.lvl3)',
    'content',
  ],
  attributesForFaceting: [
    'filterOnly(type)',
    'filterOnly(lang)',
    'filterOnly(language)',
    'filterOnly(version)',
    'filterOnly(docusaurus_tag)',
  ],
}

Markdown Index (PacingDocs1Index-markdown)​

One full-text record per page for Ask AI context retrieval.

{
  searchableAttributes: ['title', 'heading', 'unordered(text)'],
  attributesForFaceting: [
    'filterOnly(lang)',
    'filterOnly(language)',
    'filterOnly(version)',
    'filterOnly(docusaurus_tag)',
    'filterOnly(type)',
  ],
  ignorePlurals: true,
  typoTolerance: false,
}

Security Notes​

  • Search keys are public/search-only by design.
  • Admin keys are secret and must be stored only in secure environment configuration.
  • Do not paste real credentials into docs examples.