Getting Started & Setup

Relevant source files

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

• DEVELOPMENT.md
• package.json
• README.md
• CONTRIBUTING.md
• ARCHITECTURE.md
• CONTENT_AUTHORING.md
• API_DOCS_INTEGRATION.md

This page provides a comprehensive guide for developers and content authors to set up the CircleCI Docs Static Site development environment. The project is a documentation platform built using Antora, a static site generator designed for multi-repository documentation, and integrated with a custom UI and automated build pipelines. Sources: README.md:1-15, ARCHITECTURE.md:1-12

The setup process covers environment prerequisites, initial repository configuration, and the workflows required to build and preview the documentation locally. This includes managing UI bundles, fetching server-specific documentation branches, and integrating live API documentation. Sources: README.md:21-45, DEVELOPMENT.md:14-35

Environment Prerequisites

Before beginning the setup, ensure your local environment meets the following software requirements:

Tool	Version Requirement	Purpose
Node.js	v22 or later	Core runtime for build tools and Antora
npm	v8 or later	Package management
Git	Latest version recommended	Version control and sub-module management

Sources: DEVELOPMENT.md:16-20, CONTRIBUTING.md:25-30

For an optimal development experience, it is recommended to configure your code editor with the AsciiDoc extension for .adoc files, ESLint for JavaScript linting, and Prettier for code formatting. Sources: DEVELOPMENT.md:31-35

Initial Repository Setup

The project requires a sequence of commands to correctly initialize the repository and its dependencies.

Step-by-Step Installation

1. Clone the Repository:

   git clone https://github.com/circleci/circleci-docs.git
   cd circleci-docs
   

   Sources: README.md:24-26, DEVELOPMENT.md:24-25

2. Install Dependencies:
   The project uses npm ci to ensure consistent installations based on the package-lock.json.

   npm ci
   

   Sources: README.md:27, DEVELOPMENT.md:27-28

3. Fetch Server Documentation Branches:
   This step is critical for including Server Administration documentation in the build.

   npm run fetch-server-branches
   

   Sources: README.md:30-33, package.json:13

4. Environment Variables:
   The project uses dotenvx to manage environment variables. A .env.copy file is provided as a template for creating your .env file in the project root. Sources: DEVELOPMENT.md:29-30, package.json:20

Setup Workflow Diagram

The following diagram illustrates the sequence of actions required to move from a fresh clone to a running local preview.

Development Workflows

The project supports several distinct workflows depending on whether you are working on documentation content, the UI theme, or API integrations.

Content Authoring Workflow

Documentation is organized into logical components within the docs/ directory. Each component contains its own antora.yml configuration and nav.adoc navigation structure. Sources: ARCHITECTURE.md:43-58, CONTENT_AUTHORING.md:12-25

To add or edit content:

1. Navigate to the relevant component (e.g., docs/guides/).
2. Add or modify AsciiDoc (.adoc) files in the pages/ directory.
3. Update the nav.adoc file if the page hierarchy has changed.
4. Preview changes using the development server.

Sources: DEVELOPMENT.md:65-85

UI Development Workflow

The UI project is located in the ui/ directory and utilizes Gulp and Tailwind CSS. Sources: ARCHITECTURE.md:25-30, DEVELOPMENT.md:105-115

API Documentation Integration

This project integrates both static (v1) and live (v2) API documentation. Sources: API_DOCS_INTEGRATION.md:5-20

• API v1: Static documentation is copied from the api-v1/ directory.
• API v2: A live OpenAPI spec is fetched from the CircleCI API and processed through a pipeline involving Redocly and custom patches.

To build the API documentation specifically:

npm run build:api-docs

Sources: README.md:42, API_DOCS_INTEGRATION.md:65-70

Command Reference

The following table lists the primary scripts available in the root package.json for managing the documentation site.

Command	Description
npm run start:dev	Starts the development server with live reload and UI rebuilds.
npm run build:docs	Performs a full build of the site, including UI and API docs.
npm run build:ui	Rebuilds only the UI bundle (ui-bundle.zip).
npm run build:api-docs	Rebuilds the API v1 and v2 documentation.
npm run preview:ui	Focuses on UI development with faster rebuilds.

Sources: DEVELOPMENT.md:47-60, package.json:6-14

Summary

The CircleCI Docs Static Site relies on a component-based architecture where Antora assembles AsciiDoc content and a Gulp-driven UI bundle. Successful setup requires Node.js v22+, fetching specific server documentation branches, and using the automated build scripts to generate the final static site. Developers can choose between targeted UI builds or a comprehensive site build that includes integrated API reference documentation. Sources: ARCHITECTURE.md:10-20, README.md:60-80