Gulp Build Pipeline

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• DEVELOPMENT.md
• TECHNICAL_REFERENCE.md
• gulp.d/tasks/build-api-docs.js
• ui/gulpfile.js
• package.json
• API_DOCS_INTEGRATION.md

The Gulp build pipeline is the orchestration layer responsible for automating the lifecycle of the CircleCI documentation site. It manages UI asset compilation, content processing via Antora, and the integration of API documentation. The pipeline is designed to separate concerns between content authoring and presentation, providing developers with automated tasks for building, linting, and locally serving the documentation site.

Sources: ARCHITECTURE.md:16-24, TECHNICAL_REFERENCE.md:86-89

Pipeline Architecture and Stages

The pipeline follows a modular multi-stage process to transform source files into a static site. It coordinates three primary workflows: the UI bundle creation, the Antora site generation, and the API documentation integration.

Core Build Stages

1. UI Bundle Build: Processes CSS (using Tailwind), JavaScript, and Handlebars templates into a minified ui-bundle.zip.
2. Content Processing: Loads Antora components and uses Asciidoctor to convert AsciiDoc files into HTML.
3. API Docs Build: Fetches OpenAPI specifications and merges them with static assets to generate API reference pages.
4. Site Assembly: Combines all previous outputs into a final build/ directory structure.

Sources: ARCHITECTURE.md:92-113, API_DOCS_INTEGRATION.md:7-13

Build Flow Diagram

The following flowchart illustrates the sequential and parallel dependencies within the Gulp pipeline:

Task Definitions and Execution

The project utilizes Gulp tasks to provide high-level commands for developers. These tasks are mapped to npm scripts in the root package.json.

Principal Gulp Tasks

Task Name	Implementation File	Purpose
build:ui	ui/gulpfile.js	Cleans, lints, and bundles UI assets (CSS/JS).
build:docs	TECHNICAL_REFERENCE.md	Executes the full site build including Antora and UI.
build:api-docs	gulp.d/tasks/build-api-docs.js	Generates v1 and v2 API documentation.
preview:docs	DEVELOPMENT.md	Starts a local server with live-reload for site preview.

Sources: TECHNICAL_REFERENCE.md:92-97, ui/gulpfile.js:106-117, package.json:7-12

UI Asset Management

The UI build pipeline, located in the ui/ directory, manages the presentation layer. It utilizes Handlebars for templating and Tailwind CSS for styling. The bundle task is the primary entry point for creating the theme used by Antora.

API Documentation Pipeline

The API documentation build is a specialized sub-pipeline orchestrated by Gulp to integrate external API specifications into the documentation site.

API v2 Build Process

The pipeline for API v2 is more complex than v1 (which is a simple copy operation). It performs the following steps:

1. Fetch: Downloads the live OpenAPI spec from circleci.com/api/v2/openapi.json.
2. Bundle/Dereference: Uses @redocly/cli to resolve $ref pointers and optimize the schema.
3. Snippet Generation: Injects code samples for cURL, Node.js, Python, Go, and Ruby.
4. Patching: Applies custom modifications from openapi-patch.json using jq.
5. Rendering: Generates the final interactive HTML via Redocly.

Sources: gulp.d/tasks/build-api-docs.js:84-180, API_DOCS_INTEGRATION.md:43-52

API Integration Table

Version	Strategy	Output Path
API v1	Static file copy from api-v1/	build/api/v1/
API v2	Dynamic generation (Redocly + OIDC)	build/api/v2/index.html

Sources: gulp.d/tasks/build-api-docs.js:14-25, API_DOCS_INTEGRATION.md:15-32

Environment and Configuration

The pipeline behavior can be modified through environment variables and configuration files like antora-playbook.yml and redocly.yaml.

Configuration Elements

• Playbook: Controls content sources (local or remote), UI bundle location, and AsciiDoc extensions (e.g., @asciidoctor/tabs).
• Environment Variables:
  • LIVERELOAD: Enables browser refresh during start:dev.
  • FORCE_NPM_INSTALL: Triggers UI dependency refresh.
  • NODE_ENV: Sets the build context (development vs production).

Sources: TECHNICAL_REFERENCE.md:21-46, TECHNICAL_REFERENCE.md:188-196

The Gulp Build Pipeline ensures that the CircleCI documentation remains a cohesive platform by programmatically linking disparate parts—Asciidoc content, a custom Tailwind UI, and live-fetched API specifications—into a single high-performance static site.

Sources: ARCHITECTURE.md:115-119, DEVELOPMENT.md:38-47