Feat/web 308 improve search on documentation website related tasks by niallobrien · Pull Request #376 · cloudsmith-io/cloudsmith-docs

niallobrien · 2026-03-31T10:37:42Z

Story

https://linear.app/cloudsmith/issue/WEB-308/improve-search-on-documentation-website-and-related-tasks

Description

This feature replaces the existing search feature with an Algolia-backed search implementation. This required changes to the existing Algolia docs index (Crawler config), the docs site and the website. See website PR.

I used the dev_DOCS index while building this feature, and used Algolia's duplicate feature to move the index records into Docs only after I had first tested my local instance of the website against the dev_DOCS index.
The Algolia index has already been updated and I've confirmed that these changes do not break the search results in production.

The frontend implementation was a little fiddly in places due to the design requirements and the tokens being used on the site (vs the DS). There is future work planned to align the docs site tokens with the product.
I brought the SearchDialog component over from the website codebase and adjusted accordingly. The main changes being the inline and compact variants, along with theming options, keyboard activation, http method badges (as on the current implementation) and alternative grouping/ranking compared to the website's implementation.

As much as I'd have loved for the two sites to share a common search package implementation here, the search result ordering & grouping is quite different between the two, and is already quite verbose in places, but this could potentially be tackled in a future story, especially if maintenance due to deviation becomes an issue. Future work will also include a light and dark mode, so I tried to somewhat account for this in advance.

Screenshots

Release plan

Update the Algolia Crawler config for production at go-live. Used the dev_DOCS Crawler config.
Merge website and docs changes.

Checklist

I have completed a design review if necessary.

… and improving anchor handling

…h hit categorization

…itle handling

… anchor title handling

… improve anchor fragment handling

…ndling and add tests

…cription segments

vercel · 2026-03-31T10:37:48Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cloudsmith-docs	Ready	Preview, Comment	Apr 3, 2026 3:48pm

… display

…s etc.

…port

…g and layout adjustments

…nd update Navbar usage

…le nav support

…JSON structure

Copilot

Pull request overview

Replaces the existing documentation search with an Algolia-backed implementation, while also updating related UI/layout components (navbar, homepage hero, quick nav) to support the new search experience and refreshed design.

Changes:

Implemented Algolia-powered search dialog (InstantSearch) with merged docs + marketing results, grouping, and keyboard navigation.
Updated navigation/layout (Navbar, QuickNav, Sidenav, AppShell) and introduced new shared UI pieces (Footer, BackgroundGrid, icons).
Adjusted homepage hero/content and supporting utilities/constants to align with the new UI.

Reviewed changes

