CircleCI Docs

CircleCI Docs

CircleCI Docs is the open-source technical documentation project behind the CircleCI documentation site, built with Antora and AsciiDoc.

What is CircleCI Docs?

It is a static site generator–based documentation platform that consumes AsciiDoc content organized into components and produces a deployed static documentation site. The project is maintained by CircleCI, with contribution guidelines published in CONTRIBUTING.md, and is publicly available on GitHub at github.com/circleci/circleci-docs. It powers both the user documentation and the integrated API reference, the latter built with Redocly.

What makes CircleCI Docs stand out?

• Component-based architecture — Organizes documentation into logical, versionable components instead of a single monolithic tree, following Antora's content model.
• AsciiDoc authoring — All pages are written in AsciiDoc, which supports structured elements like tables, callouts, and includes for reuse.
• Custom UI — Replaces the default Antora UI with a tailored presentation built with modern web technologies.
• Automated build pipeline — Uses CircleCI itself for building and previewing the site; contributors can preview changes via the CircleCI build assets at app.circleci.com/pipelines/github/circleci/circleci-docs.
• Bundled API documentation — API reference is generated with Redocly and built as part of the same docs site.
• Hacktoberfest-friendly — The repository is tagged with hacktoberfest, inviting community contributions during Hacktoberfest season.

Who should use CircleCI Docs?

• Documentation contributors — Anyone wanting to fix a typo or add a guide: clone the repo, run npm ci, start the dev server with npm run start:dev, create a branch, and submit a pull request.
• CircleCI content authors — Writers who create or edit documentation, following the AsciiDoc formatting guidelines and the CircleCI docs style guide linked from the README.
• Documentation infrastructure engineers — Developers who maintain the Antora UI, component structure, or build pipeline, using ARCHITECTURE.md, DEVELOPMENT.md, and TECHNICAL_REFERENCE.md as guides.

What can you do with CircleCI Docs?

• Community contributors: add or correct documentation content and preview the result locally before submitting a PR.
• Content authors: check whether content already exists, follow the style guide, and test changes locally before publishing.
• API documentation maintainers: integrate and update API reference docs through the Redocly-based API docs integration described in API_DOCS_INTEGRATION.md.