CircleCI Documentation

This is the public repository for CircleCI Docs, astatic website generated by Jekyll. If you find anyerrors in our docs or have suggestions, please follow our ContributingGuide to submit an issue or pull request.

For Server 3.x documentation development, see the Server 3.x documentation section.

For minor changes like typos, you can click Suggest an edit to this page,located at the bottom of each article. This will take you to the source file onGitHub, where you can submit a pull request for your change through the UI.

For larger edits or new articles, you'll want to set up a local environment forediting. Please see our Local Developmentdocument to set that up.

If you have a question or need help debugging, please head to CircleCIDiscuss where our support team will help youout.

Preview

It is possible to build and serve the Jekyll docs locally (without ruby or jekyll installed) using Docker and docker compose.If you already configured Jekyll on your local machine, you need to delete vendor directory, before running the command.

$ docker-compose up

Documentation Components

This repository houses and manages several arms of documentation for CircleCI.This section will provide a brief overview of each "component" and how to getstarted with making changes.

/Jekyll - Main Site

This is the main CircleCI documentation site.This is built with Jekyll and houses the majority of our documentation. Otherbranches of documentation (src-api, src-crg, etc) eventually get moved intothis folder (in our build process) and integrated into the Jekyll Site. Followthe local development guide to get started withbuilding the Jekyll site.

We also have an automated code review tool setup, so it will run markdownlint on your PR and review for anymarkdown style violations. The rules are located at .markdownlint.jsonc.You can also fix most of the violations automatically. You can read morehere.

/src-api - API v1.1 and v2 Build Tooling

Our API documentation source can be found in this folder.

API v1 is written by hand, and compiled to work withSlate. The compilation and deployment ofv1 is handled by our .circleci/config.yml, which calls our build_api_docsscript. If you need to make changes to our V1 documentation, go tosrc-api/source/includes and make changes as needed in the markdown files.

API v2 is compiled from an OpenAPIspec. We useRedoc to compile our spec into a webpage. Tosee the compilation process, refer to build_api_docs.sh and our.circleci/config.yml. If you need to make changes to the output site, you willlikely need to make source code changes to the API, where the docs are generatedfrom.

This is the build folder we use for automatically generating documentation forthe CircleCI API v2. This uses Slate andWiddershins to create documentationwith a spec (that follows the Open API Spec) generated from the CircleCI codebase.

/src-js - Javascript Files

Some JavaScript files that make use of Webpack and bundles a Javascriptfile that eventually gets loaded into Jekyll. Our JavaScript files aresplintered between Jekyll's assets folder and here. We should be navigatingtoward one solution that will eventually aggregate all JS source code in one place.

/src-shared - Shared Assets with circleci.com

This is a git sub-module for shared content with the main CircleCIwebsite. The js folder within is symlinked intoJekyll's assets folder for JavaScript. Eventually, the JS here could/should beintegrated with a better JS bundle solution per above. Please see the localdevelopment guide for more information aboutpulling in the updates for the sub-module.

Server 3.x documentation

Server documentation is written in ASCIIDOC and built for the web and PDF usingjekyll-asciidoc and asciidoctor-pdf plugins.

Server capitalization

Server should not be capitalized, if it can be avoided.

Branch nomenclature for subsequent server releases

Note: If you are creating server documentation for subsequent releases (i.e., 3.0 to 3.1), pleasecreate a PR against the server/3.<NEW_VERSION_NUMBER>-preview branch (please create a branch withthis nomenclature, if you don't see one).

• Prefacing a branch with server/ will generate PDFs built of the files described in the following section. The PDFs appear as build artifactsand can be accessed from the CircleCI App.
• Appending -preview to a branch will deploy the preview site of the documentation updates.

Important files

Below are important files to note when updating server documentation:

• _server-3-overview.adoc: This file "stitches" any Overview-related documentation together, such as overall architectureand components, the server changelog, and frequently asked questions. This file is not expected to be updated often.

• _server-3-install-guide.adoc: This file "stitches" any Installation-related documentation together. Any brand-new sections must be added here.

• _server-3-ops-guide.adoc: This file "stitches" any Operator-related documentation together. Any brand-new sections must be added here.

• build_pdfs_asciidoc.sh: This is the shell script that is executed as a part of the pipeline when server documentationis built. It uses asciidoctor to build the three PDFs above. You should not have to update this file.

• sidenav.yml: Defines links in the sidebar. Any brand-new sections must be added here. Links to the PDFs must also beupdated here with every new release. See the section named Server v3.x PDFs.

• _config.yml: Update this file when you need to bump version numbers of serverversion (every new release),terraformversion, kubectlversion, helmversion, or kostversion. Consider these your global variables to use in anyserver documentation, (use the variable name in between two brackets, i.e. {serverversion}).

Server changelogs

To update the server changelog, you will need to update both the docs site and outer. JIRA tickets (and their associatedpull requests, details, etc.) are linked in the Server Release e-mail sent out monthly by Sara Meisburger, in theServer 3.x Release Plan document.

• server-3-whats-new.adoc: Make sure the Known Issues section is up to date, and add a new section for the newrelease.

• Outer changelog: the outer changelog is located in the private repository for circleci.com. Create a file containingthe contents of the previous changelog (located in changelog_ccie/). You will need to update the timestampand version values (and the Release header). Make sure the Known Issues section is up to date.

Note: For every new changelog, be sure to update the serverversion number in _config.yml and add the newlygenerated PDFs to your pull request. You will also need to change the links in sidenav.yml as described in Important files.

More server documentation specifics

For more information on server documentation development (this includes overall syntax suggestions, local development,and 2.x-specific information) check out the previous instructions here.

License Information

Documentation (guides, references, and associated images) is licensed asCreative Commons Attribution-NonCommercial-ShareAlike CC BY-NC-SA. The fulllicense can be foundhere, and thehuman-readable summaryhere.

Everything in this repository not covered above is licensed under the includedMIT license.