Internal Go Packages

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
• package.json
• API_DOCS_INTEGRATION.md

The CircleCI Docs Static Site infrastructure utilizes internal packages and specialized extensions to manage the transformation of documentation from source files to a rendered static site. While the primary content authoring is performed in AsciiDoc, the backend logic involves modular build systems, custom Antora extensions, and utility scripts that handle metadata generation and content export.

The system is designed with a component-based architecture where presentation is separated from content. Presentation is managed via a UI bundle, while internal logic handles the aggregation of multiple repositories, versioning, and integration with the CircleCI API.

Sources: ARCHITECTURE.md:10-22, TECHNICAL_REFERENCE.md:12-25

Core Architectural Modules

The internal logic is divided into several specialized modules that handle different stages of the documentation lifecycle.

Antora Extensions and Metadata

The project utilizes custom extensions to enhance the core capabilities of the Antora static site generator. These extensions facilitate content export and the enrichment of page metadata, such as "last updated" timestamps derived from Git history.

• Content Export Extension: Manages the transformation and export of content for external integrations like search indexing.
• Page Metadata Extension: Injects custom attributes into pages, including commit-linked metadata.

Sources: ARCHITECTURE.md:46-55, TECHNICAL_REFERENCE.md:135-155

Build Orchestration

The build system is managed via Gulp and a series of JavaScript tasks that interface with the underlying documentation engine. This includes specialized tasks for API documentation integration which involves fetching live data and applying patches.

This diagram illustrates the sequential flow of the build pipeline, emphasizing the integration of API documentation after the main site generation.
Sources: ARCHITECTURE.md:68-85, gulp.d/tasks/build-api-docs.js:15-45

API Documentation Integration

The system maintains two distinct versions of API documentation with different internal handling logic.

API v1 (Static Legacy)

Internal logic for API v1 is primarily a synchronization task. The build system verifies the existence of the source directory and performs a recursive copy to preserve assets such as fonts, images, and stylesheets.

API v2 (Dynamic Pipeline)

The API v2 module implements a sophisticated processing pipeline. It does not rely on local source files for the specification but fetches a live OpenAPI JSON from the CircleCI production environment.

Stage	Logic Description	Tooling
Fetch	Retrieves live openapi.json from circleci.com	curl
Bundle	Resolves $ref pointers and removes unused components	@redocly/cli
Enrich	Injects code samples (cURL, Node.js, Go, etc.)	httpsnippet
Patch	Applies custom modifications via openapi-patch.json	jq
Lint	Validates the final specification against quality rules	@redocly/cli
Build	Renders final interactive HTML documentation	Redocly

Sources: gulp.d/tasks/build-api-docs.js:90-190, API_DOCS_INTEGRATION.md:38-65

Technical Reference and Tooling

The internal logic relies on specific environment variables and scripts to maintain consistency across the documentation components.

Maintenance and Metadata Scripts

Internal maintenance is handled by a set of specialized scripts found in the scripts/ directory.

• fetch-server-branches.sh: Logic to pull documentation for specific CircleCI Server versions.
• gen-git-last-update-meta.sh: Extracts Git history to provide accurate "Last Updated" information.
• convert_frontmatter.py: A transformation script that converts YAML frontmatter into AsciiDoc attributes for compatibility with the Antora engine.

Sources: TECHNICAL_REFERENCE.md:173-195, package.json:7-14

System Dependencies

The internal logic is implemented using CommonJS and relies on several key development dependencies for processing documentation.

{
  "devDependencies": {
    "@antora/cli": "3.1.14",
    "@redocly/cli": "^2.0.0",
    "gulp": "^5.0.0",
    "httpsnippet": "^3.0.9"
  }
}

Sources: package.json:23-32

Summary of Integration Logic

The internal packages ensure that the final documentation site is not merely a collection of static files but a dynamic platform. This is achieved by:

1. Orchestrating multiple content sources via the Antora Playbook.
2. Enriching standard output with custom metadata via JavaScript extensions.
3. Integrating external live API data through a multi-stage transformation pipeline.

Sources: ARCHITECTURE.md:87-105, DEVELOPMENT.md:162-185