Project File Structure
Relevant source files
The following files were used as context for generating this wiki page:
The CircleCI Docs project is a documentation platform built using Antora, a static site generator designed for multi-repository documentation. Its file structure is strictly organized to separate documentation content, UI presentation, build automation, and technical extensions. This modularity allows content authors to focus on AsciiDoc files while developers manage the site's React-based UI and Gulp-driven build pipeline.
The project follows a component-based architecture where documentation is divided into logical sections like guides, references, and server administration. Each section is treated as an independent Antora component with its own configuration and navigation.
Sources: README.md:12-20, ARCHITECTURE.md:14-25
Core Directory Organization
The repository is divided into several high-level directories that represent the distinct functional areas of the documentation system.
| Directory | Purpose | Key Contents |
|---|---|---|
docs/ | Documentation Content | Organized into Antora components (e.g., guides, reference) |
ui/ | UI Bundle | Handlebars templates, Tailwind CSS, and site JavaScript |
gulp.d/ | Build System | Gulp tasks for site assembly and API doc generation |
extensions/ | Custom Logic | JavaScript extensions for Antora's build process |
scripts/ | Utilities | Maintenance, migration, and metadata generation scripts |
Sources: ARCHITECTURE.md:27-44, TECHNICAL_REFERENCE.md:130-143
The docs/ Directory Structure
The docs/ directory contains the source content for the site. Every subdirectory within docs/ represents an Antora component. Each component must contain an antora.yml configuration file and a modules/ directory.
The diagram above shows the standard hierarchy for any documentation component in the system.
Sources: CONTENT_AUTHORING.md:28-42, DEVELOPMENT.md:68-77
Build and Configuration Files
The project’s behavior is governed by root-level configuration files and specialized build tasks located in gulp.d/.
Antora Playbook
The antora-playbook.yml file acts as the primary configuration for the entire site. It defines the content sources, UI bundle location, and global AsciiDoc attributes.
content:
sources:
- url: .
start_path: docs/root
- url: .
start_path: docs/guides
# ... additional sources
ui:
bundle:
url: ./ui-bundle.zip
Sources: antora-playbook.yml:8-25, TECHNICAL_REFERENCE.md:22-55
Gulp Build Pipeline
The build pipeline is orchestrated by Gulp tasks that handle different stages of site generation.
The build process ensures that UI assets are prepared before the site generator processes the AsciiDoc content and integrates API reference documentation.
Sources: TECHNICAL_REFERENCE.md:86-115, API_DOCS_INTEGRATION.md:12-25
UI and Asset Structure
The ui/ directory contains the source code for the site's look and feel. It is built independently into a ui-bundle.zip which is then consumed by Antora.
ui/src/layouts/: Contains.hbs(Handlebars) templates defining the main page structures.ui/src/partials/: Reusable template fragments like headers, footers, and navigation bars.ui/src/css/: Styling powered by Tailwind CSS.ui/src/js/: Client-side functionality for the documentation site.
Sources: DEVELOPMENT.md:120-132, TECHNICAL_REFERENCE.md:130-153
API Documentation Integration
A unique aspect of the project structure is the integration of API documentation, which is handled outside the standard Antora flow but merged into the final /build directory.
api-v1/: A static directory containing legacy API documentation that is copied directly to the build output.build/api/v2/: This directory is dynamically generated by fetching a live OpenAPI spec from CircleCI and processing it with Redocly during the build.
Sources: API_DOCS_INTEGRATION.md:27-45, gulp.d/tasks/build-api-docs.js:41-80
Conclusion
The file structure of the CircleCI Docs project is designed to support a high-scale, multi-version documentation environment. By strictly separating content (in docs/) from presentation (in ui/) and build logic (in gulp.d/ and extensions/), the project maintains a clear workflow for both technical writers and software engineers. The centralized configuration in antora-playbook.yml provides a single point of truth for how these various modules are assembled into the final static site.
Sources: ARCHITECTURE.md:14-25, README.md:12-20