UI Bundle Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The UI Bundle Architecture represents the presentation layer of the CircleCI documentation platform. Built on Antora's default UI but heavily customized, it separates content (written in AsciiDoc) from the visual and interactive elements of the site. The architecture follows a modular approach where styles, templates, and scripts are processed into a single ui-bundle.zip file, which is then consumed by the Antora site generator to produce the final static HTML.
Sources: ARCHITECTURE.md:12-16, TECHNICAL_REFERENCE.md:83-88
Core Framework and Technologies
The UI framework is designed to provide a modern, responsive, and interactive experience for technical documentation. It utilizes a combination of templating engines and CSS frameworks to maintain a consistent brand identity across the project.
Technical Stack Components
| Technology | Purpose | Implementation Details |
|---|---|---|
| Handlebars | Templating | Used for defining HTML layouts and reusable partials. |
| Tailwind CSS | Styling | A utility-first CSS framework used for site-wide styling and custom components. |
| Gulp | Build System | Automates tasks like CSS minification, JS bundling, and packaging the UI bundle. |
| Modular JS | Interactivity | Handles client-side features such as navigation, search, and UI state. |
Sources: ARCHITECTURE.md:89-94, TECHNICAL_REFERENCE.md:113-125
UI Lifecycle and Data Flow
The following diagram illustrates how the UI bundle is generated and subsequently integrated with the Antora content processing pipeline.
The Gulp build system processes UI source files into a bundle, which Antora then uses to wrap processed AsciiDoc content into final HTML pages.
Sources: ARCHITECTURE.md:67-84, TECHNICAL_REFERENCE.md:80-81
UI Directory Structure
The UI logic and assets are isolated within the ui/ directory to maintain a clear separation from documentation content.
ui/
├── src/
│ ├── css/ # Base and site-specific styles
│ ├── helpers/ # Custom Handlebars helpers
│ ├── img/ # Static image assets
│ ├── js/ # Modular JavaScript files
│ ├── layouts/ # Primary page layout templates (e.g., default.hbs)
│ └── partials/ # Reusable template fragments (header, footer, nav)
├── preview-src/ # Mock data (ui-model.yml) for local UI testing
└── tailwind.config.js # Tailwind CSS configuration
Sources: DEVELOPMENT.md:118-130, TECHNICAL_REFERENCE.md:103-112
Templating and Layouts
The UI uses Handlebars to define the structure of the site. Templates have access to a rich set of variables provided by Antora during the generation process.
Template Variables
| Variable | Scope | Description |
|---|---|---|
site | Global | Site-wide configuration like title and production URL. |
page | Local | Metadata for the current page, including title, version, and edit URL. |
navigation | Structural | The hierarchical structure of the sidebar navigation. |
uiRootPath | Pathing | Relative path to UI assets (CSS, JS) from the current page. |
Sources: TECHNICAL_REFERENCE.md:117-125, ui/preview-src/ui-model.yml:51-60
Page Layout Structure
The primary layout resides in layouts/default.hbs, which acts as the skeleton for every documentation page. It includes essential partials to build the complete view:
- Header: Includes site-wide branding and global navigation.
- Navigation: Renders the component explorer and module-specific sidebars.
- Main Content: Injects the processed AsciiDoc HTML.
- Footer: Contains copyright information and utility links.
Sources: TECHNICAL_REFERENCE.md:113-116
UI Development and Preview
To ensure rapid iteration without rebuilding the entire documentation set, the architecture includes a specialized UI preview mechanism.
UI Preview Sequence
The preview system uses mock data to simulate the Antora environment, allowing developers to see UI changes instantly.
This workflow allows UI developers to test layouts and styles against local AsciiDoc files like ui/preview-src/index.adoc using mock data from ui-model.yml.
Sources: DEVELOPMENT.md:46-59, DEVELOPMENT.md:132-137, package.json:8
Styling and Components
Styling is handled via Tailwind CSS, following a utility-first approach. Custom components are extracted when patterns repeat across the documentation site.
Design Principles
- Utility-First: Styles are primarily applied via utility classes in Handlebars templates.
- Responsive Design: The UI employs a mobile-first approach with Tailwind breakpoints.
- Component Extraction: Complex or repeated patterns (like admonitions, tabs, and badges) are defined as custom components in CSS.
Sources: DEVELOPMENT.md:144-152, TECHNICAL_REFERENCE.md:127-130
Content-Specific Styling
The UI includes specific styles for AsciiDoc elements rendered within the layouts:
- Admonitions: Styled blocks for
NOTE,TIP,IMPORTANT,WARNING, andCAUTION. - Code Blocks: Enhanced with syntax highlighting and buffer-aware line numbering.
- Collapsible Sections: Uses Tailwind and JS to handle toggling visibility of "Details" blocks.
- Badges: Support for custom status badges (e.g., "Preview", "Deprecated") using hex colors or Tailwind classes.
Sources: CONTENT_AUTHORING.md:46-77, ui/preview-src/index.adoc:65-80
Summary
The UI Bundle Architecture is a modular, Gulp-driven system that transforms Handlebars templates and Tailwind CSS into a portable package. By separating the presentation logic from the documentation source, it allows for independent development cycles while ensuring that the CircleCI brand and interactive features remain consistent across thousands of documentation pages. This structure facilitates high-performance static site generation while maintaining a flexible, modern developer experience for UI contributors.
Sources: ARCHITECTURE.md:20-24, TECHNICAL_REFERENCE.md:209-215