circleci-docs builds the CircleCI manual with Antora and Gulp

The repository is the source of a site, not the site

The circleci-docs repository is the public source for circleci.com/docs, and the package.json description says so directly, calling it the public repository for a static website generated with Antora. The technical documentation inside the repository is written for three different audiences, which the README states as developers, content authors and contributors who need to understand the architecture, the workflow and the practices. That self-documenting aspect is a deliberate design choice and it is visible in the file listing at the repository root: ARCHITECTURE.md for system design, DEVELOPMENT.md for the development workflow, CONTENT_AUTHORING.md for writing and formatting rules, TECHNICAL_REFERENCE.md for detailed specifications, API_DOCS_INTEGRATION.md for the API documentation integration, and CONTRIBUTING.md for contributors. Each of those is a pointer to a deeper document, so the repository explains itself rather than relying on tribal knowledge.

Antora, AsciiDoc and a component based layout

The site generator is Antora, which the README describes as a static site generator designed for technical documentation. The four ingredients it names are a component based architecture that organises documentation into logical sections, AsciiDoc as the markup language, a custom UI built with modern web technologies, and an automated build pipeline. The component model is the part that matters for scale, because a component is a versioned set of pages with its own navigation, and a versioned product manual needs exactly that. The Antora packages are pinned in the devDependencies at 3.2.1 for both the CLI and the site generator, and the repository carries an antora-playbook.yml file, which is the file that defines components, versions and the navigation tree. The custom template is custom-template.hbs, a Handlebars template, so the presentation layer is overridable rather than fixed.

The build is Gulp, and the local preview is a browser sync

The npm scripts show how the pieces fit together, and they are worth reading closely because the order is meaningful.

  "scripts": {
    "start:dev": "dotenvx run -- npm run build:ui && gulp preview:docs",
    "build:ui": "gulp build:ui",
    "build:api-docs": "gulp build:api-docs",
    "build:docs": "npm run build:ui && gulp build:docs",
  },

The development server first builds the custom UI and then asks Gulp to preview the documentation, and the whole thing runs under dotenvx, which loads environment variables from a local file. That last detail is the reason for the .env.copy file at the repository root, and it is the kind of thing that costs an afternoon if you do not know about it. There is a separate preview script for the UI on its own, a dedicated build:api-docs target, and a full build:docs that chains the UI build into the documentation build, which mirrors the way the two outputs are combined in production.

A Go toolchain sits beside the Node one

The repository is described as JavaScript, but there is a go.mod at the root and a go.sum beside it, with a module path of github.com/circleci/circleci-docs and a go directive of 1.26.0. The dependencies are revealing: the AWS SDK for Go v2 with the S3 service, a YAML parser, retryable HTTP, a colour logging library, and golang.org/x/sync. So a Go program in this repository talks to S3, which is the obvious mechanism for publishing build artifacts, and the retryable HTTP client suggests it fetches remote content as part of the pipeline. The internal/ directory, the cmd/ directory and the scripts/ directory hold that side of the codebase, and the long indirect dependency list in go.mod is dominated by linters, which tells you the Go code is held to a strict static analysis bar.

The API reference is Redocly, and there is a patching step

The API documentation is a separate pipeline rather than hand written AsciiDoc. The devDependencies include the Redocly CLI, the repository carries a redocly.yaml configuration and an openapi-patch.json, and the api-v1/ directory exists at the top level alongside a separate schemas/ directory. The build script build:api-docs is wired to Gulp, and the README states that the API docs are built along with the docs site, so a single pipeline produces both the prose manual and the generated reference. The openapi-patch.json file is the interesting artefact: it implies the OpenAPI specification is not taken as published but modified before rendering, which is a common and reasonable practice when a vendor specification and the documentation need to differ slightly.

Link checking, prose linting and a git hook

The quality tooling is part of the build rather than a suggestion. The htmlproofer:dev script checks the built output for links and images, disables external link checking, and ignores the two generated API index files while swapping the /docs/ URL prefix.

    "htmlproofer:dev": "htmlproofer ./build --ignore-empty-alt --checks 'Links,Images' --disable-external --swap-urls '^/docs/:/' --ignore-files './build/api/v1/index.html,./build/api/v2/index.html' --ignore-urls '[url],[path]'

Prose is linted separately with Vale, configured in the .vale.ini file, and there is a scripts/check-metadata.js script behind a check:metadata npm target. A Taskfile.yml sits at the root for task automation, and a hooks:install script points git at the .githooks directory, so the hooks are versioned with the repository rather than living in each contributor's global config. A renovate.json file is also present, so dependency updates are automated. There is a .htmltest.yml and a .nvmrc, which pins the Node version contributors should use.

What the repository does not settle for you

Two limits are worth naming. The first is that the licence field in the package.json is empty and the repository carries no LICENSE file at the top level, so a fork that republishes the content or the custom UI is on unclear legal ground, and the repository is not something to copy wholesale without asking. The second is that this is infrastructure, not content, and the people who most want it are usually looking for the words rather than the machinery. If your goal is to learn how to configure a CircleCI pipeline, the published documentation is the place to be, and the Antora component layout will not help you. The repository also has a layer that is worth knowing about before you contribute: AGENTS.md, CLAUDE.md, agent-docs.config.yml, agent-docs.test.ts, a skills/ directory and a cmd/ directory, which together suggest that documentation for coding agents is treated as a first class output, tested by a dedicated test file. The related plan document, API_DOCS_LLM_ACCESS_PLAN.md, points the same way. That is a trend in technical documentation, and it comes with its own question about how much of the manual should be written for a machine to read rather than a person.

Editorial conclusion

circleci-docs suits a documentation engineer or technical writer who wants to see how a large product manual is assembled, and it suits a team that wants its own Antora site to borrow a proven component layout, a Vale style configuration and a link checker in the build. It is the wrong template for a small documentation set, because the machinery of a component based site, a Gulp pipeline, a Go tool and an agent documentation layer is a lot to carry for a handful of pages, and it is the wrong repository for reading CircleCI usage instructions, since the published site is the rendered form and the repository is its source. Before adopting the structure, read ARCHITECTURE.md and DEVELOPMENT.md, and check the.env.copy file since the local preview depends on environment variables loaded through dotenvx. The last push was on 2026-10-22, and the repository publishes no GitHub releases.

Frequently asked questions

Official sources

1. circleci/circleci-docs on GitHub
2. Issues
3. Project website
4. README