Custom Gulp Tasks
Relevant source files
The following files were used as context for generating this wiki page:
Custom Gulp tasks serve as the orchestration layer for the CircleCI Docs static site, automating the build, preview, and integration processes. The system is divided into two primary areas: the root project tasks that handle the complete site and API documentation, and the UI-specific tasks located within the ui/ directory that manage asset bundling and styling.
The architecture relies on a modular task structure where individual task logic is defined in the gulp.d/tasks/ directory and exported through a central gulpfile.js. This allows for a clean separation between task definition and execution, enabling developers to build the UI bundle, generate API documentation, or preview the site with live reloading.
Sources: ARCHITECTURE.md:27-31, gulpfile.js:1-25
Task Orchestration and Infrastructure
The project utilizes a library-based approach to task creation and exporting. Tasks are wrapped using helper functions to provide consistent metadata, such as names and descriptions, which are then used by the Gulp CLI.
Core Task Registry
The root gulpfile.js defines the high-level workflows required for site generation.
| Task Name | Description | Source Call |
|---|---|---|
build:ui | Builds the UI bundle for Antora | tasks.buildUi |
build:api-docs | Builds API v1 and v2 documentation | tasks.buildApiDocs |
build:docs | Builds the complete Antora site including API docs | tasks.buildSite |
preview:docs | Serves and watches documentation content only | tasks.docsPreview |
preview:ui | Serves docs and watches for UI source changes | tasks.uiPreview |
Sources: gulpfile.js:5-35, TECHNICAL_REFERENCE.md:95-103
UI Task Module
The ui/gulpfile.js manages a more granular set of tasks specifically for asset management, including linting, formatting, and bundling the UI into a distributable .zip file.
The diagram shows the sequential flow of the UI bundling process from cleaning to final package creation.
Sources: ui/gulpfile.js:31-77, ARCHITECTURE.md:41-45
API Documentation Build Pipeline
One of the most complex custom tasks is build:api-docs. This task integrates static legacy documentation (v1) with dynamically generated OpenAPI documentation (v2).
API v1: Static Copy
The build process for API v1 is a straightforward recursive copy of the api-v1/ directory to the final build destination. This preserves fonts, images, and legacy stylesheets without modification.
Sources: gulp.d/tasks/build-api-docs.js:53-70, API_DOCS_INTEGRATION.md:41-45
API v2: Dynamic Generation
The v2 pipeline involves fetching live data and applying several transformations.
The sequence illustrates the multi-step transformation from a raw OpenAPI JSON to a fully interactive HTML document with injected code snippets.
Sources: gulp.d/tasks/build-api-docs.js:106-180, API_DOCS_INTEGRATION.md:47-55
UI Development and Preview Tasks
For local development, the Gulp configuration provides specialized "preview" tasks. These tasks utilize gulp-connect and livereload to provide a real-time feedback loop.
Preview Workflow Logic
preview:docs: Watches.adocfiles in thedocs/component directories.preview:ui: Watches theui/src/directory for changes in CSS, JS, or Handlebars templates. It triggers thebuild:uitask and reloads the browser when the bundle is updated.
Sources: gulpfile.js:23-33, DEVELOPMENT.md:45-55, TECHNICAL_REFERENCE.md:120-128
UI Build Specifics
The UI build process includes:
- Linting: Using
stylelintfor CSS andeslintfor JavaScript. - Tailwind Processing: Building utility classes based on
tailwind.config.js. - Bundling: Packaging assets into
ui-bundle.zipwhich Antora consumes via the--ui-bundle-urlflag.
Sources: ui/gulpfile.js:31-50, TECHNICAL_REFERENCE.md:165-175, DEVELOPMENT.md:110-120
Summary
Custom Gulp tasks in this project provide the necessary glue between disparate tools like Antora, Redocly, and Tailwind CSS. By categorizing tasks into site-wide orchestration and specialized UI asset management, the system ensures a scalable build pipeline that supports both legacy static content and modern dynamic API documentation generation.