Handlebars Helpers
Relevant source files
The following files were used as context for generating this wiki page:
Handlebars Helpers are a critical component of the CircleCI Docs Static Site's UI framework. They extend the capabilities of Handlebars templates by providing custom logic for data transformation, conditional rendering, and metadata extraction during the site assembly process. These helpers reside within the ui/src/helpers/ directory and are integrated into the Gulp-based UI build pipeline to produce the final documentation pages.
The primary purpose of these helpers is to process Antora-provided variables—such as site, page, and navigation—and convert them into a format suitable for the custom Tailwind CSS-based theme. This includes managing complex navigation structures, evaluating multi-variable logical conditions, and surfacing page-specific attributes for SEO and social sharing.
Sources: ARCHITECTURE.md:43-52, TECHNICAL_REFERENCE.md:104-106, TECHNICAL_REFERENCE.md:120-125
Architecture and Integration
Handlebars helpers are part of the UI Bundle, which is managed separately from the documentation content. The UI project uses Gulp to bundle these helpers into a ui-bundle.zip file, which Antora subsequently uses to render HTML.
The diagram above illustrates how Javascript helpers are bundled and consumed by the static site generator to produce processed HTML.
Sources: ARCHITECTURE.md:21-31, TECHNICAL_REFERENCE.md:70-76
Core Helper Categories
Logical Helpers
The and helper provides multi-argument boolean logic within templates. Unlike standard Handlebars if blocks that evaluate a single value, this helper allows templates to check multiple conditions simultaneously. It iterates through all provided arguments and returns false if any argument is falsy; otherwise, it returns the final value.
Sources: ui/src/helpers/and.js:1-12
Navigation Helpers
The components-to-nav-list helper is responsible for transforming Antora's component data into a structured navigation list. This is primarily used for the "Component Explorer" or sidebar navigation, where it maps component metadata (like titles and versions) into a format that the partials/nav.hbs or partials/component-explorer-nav.hbs templates can iterate over.
Sources: ui/src/helpers/components-to-nav-list.js:1-15, TECHNICAL_REFERENCE.md:113-118
Metadata Helpers
The get-page-meta helper extracts specific attributes from the page object to populate HTML <meta> tags. It prioritizes attributes defined in the AsciiDoc header (e.g., :description:) but provides fallback logic using site-wide defaults if specific page attributes are missing.
| Helper Function | Input Parameters | Primary Responsibility |
|---|---|---|
and | ...args | Performs a logical AND operation across multiple template variables. |
components-to-nav-list | components | Converts the site component catalog into an array for navigation menus. |
get-page-meta | page, site | Extracts and formats page titles, descriptions, and OpenGraph metadata. |
Sources: ui/src/helpers/get-page-meta.js:1-10, CONTENT_AUTHORING.md:46-52
Data Flow: Metadata Extraction
The get-page-meta helper interacts with the global site and local page objects provided by Antora to ensure SEO consistency across the site.
This flow ensures that every page has valid metadata even if the content author does not explicitly define it in the AsciiDoc source.
Sources: ui/src/helpers/get-page-meta.js:1-15, TECHNICAL_REFERENCE.md:127-135
Implementation Details
Boolean Logic Implementation
The and helper is implemented using a rest parameter to handle an arbitrary number of conditions.
module.exports = (...args) => {
// Handlebars passes an 'options' object as the last argument
const options = args.pop()
return args.every(Boolean) ? args[args.length - 1] : false
}
Sources: ui/src/helpers/and.js:1-12
Navigation Mapping
The components-to-nav-list helper processes the component catalog. It filters out hidden components and sorts them based on the configuration defined in the site's antora-playbook.yml.
Sources: ui/src/helpers/components-to-nav-list.js:1-20, TECHNICAL_REFERENCE.md:15-30
Conclusion
Handlebars Helpers in the CircleCI Docs project serve as the bridge between raw Antora data and the specialized requirements of the documentation UI. By encapsulating logic for navigation transformation, metadata fallback, and complex conditionals, these helpers keep the Handlebars templates clean and maintainable while ensuring a robust and SEO-friendly documentation experience.
Sources: ARCHITECTURE.md:43-46, DEVELOPMENT.md:117-122