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.

• Overview
• Documentation Files
• Getting Started
• Contributing

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

This technical documentation consists of several specialized files:

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

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.

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

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

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