Search Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Search Implementation for the CircleCI documentation site provides a robust, interactive interface for users to discover content across various components and versions. It is primarily powered by Algolia for the main documentation site, while maintaining a fallback or legacy implementation using Lunr.js for specific static contexts like the API v1 documentation.
The system is designed to handle multi-repository documentation, allowing users to filter results by specific documentation "components" (e.g., Guides, Server Admin, Orbs). It features a responsive design that adapts its UI behavior between desktop and mobile views, integrating directly into the site's header and navigation panels.
Sources: ARCHITECTURE.md:88-91, ui/src/js/07-search.js:1-15, api-v1/index.html:619-635
Architecture and Core Components
The search architecture is split between client-side UI logic and external search indexing services. The documentation site is generated by Antora, which provides the underlying structure that the search scripts hook into.
Algolia Integration
The primary search engine uses the Algolia Search API. The implementation utilizes the algoliasearch client to communicate with the circleci-docs index.
| Component | Value / Description |
|---|---|
| App ID | U0RXNGRK45 |
| Search-Only API Key | acd02091c5079d698a0637ca692ebe07 |
| Index Name | circleci-docs |
| Debounce Delay | 300ms |
| Min Query Length | 2 characters |
Sources: ui/src/js/07-search.js:7-14, TECHNICAL_REFERENCE.md:204-206
Frontend UI Logic
The frontend logic, located in ui/src/js/07-search.js, manages DOM references for both desktop and mobile search interfaces. It handles state for queries, pagination, and "path counts" (facets) which represent different documentation components.
The flow diagram above illustrates the search trigger logic from user input to final UI rendering.
Sources: ui/src/js/07-search.js:82-108, ui/src/js/07-search.js:476-515
Data Flow and Search Execution
When a user interacts with the search input, the system executes an asynchronous search against the Algolia index.
Search Execution Logic
The search() function is the central coordinator for data retrieval. It requests specific attributes and highlights relevant terms.
- Hits Per Page: 10
- Attributes Retrieved:
title,url,relUrl,path,content,component,version. - Highlighting: Uses
<strong class="font-bold">tags for match visualization. - Faceting: Uses the
componentfacet to categorize results.
Sources: ui/src/js/07-search.js:82-108
Pagination and Faceting
The implementation features a custom pagination system that supports visible page limits (5 on desktop, 3 on mobile). Faceting (referred to as "Paths" in the code) allows users to filter results by documentation component and version.
The sequence diagram shows the interaction between the user, the local search controller, and the Algolia backend.
Sources: ui/src/js/07-search.js:112-167, ui/src/js/07-search.js:321-360
Responsive Implementation
The search implementation strictly differentiates between Desktop and Mobile environments to ensure usability.
Mobile vs. Desktop UI
| Feature | Desktop View | Mobile View |
|---|---|---|
| Container | Header results container | Navigation panel (data-page-navigation) |
| Trigger | Header input field | Mobile search input in nav panel |
| Max Pages | 5 visible pages | 3 visible pages |
| Layout | Full overlay via h-dvh | Integrated into side-nav, hides regular nav |
| Breakpoint | >= 768px | < 768px |
Sources: ui/src/js/07-search.js:14-16, ui/src/js/07-search.js:452-472, ui/src/js/07-search.js:517-533
Legacy Lunr.js Implementation
For standalone contexts like the API v1 documentation, a secondary search implementation using Lunr.js is utilized. This version performs client-side indexing of the document's headers (h1, h2) and associated text blocks.
Lunr Indexing Process
The script scans the page for headers and populates a Lunr index with a boosted score for titles.
index = lunr(function () {
this.ref('id');
this.field('title', { boost: 10 });
this.field('body');
// ... configuration ...
$('h1, h2').each(function () {
// Add title and following body text to index
});
});
Sources: api-v1/index.html:619-635
Build and Maintenance
The search functionality is integrated into the Gulp-based build pipeline. While the UI logic is bundled during the build:ui task, the search index content depends on the Antora site generation.
- Build Task:
gulp build:uibundlesui/src/js/07-search.jsinto the site's main JavaScript. - Environment Variables:
ALGOLIA_APP_ID,ALGOLIA_API_KEY, andALGOLIA_INDEX_NAMEare configurable via environment variables during the build process.
Sources: DEVELOPMENT.md:126-128, TECHNICAL_REFERENCE.md:204-206
The Search Implementation serves as a critical bridge between the distributed nature of the documentation components and the user's need for a centralized discovery mechanism, leveraging modern cloud search for the main site and client-side indexing for static references.