Client-Side JavaScript
Relevant source files
The following files were used as context for generating this wiki page:
The Client-Side JavaScript in the CircleCI Docs project is a modular system designed to enhance the static documentation site with interactive features. It is a core part of the UI Bundle, which is built separately from the documentation content to maintain a clean separation of concerns. This JavaScript architecture supports functionalities such as navigation, search, interactive code blocks, and API documentation integration.
Sources: ARCHITECTURE.md:16-24, TECHNICAL_REFERENCE.md:144-149
JavaScript Architecture and Organization
The project employs a modular JavaScript architecture where functionality is divided into core modules, page-specific scripts, and third-party utilities. The source files are located within the ui/src/js/ directory and are bundled into a main site script.
Component Structure
The client-side logic is organized into three primary categories:
| Category | Description |
|---|---|
| Core Modules | Handles basic site-wide functionality like navigation and search integration. |
| Page-Specific Modules | Contains logic specific to certain page types or features (e.g., tabs, modals). |
| Utilities | Helper functions and third-party vendor scripts used across the site. |
Sources: TECHNICAL_REFERENCE.md:144-150
Build and Delivery Flow
The JavaScript is processed as part of the Gulp-based UI build pipeline. The final output is bundled and placed into the ui-bundle.zip, which Antora uses to assemble the final static site.
The diagram above illustrates how individual JavaScript modules are transformed through Gulp tasks into a production-ready bundle.
Sources: ARCHITECTURE.md:46-51, TECHNICAL_REFERENCE.md:141-143
Key Interactive Features
Interactive Content Components
The client-side scripts enable several interactive elements within the AsciiDoc-rendered pages:
- Tabs: Supported via the
@asciidoctor/tabsextension, allowing users to switch between different content views (e.g., different programming languages in code examples). - Search: Integration with Algolia to provide real-time search capabilities across the documentation.
- Navigation: Logic for handling the sidebar, breadcrumbs, and component explorer navigation.
Sources: DEVELOPMENT.md:105-115, TECHNICAL_REFERENCE.md:128-132, package.json:28
API Documentation Integration
Client-side JavaScript plays a critical role in the API documentation experience. While API v1 is static, API v2 utilizes sophisticated interactive features:
- Redocly Integration: Uses Redocly to transform OpenAPI specifications into an interactive, single-page application.
- Code Samples: Dynamically generates and displays code snippets for various languages (cURL, Node.js, Python, Go, Ruby) using
httpsnippet.
Sources: API_DOCS_INTEGRATION.md:9-19, package.json:25
This sequence diagram shows the interaction between the client-side JavaScript, search services, and the specialized API documentation engine.
Sources: TECHNICAL_REFERENCE.md:128-132, API_DOCS_INTEGRATION.md:48-55
Dependencies and Tools
The client-side ecosystem relies on several key packages and environment variables for configuration.
Core Dependencies
- @asciidoctor/tabs: Enables tabbed content panels.
- algoliasearch: Client for the Algolia search service.
- browser-sync: Used during development for live reloading and previewing UI changes.
Sources: package.json:22-30
Configuration via Environment Variables
The JavaScript behavior and integration points are often configured via environment variables during the build process:
| Variable | Usage |
|---|---|
ALGOLIA_APP_ID | Identity of the Algolia application for search. |
ALGOLIA_API_KEY | Public API key for performing searches. |
LIVERELOAD | Boolean to enable or disable browser live reloading in preview mode. |
SEGMENT_WRITE_KEY | Key used for client-side analytics tracking via Segment. |
Sources: TECHNICAL_REFERENCE.md:195-203
Development and Testing
Developers modifying client-side JavaScript use specific Gulp tasks to validate changes. The npm run preview:ui command starts a local server that watches for changes in ui/src/js/ and triggers automatic rebuilds. For production readiness, the scripts undergo bundling and minification to reduce the payload size.
Sources: DEVELOPMENT.md:43-55, TECHNICAL_REFERENCE.md:223-225
Conclusion
Client-side JavaScript in the CircleCI Docs project is a vital component that bridges the gap between static content and a dynamic user experience. By leveraging modular structures and specialized tools like Redocly and Algolia, the system provides a performant and interactive platform for technical documentation and API exploration.