Copilot reviewed 64 out of 66 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/util/url.js	Adds URL/path utilities used by navigation and search.
src/util/strings.js	Adds string helpers used for search grouping/labels.
src/lib/types.ts	Updates homepage content typing (Hero/buttons).
src/lib/search/types.ts	Removes snippet field from legacy search types.
src/lib/search/server.ts	Removes snippet generation from legacy server-side search.
src/lib/constants/quickNav.ts	Replaces content id with selector + ignored fragments set.
src/icons/svgs/Heart.tsx	Adds heart icon used in the new footer.
src/icons/svgs/External.tsx	Fixes SVG attribute casing for React.
src/icons/icon-registry.tsx	Registers the new heart icon.
src/content/homepage.json	Updates homepage hero content to match new hero layout.
src/components/WithQuickNav/WithQuicknav.tsx	Switches QuickNav hook-up to a data attribute selector.
src/components/WithQuickNav/WithQuicknav.module.css	Improves anchor scroll offset behavior.
src/components/Tag/Tag.tsx	Wraps tag content for improved visual centering.
src/components/Tag/Tag.module.css	Adds centering/layout styles for tag content.
src/components/Sidenav/Sidenav.tsx	Updates sidenav behavior and body class for layout styling.
src/components/Sidenav/Sidenav.module.css	Adjusts toggler sizing and transition behavior.
src/components/SearchDialog/utils/searchHitUtils.js	Adds hit normalization, dedupe, href normalization, and breadcrumb segment building.
src/components/SearchDialog/utils/searchGroupUtils.js	Adds grouping/sorting logic for mixed-source search results.
src/components/SearchDialog/utils/data.js	Adds filter/group definition data for search UI.
src/components/SearchDialog/types.ts	Adds typed models for Algolia hits/groups/filters.
src/components/SearchDialog/SearchTrigger/SearchTrigger.tsx	Introduces themed/variant search trigger component.
src/components/SearchDialog/SearchTrigger/SearchTrigger.module.css	Styles new search trigger (inline/compact + themes).
src/components/SearchDialog/SearchTrigger/index.ts	Barrel export for the new SearchTrigger.
src/components/SearchDialog/SearchTrigger.tsx	Removes previous trigger implementation.
src/components/SearchDialog/SearchTrigger.module.css	Removes previous trigger styles.
src/components/SearchDialog/SearchForm.tsx	Removes previous search input/hotkeys implementation.
src/components/SearchDialog/SearchForm.module.css	Removes previous search form styles.
src/components/SearchDialog/SearchDialogContent/SearchResults/SearchResults.tsx	Adds results rendering, grouping, and keyboard navigation behavior.
src/components/SearchDialog/SearchDialogContent/SearchResults/SearchResults.module.css	Styles results list, grouping headers, and empty/error states.
src/components/SearchDialog/SearchDialogContent/SearchResults/index.ts	Barrel export for SearchResults.
src/components/SearchDialog/SearchDialogContent/SearchFilters/SearchFilters.tsx	Adds group “filters” nav that scrolls to sections.
src/components/SearchDialog/SearchDialogContent/SearchFilters/SearchFilters.module.css	Styles search group navigation.
src/components/SearchDialog/SearchDialogContent/SearchFilters/index.ts	Barrel export for SearchFilters.
src/components/SearchDialog/SearchDialogContent/SearchDialogContent.tsx	Adds SearchBox + debounce queryHook + layout for filters/results.
src/components/SearchDialog/SearchDialogContent/SearchDialogContent.module.css	Styles dialog header/search input and results layout grid.
src/components/SearchDialog/SearchDialogContent/index.ts	Barrel export for SearchDialogContent.
src/components/SearchDialog/SearchDialog.tsx	Replaces legacy fuzzy/server search with Algolia InstantSearch + multi-index merge.
src/components/SearchDialog/SearchDialog.module.css	Updates dialog shell styling and adds light/dark theme variables.
src/components/SearchDialog/index.ts	Simplifies exports to just SearchDialog.
src/components/SearchDialog/FilterButtons.tsx	Removes legacy section filter buttons.
src/components/SearchDialog/FilterButtons.module.css	Removes legacy filter button styles.
src/components/QuickNav/useHeadingsObserver.ts	Updates observer scope to use selector instead of element id.
src/components/QuickNav/QuickNav.tsx	Updates QuickNav to use selector scope + adds hash scrolling behavior.
src/components/Navbar/Navbar.tsx	Updates navbar layout, adds SearchDialog variants, and revises mobile nav ordering.
src/components/Navbar/Navbar.module.css	Major navbar styling updates (new layout, mobile nav, sticky offsets).
src/components/index.ts	Exports new Footer component.
src/components/Illustrations/Grid.tsx	Adds reusable SVG grid illustration.
src/components/HomepageHero/HomepageHero.tsx	Reworks hero layout and embeds SearchDialog.
src/components/HomepageHero/HomepageHero.module.css	Updates hero styling and background grid tokenization.
src/components/Footer/index.ts	Adds footer barrel export.
src/components/Footer/Footer.tsx	Introduces new footer with nav + legal links.
src/components/Footer/Footer.module.css	Styles the new footer.
src/components/BackgroundGrid/index.ts	Adds BackgroundGrid barrel export.
src/components/BackgroundGrid/BackgroundGrid.tsx	Adds BackgroundGrid wrapper for vignette + illustration composition.
src/components/BackgroundGrid/BackgroundGrid.module.css	Styles BackgroundGrid layout and vignettes.
src/components/AppShell/AppShell.module.css	Adjusts secondary nav stickiness behavior at breakpoints.
src/components/ApiRequest/ApiRequest.tsx	Adds `data-api-method` attribute for request wrapper.
src/app/navigation.tsx	Minor import ordering cleanup.
src/app/layout.tsx	Adds Footer to the root layout.
src/app/(documentation)/design-system/page.module.css	Media query + hover style adjustments for icon wrapper.
src/app/_styles/variables.css	Adds grid-line token and updates navbar sizing variables.
src/app/_styles/global.css	Adds body var override when sidenav toggle class is present.
package.json	Adds Algolia + InstantSearch dependencies.
package-lock.json	Locks newly added Algolia/InstantSearch dependency tree.
.gitignore	Adds `.history` and normalizes docs/graph ignore formatting.
.env	Adds Algolia-related env vars (currently includes a committed key).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-03T15:17:18Z

.env

