integrate-search

name	integrate-search
description	Update onsite search behavior in website-docs when the task changes the search page, search box flows, Algolia client wiring, result categorization, external search fallbacks, or search-related routing. Edit the relevant Gatsby page creator, search template or components, and shared search utilities while keeping locale, category, and tracking behavior aligned.

Integrate Search

Overview

Use this skill for search experience changes in this repo. Search behavior spans Gatsby page creation, the search page template, UI components, Algolia wiring, category labeling, and external search fallbacks.

Workflow

1) Locate the affected search layer

Common files:

• gatsby/create-pages/create-search.ts
• src/templates/DocSearchTemplate.tsx
• src/components/Search/index.tsx
• src/components/Search/Results.tsx
• src/shared/utils/algolia.ts
• src/shared/utils/searchCategory.ts

Choose the correct layer before editing:

• Page route creation
• Search box interactions
• Result rendering and paging
• Category resolution
• Algolia client configuration

2) Preserve current locale and route assumptions

Search in this repo currently:

• creates /search/
• navigates to /search/?q=...
• uses gatsby-plugin-react-i18next helpers in UI
• mixes onsite search with Google or Bing fallbacks

If you change search route shape or category prefixes, review i18n routing and resolveSearchCategory().

3) Update Algolia and category logic carefully

When touching search data wiring:

• Keep GATSBY_ALGOLIA_APPLICATION_ID and GATSBY_ALGOLIA_API_KEY usage intact unless the task explicitly changes them
• Reuse normalizeSearchResultPath() and resolveSearchCategory() patterns
• Update translation keys if new labels or UI strings are introduced

When adding a new top-level docs section, search categorization may need updates.

4) Review tracking and external search behavior

src/components/Search/index.tsx includes GTM events and Google/Bing fallbacks. If you alter submit behavior, preserve or intentionally update:

• onsite vs external search selection
• query propagation to the search page
• GTM events

5) Validate

At minimum:

• Confirm the search route still resolves
• Confirm query string handling still works
• Confirm category chips still resolve correctly for representative URLs
• Run yarn build when feasible

Output Checklist

Report:

• Which search files changed
• Whether route, Algolia, category, or tracking behavior changed
• Any new translation keys or route-prefix dependencies
• Whether yarn build was run