# Integrate Search

> 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.

- Skill: `pingcap/integrate-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add pingcap/integrate-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pingcap/integrate-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: pingcap (https://skillmd.com/u/pingcap)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pingcap/integrate-search

---


# 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