+NEXT_PUBLIC_ALGOLIA_APP_ID=
+NEXT_PUBLIC_ALGOLIA_API_KEY=77bed0e1d7c9a7b0572d1ffdb55b2be9 # this is only for development, a restricted key is used in production
+NEXT_PUBLIC_ALGOLIA_DOCS_INDEX=Docs
+NEXT_PUBLIC_ALGOLIA_INDEX=prod_WEBSITE
+# NEXT_PUBLIC_ALGOLIA_INDEX=dev_WEBSITE
+
+ALGOLIA_WRITE_KEY=


A public Algolia API key is committed in this tracked .env file (and it’s a NEXT_PUBLIC_* value, so it will be exposed to the browser). Even if restricted, committing keys in-repo increases the risk of accidental reuse/privilege expansion and makes rotation harder. Remove the key from version control (e.g., move to developer-local env files and provide a .env.example with placeholders) and rotate the exposed key.

This is a dev-only key. Will remove to be safe I guess.

Copilot · 2026-04-03T15:17:18Z

src/lib/types.ts

+export interface Hero {
  title: string;
  description: string;
-  buttons: Button[];
+  buttons: {
+    label: string;
+    href: string;
+    icon: IconName;
+  }[];


Hero.buttons is still required in the Hero/HomepageContent type, but src/content/homepage.json no longer contains hero.buttons. This forces consumers to lie with type assertions and can lead to runtime undefined values. Either make buttons optional (or default to an empty array in the content shape), or update the JSON to include "buttons": [] to match the type.

Copilot · 2026-04-03T15:17:18Z

src/components/SearchDialog/utils/searchHitUtils.js

+const normalizeComparableSearchValue = (value) => {
+  const normalizedValue = normalizeSearchValue(value);
+  if (!normalizedValue) return '';
+
+  return slugify(decodeURIComponent(normalizedValue).replace(/\+/g, ' '));
+};


normalizeComparableSearchValue calls decodeURIComponent without a try/catch. If Algolia returns a value containing malformed percent-encoding, this will throw and break the search UI. Consider reusing decodeSearchValue (which already guards) or wrapping this decodeURIComponent call in a try/catch with a safe fallback.

Copilot · 2026-04-03T15:17:19Z

src/components/QuickNav/QuickNav.tsx

+export const scrollToHashTarget = (hash = window.location.hash) => {
+  const normalizedHash = hash.replace(/^#/, '');
+  if (!normalizedHash) return false;
+
+  const targetId = decodeURIComponent(normalizedHash);
+  const target = document.getElementById(targetId);
+  if (!target) return false;
+
+  target.scrollIntoView({ block: 'start' });


scrollToHashTarget uses decodeURIComponent on the hash fragment without guarding against malformed percent-encoding. A malformed URL hash can throw here and break QuickNav rendering/behavior. Wrap the decode in try/catch (fall back to the raw fragment) before calling getElementById.

Copilot · 2026-04-03T15:17:19Z

src/components/SearchDialog/SearchDialogContent/SearchDialogContent.tsx

+  const queryHook = useCallback((nextQuery: string, search: (value: string) => void) => {
+    const trimmed = nextQuery.trim();
+
+    if (trimmed.length === 0) {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+      search('');
+      return;
+    }
+
+    if (trimmed.length < 2) return;
+    if (debounceRef.current) window.clearTimeout(debounceRef.current);
+
+    debounceRef.current = window.setTimeout(() => {
+      search(nextQuery);
+    }, 150);


In queryHook, queries with 1 character return early without calling search('') or otherwise clearing results. This can leave stale results visible while the input shows a new (too-short) query. Consider explicitly clearing/refining to an empty query when trimmed.length < 2, or hiding results until the minimum length is reached.

Copilot · 2026-04-03T15:17:19Z

src/components/SearchDialog/SearchDialog.tsx

+// Guard against missing Algolia credentials to prevent breaking the navbar
+const hasAlgoliaCredentials = Boolean(algoliaAppId && algoliaApiKey);


hasAlgoliaCredentials only checks app ID + API key, but InstantSearchNext is still passed indexName={algoliaIndexName} which may be undefined/empty (and createSearchClient falls back to an empty index name). This can lead to runtime errors if NEXT_PUBLIC_ALGOLIA_INDEX isn’t configured. Consider including algoliaIndexName in the guard (or providing a safe default / clearer failure mode).

Suggested change

// Guard against missing Algolia credentials to prevent breaking the navbar

const hasAlgoliaCredentials = Boolean(algoliaAppId && algoliaApiKey);

// Guard against missing Algolia configuration to prevent breaking the navbar.

const hasAlgoliaCredentials = Boolean(

algoliaAppId && algoliaApiKey && algoliaIndexName,

);

Copilot · 2026-04-03T15:17:19Z

src/components/SearchDialog/utils/searchGroupUtils.js

+import { slugify, titleCase } from '../../../util/strings';
+import { isExternalHref } from '../../../util/url';
+import { filtersData } from './data';


This file imports util modules via a deep relative path (../../../util/...) while the rest of the SearchDialog code uses the @/util/... alias. Keeping imports consistent reduces churn if folders move and matches existing conventions in this area (e.g., searchHitUtils.js). Switch these imports to the @/util/... form for consistency.

Copilot · 2026-04-03T15:17:20Z

src/components/SearchDialog/SearchTrigger/SearchTrigger.tsx

+    <span className={styles.kbdHint}>
+      <kbd>
+        <span className={styles.kbdText}>Ctrl</span>
+      </kbd>
+      <kbd>
+        <span className={styles.kbdText}>K</span>
+      </kbd>
+    </span>


The keyboard shortcut hint is hard-coded to “Ctrl K”. On macOS this should typically display “⌘K”, and the previous implementation already derived the modifier key dynamically. Consider restoring OS-aware rendering for the modifier key (or hiding the hint on platforms where it’s not applicable).

…ration

niallobrien added 11 commits March 26, 2026 15:48

feat: initial commit of Algolia search integration

5737b57

fix: enhance search functionality and improve search result handling

ec5ff45

fix: improve state management in Sidenav component

c6c199c

fix: enhance search functionality by deduplicating merged search hits…

ee0863d

… and improving anchor handling

fix: enhance QuickNav component with hash scrolling and improve searc…

b112b0d

…h hit categorization

fix: enhance search functionality with improved decoding and anchor t…

92eaa66

…itle handling

fix: enhance search functionality by improving page display title and…

f18f80a

… anchor title handling

fix: refactor QuickNav component to use selector for content area and…

a02adb5

… improve anchor fragment handling

fix: enhance search functionality with improved page display title ha…

2a2c9aa

…ndling and add tests

fix: add website breadcrumb segment to search results and enhance des…

9c2d948

…cription segments

fix: enhance search results display by adding HTTP method tags

bd9a9ff

vercel bot deployed to Preview March 31, 2026 10:40 View deployment

niallobrien added 11 commits March 31, 2026 12:22

fix: improve alignment and centering for tag and search result method…

3e21235

… display

fix: updated search feature with added types, and homepage adjustment…

611780a

…s etc.

fix: enhance search dialog and trigger with theme support

d35875d

fix: enhance Navbar layout and improve search dialog styling

f074812

feat: add Footer component with styling and integrate into layout

8ed6219

feat: enhance SearchDialog and SearchTrigger with compact variant sup…

275a8a8

…port

feat: improve Navbar and SearchDialog components with enhanced stylin…

3a30c81

…g and layout adjustments

feat: improve Navbar and Sidenav components with improved styling

fc6f10d

feat: enhance SearchDialog component with keyboard shortcut support a…

b144ad6

…nd update Navbar usage

fix: improve Navbar and Footer components with improved layout & mobi…

fe793d6

…le nav support

fix: improves types for Hero component buttons and resolves build issue

3a1d00a

vercel bot deployed to Preview April 2, 2026 17:11 View deployment

fix: updates navbar height for tablet screens and cleans up homepage …

bd2173d

…JSON structure

vercel bot deployed to Preview April 2, 2026 17:53 View deployment

fix: update search test to check for undefined content property

409bf63

niallobrien marked this pull request as ready for review April 3, 2026 15:12

Copilot AI review requested due to automatic review settings April 3, 2026 15:12

Copilot started reviewing on behalf of niallobrien April 3, 2026 15:13 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

fix: remove development-only Algolia API key from environment configu…

12d61c1

…ration

vercel bot deployed to Preview April 3, 2026 15:48 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat/web 308 improve search on documentation website related tasks#376

Feat/web 308 improve search on documentation website related tasks#376
niallobrien wants to merge 25 commits intomainfrom
feat/web-308-improve-search-on-documentation-website-related-tasks

niallobrien commented Mar 31, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

niallobrien Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

		// Guard against missing Algolia credentials to prevent breaking the navbar
		const hasAlgoliaCredentials = Boolean(algoliaAppId && algoliaApiKey);

Conversation

niallobrien commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Story

Description

Screenshots

Release plan

Checklist

Uh oh!

vercel bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

niallobrien Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

niallobrien commented Mar 31, 2026 •

edited

Loading

vercel bot commented Mar 31, 2026 •

edited

Loading