Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Contributing to the CircleCI Docs Static Site involves a multi-faceted approach covering documentation content, technical infrastructure, UI enhancements, and bug fixes. The project is built on the Antora documentation platform, which utilizes a component-based architecture and AsciiDoc for content creation. This ensures a clear separation between content and presentation, supported by an automated build pipeline.
Sources: CONTRIBUTING.md:7-14, README.md:14-20, ARCHITECTURE.md:14-17
Development Environment Setup
To contribute to the project, developers must establish a local environment that mirrors the production build pipeline. The core stack relies on Node.js and npm for managing the build system and UI components.
Prerequisites and Initial Setup
The project requires the following environment specifications:
- Node.js: version 22 or later
- npm: version 8 or later
- Git: Latest version recommended
Sources: CONTRIBUTING.md:32-35, DEVELOPMENT.md:14-17
The setup process involves forking the repository, cloning it locally, and installing dependencies using npm ci to ensure consistency with the package-lock.json.
git clone https://github.com/circleci/circleci-docs.git
cd circleci-docs
npm ci
Sources: README.md:33-37, DEVELOPMENT.md:23-28
Local Development Flow
The following diagram illustrates the lifecycle of starting the development environment and previewing changes.
The development server automates the UI bundle creation and site rebuilding with live-reload capabilities.
Sources: DEVELOPMENT.md:40-48, README.md:39-41
Contribution Workflow
The project follows a standard Git-based contribution model. Contributors are expected to use descriptive branch names and follow semantic commit message formats to facilitate clear version history and automated release notes.
Branching and Commits
Branch names should be prefixed by the type of change:
docs/: Documentation updatesfeature/: New technical functionalityfix/: Bug fixesrefactor/: Code reorganizationtest/: Test-related changes
Sources: CONTRIBUTING.md:57-66
Commit messages should follow the pattern: type(scope): Brief description. Supported types include feat, fix, docs, style, refactor, and test.
Sources: CONTRIBUTING.md:88-100
Pull Request (PR) Lifecycle
The following sequence diagram outlines the interaction between a contributor, the GitHub repository, and the CI/CD pipeline.
Sources: CONTRIBUTING.md:112-140, ARCHITECTURE.md:73-81
Content Authoring Standards
Content authors must adhere to specific structural and semantic guidelines to maintain documentation quality. The site uses AsciiDoc (.adoc) for all content.
Document Structure
A standard documentation page should include specific metadata attributes and structural elements:
| Attribute/Section | Description | Example |
|---|---|---|
= Page Title | Level 0 heading (Title) | = Getting Started |
:description: | SEO and meta description | :description: Setup guide |
:page-toclevels: | Controls Table of Contents depth | :page-toclevels: 3 |
[abstract] | Concise intro paragraph | [abstract] \n -- \n Intro \n -- |
xref: | Internal cross-reference | xref:component:page.adoc[Text] |
Sources: CONTENT_AUTHORING.md:65-72, CONTENT_AUTHORING.md:126-146
Component Organization
Documentation is modularized into Antora components. Each component contains its own antora.yml configuration and nav.adoc navigation structure.
docs/component-name/
├── antora.yml # Component configuration
└── modules/
└── ROOT/ # Default module
├── nav.adoc # Sidebar navigation
├── pages/ # AsciiDoc content files
└── assets/ # Images and media
Sources: ARCHITECTURE.md:40-54, DEVELOPMENT.md:87-95
UI and Technical Infrastructure
Contributors working on the site's "Presentation" layer interact with the ui/ directory, which contains Handlebars templates, Tailwind CSS, and Gulp-based build tasks.
UI Development Commands
- Build UI Bundle:
npm run build:ui(Generatesui-bundle.zip) - Preview UI Changes:
npm run preview:ui(Faster rebuilds focusing on CSS/JS) - Full Build:
npm run build:docs(Combines UI and Antora content)
Sources: DEVELOPMENT.md:50-62, TECHNICAL_REFERENCE.md:86-95
UI Architecture
The UI is a custom theme based on the Antora Default UI but enhanced with Tailwind CSS.
| Component | Technology | Path |
|---|---|---|
| Templating | Handlebars (.hbs) | ui/src/layouts/, ui/src/partials/ |
| Styling | Tailwind CSS | ui/src/css/ |
| Scripts | JavaScript (ES6+) | ui/src/js/ |
| Build Tool | Gulp | ui/gulpfile.js, gulp.d/ |
Sources: ARCHITECTURE.md:83-93, DEVELOPMENT.md:131-143, TECHNICAL_REFERENCE.md:111-125
Review and Release Process
All contributions are subject to a structured review process to ensure technical accuracy and adherence to style guides.
- Automated Checks: The CI system runs build tests, link checking, and code linting.
- Code/Content Review: Maintainers evaluate technical accuracy, security impact, performance, and clarity.
- Staging: Approved PRs are merged to
main, triggered a build and deployment to a staging environment. - Production: Once verified in staging, changes are deployed to the production site.
Sources: CONTRIBUTING.md:173-195, CONTRIBUTING.md:209-216
Summary
Contributing to the CircleCI Docs project requires understanding the interplay between AsciiDoc content and the Antora/Gulp technical infrastructure. Whether providing content updates or UI improvements, contributors must follow the established branching strategies, commit formats, and authoring guidelines to maintain a cohesive and high-quality documentation platform.