Introduction & Project Goals
Relevant source files
The following files were used as context for generating this wiki page:
The CircleCI Docs Static Site is a comprehensive documentation platform designed to deliver technical content for CircleCI users, including developers, administrators, and contributors. It is built as a multi-repository documentation site using Antora, which allows for a modular, component-based approach to content management. The project integrates diverse content types—from high-level guides to detailed API references—into a unified, searchable, and modern web interface.
The primary goal of the project is to provide a streamlined development and deployment process for documentation. By separating content (authored in AsciiDoc) from presentation (managed via a custom UI bundle), the site ensures scalability and consistency across different documentation sets. Key objectives include supporting a component-based architecture, maintaining a robust automated build pipeline, and providing a tailored user experience through a custom UI framework.
Sources: README.md:1-15, ARCHITECTURE.md:1-15, DEVELOPMENT.md:1-10
Core Project Architecture
The architecture is centered around the Antora static site generator, which facilitates the assembly of documentation from various sources into a single site. The system is divided into four primary architectural pillars: content organization, the UI framework, the build system, and custom extensions.
High-Level System Overview
The following diagram illustrates the relationship between the core components of the CircleCI documentation system:
This diagram shows how documentation content and UI assets are processed through the build system to generate the final static site.
Sources: ARCHITECTURE.md:15-35, TECHNICAL_REFERENCE.md:110-130
Component-Based Content Organization
Documentation is organized into logical components, each residing in the docs/ directory. This structure allows individual teams to manage specific areas of the documentation (e.g., Guides, Orbs, Server Administration) independently while maintaining a global navigation structure.
| Component | Purpose | Location |
|---|---|---|
root | Home and landing pages | docs/root/ |
guides | How-to guides and tutorials | docs/guides/ |
reference | API and configuration references | docs/reference/ |
orbs | CircleCI orbs documentation | docs/orbs/ |
server-admin | Server administration guides | docs/server-admin-4.*/ |
Each component follows a standardized internal structure to ensure compatibility with the Antora engine:
antora.yml: Component metadata and configuration.modules/ROOT/nav.adoc: Defines the sidebar navigation.modules/ROOT/pages/: Contains the actual AsciiDoc content files.modules/ROOT/assets/: Stores images and downloadable attachments.
Sources: CONTENT_AUTHORING.md:15-45, ARCHITECTURE.md:40-60, TECHNICAL_REFERENCE.md:165-185
Build Pipeline & Automation
The project utilizes Gulp to orchestrate a multi-stage build pipeline. This automation ensures that the UI is bundled and the documentation is rendered consistently across local development and production environments.
The Build Workflow
- UI Bundle Creation: Gulp processes CSS (via Tailwind), JavaScript, and Handlebars templates to create a
ui-bundle.zip. - Content Processing: Antora loads the component configurations and processes AsciiDoc files.
- Extension Execution: Custom extensions (e.g., for Algolia metadata or page last-updated dates) are applied during the rendering process.
- Site Assembly: The UI bundle and processed content are combined into the final
/builddirectory.
This sequence diagram details the steps taken by the automated system to convert raw content into a deployable static site.
Sources: ARCHITECTURE.md:75-95, TECHNICAL_REFERENCE.md:65-90, DEVELOPMENT.md:40-60
Development & Contribution Goals
The project is designed to be highly accessible for both technical contributors and content authors. The workflow emphasizes local previewing and automated testing to maintain high documentation quality.
Key Development Commands
npm run start:dev: Starts a local development server with live reload and UI bundling.npm run build:docs: Performs a full production build of the entire site.npm run fetch-server-branches: Retrieves necessary branches for Server Administration docs.
Quality Assurance Principles
The project enforces specific standards for all contributions:
- Technical Accuracy: Content must be verified against actual code behavior.
- Semantic Guidelines: Authors are encouraged to use specific documentation types (Tutorials, How-to, Reference, Explanation).
- Review Process: All changes require a peer review and must pass automated CI checks (e.g., link checking and UI validation).
Sources: README.md:40-65, DEVELOPMENT.md:30-45, CONTRIBUTING.md:20-50, CONTENT_AUTHORING.md:165-180
Conclusion
The CircleCI Docs Static Site project aims to create a world-class documentation experience by leveraging modern static site generation technologies. By adopting a component-based architecture and a robust Gulp-driven build pipeline, the project ensures that content remains modular, the UI remains performant, and the contribution process remains efficient for the entire CircleCI community.
Sources: README.md:10-25, ARCHITECTURE.md:10-20