Fix overlapping search highlights for adjacent multi-word matches

[zenoachtig]

Night-shift draft — not ready to merge; prepared for Zeno to review in the morning.

Source: #published-docs-experience Slack thread where Nolann reported that searching maria db cloud renders MariaDB as two overlapping highlight pills (while mariadb cloud looks fine). Zeno diagnosed the cause in-thread; this implements that fix.

Overview

• HighlightQuery highlights each query word independently (matchString reduces the text word-by-word). A multi-word query whose words are contiguous in the result text — e.g. maria db inside MariaDB — produced two touching <span> matches. Because each highlight span carries -mx-0.5 (negative margin) and rounded-sm, adjacent spans overlap into a visually doubled/seamed pill.
• Fix: coalesce directly-adjacent matched parts into a single highlight span (coalesceAdjacentMatches). Non-adjacent matches (unmatched text between them) still render as separate highlights.
• The pure matching logic is moved to HighlightQuery.utils.ts so it can be unit-tested without pulling in the React JSX runtime (mirrors the existing filter.ts / filter.test.ts split). HighlightQuery.tsx now just imports matchString and renders.

Test

packages/gitbook/src/components/Search/HighlightQuery.utils.test.ts (bun test) — covers no-match, single-word match, the adjacent-coalesce regression (maria db cloud → one MariaDB pill + one Cloud pill), and non-adjacent matches staying separate. The coalesce case fails on main and passes with this change. All 4 pass locally.

For Zeno

• Judgment call: I merge on adjacency only (consecutive match parts), not on the raw query — so maria cloud against MariaDB is a cloud database still yields two separate pills, which is correct. Merged span's match value is the concatenation of the matched tokens; it's only used as a truthy styling flag, so the exact value doesn't matter downstream.
• Extraction: I split the pure logic into HighlightQuery.utils.ts. If you'd rather keep it inline in the .tsx, the test can instead import through the component — but then it needs the JSX runtime and doesn't run under bun test cleanly. Happy to fold it back if you prefer.
• Not verified in-browser in this environment (couldn't run the full dev server); the fix is verified at the unit level. Worth an eyeball on a real search dropdown before it leaves draft.
• Typecheck locally is blocked only by unbuilt internal packages (@gitbook/icons, @gitbook/embed, …) in the fresh container — no errors in the changed files. CI will confirm.

Changelog

• [Fix] Search results no longer render adjacent matched words from a multi-word query (e.g. "maria db" matching "MariaDB") as two overlapping highlight pills.

---

Generated by Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: d55764e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
gitbook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	18 changed, 2 ignored	Jul 20, 2026, 12:28 AM
customers-v2-vercel (Inspect)	⚠️ Changes detected (Review)	16 changed, 4 ignored	Jul 20, 2026, 12:28 AM
v2-cloudflare (Inspect)	✅ No changes detected	3 ignored	Jul 20, 2026, 12:29 AM
v2-vercel (Inspect)	⚠️ Changes detected (Review)	1 changed, 2 ignored	Jul 20, 2026, 12:28 AM