CircleCI docs site: technical documentation

Welcome to the comprehensive technical documentation for the CircleCI docs project. This documentation is designed to help developers, content authors, and contributors understand the project's architecture, workflow, and best practices.

Table of contents

• Overview
• Documentation Files
• Getting Started
• Contributing

Overview

The CircleCI docs site is a documentation platform built using Antora, a static site generator designed for technical documentation. This project combines:

• Component-based architecture: Organized documentation into logical sections
• AsciiDoc content: Powerful markup language for technical documentation
• Custom UI: Tailored presentation with modern web technologies
• Automated build pipeline: Streamlined development and deployment process

Documentation Files

This technical documentation consists of several specialized files:

File	Purpose
README.md	Project overview and basic usage
ARCHITECTURE.md	Detailed system architecture
DEVELOPMENT.md	Development setup and workflows
CONTENT_AUTHORING.md	Writing and formatting guidelines
TECHNICAL_REFERENCE.md	Detailed technical specifications
API_DOCS_INTEGRATION.md	API documentation integration guide
CONTRIBUTING.md	Guidelines for contributors

Getting Started

For Contributors

1. Set up your environment:

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

2. Start the development server:

   npm run start:dev
   

For API Documentation

This project includes integrated API documentation built with Redocly. See API_DOCS_INTEGRATION.md for details.

The API docs are built along with the docs site.

Technical Reference

You can review the CircleCI docs site architechture in the following documents:

• ARCHITECTURE.md for system design
• DEVELOPMENT.md for development workflow
• TECHNICAL_REFERENCE.md for detailed specs

For Content Authors

1. Understand the content organization:

   • Read CONTENT_AUTHORING.md for guidelines
   • Review existing content for examples and patterns

2. Set up your environment:

   • Follow the developer setup instructions
   • Start the development server to preview changes

3. Create or edit content:

   • Check whether the content you want to add or edit already exists. Consider whether you need to add a new page or edit existing material
   • Check the CircleCI docs style guide and templates here
   • Follow the AsciiDoc formatting guidelines
   • Use the appropriate component structure
   • Test your content locally. You can also preview a change by checking the CircleCI build assets

Contributing

We welcome contributions to both the documentation content and the technical infrastructure. To contribute:

1. Review CONTRIBUTING.md for guidelines
2. Set up your development environment
3. Create a branch for your changes
4. Submit a pull request