This is the public repository for https://circleci.com/docs/, a static website generated by Jekyll. If you find any errors or have requests, you can contribute by:

1. Reading our Contributing Guide
2. Setting up a local environment using the instructions below

If you can't contribute but still want to report a problem, open an Issue on this project. If you have a question or need help debugging a problem, do not submit an issue. Instead, please head to CircleCI Discuss where our support team will help you out.

There are two ways to run a local development server: Run With Vagrant or Run Without Vagrant.

The easiest way to get started is by using Vagrant because it gives you a clean environment with all of the necessary dependencies.

• Vagrant: download directly, brew cask install vagrant, or sudo apt-get install vagrant
• VirtualBox: download directly, brew cask install virtualbox, or sudo apt-get install virtualbox

Use the following command-line procedure to set up your local development environment with Vagrant and Brew on macOS.

1. Open a terminal window and run the following command to install Xcode:

xcode-select --install

A dialog box appears, press Continue. Xcode should install in a few minutes.

2. Install Homebrew, a macOS package manager.

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Type your password to complete the installation.

3. Install Vagrant.

brew cask install vagrant

Type your password to complete the installation.

4. Install VirtualBox.

brew cask install virtualbox

Type your password to complete the installation.

5. Fork the circleci-docs repo on GitHub.

6. Clone your fork of the circleci-docs repo.

git clone https://github.com/<my_github_username>/circleci-docs.git

7. Change to the circleci-docs directory and start Jekyll. The first time you run ./jctl start, Vagrant will provision the entire VM based on the contents of boostrap.sh. This process can take a few minutes, but it's a one-time deal.

cd circleci-docs

./jctl start

After successful completion, Jekyll will automatically start in the VM. Vagrant will then begin forwarding port 4040, and you'll be able to view the complete documentation site at http://localhost:4040/docs/.

The Jekyll Controller (jctl) is a bash wrapper script that talks to Jekyll & Vagrant.

• ./jctl start: Starts Jekyll; will also start Vagrant, if not already running
• ./jctl rebuild: Rebuilds the site
• ./jctl stop: Shuts down entire VM (including Jekyll)
• ./jctl restart: Stops and then starts the VM ./jctl stop && ./jctl start

Note: As an alternative to jctl, you can log into the VM directly to interact with Jekyll. Run vagrant ssh to enter the VM, then cd /vagrant/jekyll to access the repository's files. From there, you can run standard Jekyll commands with any preferred options.

If you already have a stable Ruby environment and feel comfortable installing dependencies, you can run the server directly on your machine.

• Ruby: See this project's Gemfile for the version of Ruby currently being used with this project. We recommend RVM for managing multiple Ruby versions, but there are other options available.
• Jekyll: Jekyll 3 transforms Markdown files.
• HTMLProofer: Used for testing links, images, and HTML. The docs site will need a passing build to be deployed, so use HTMLProofer to test everything before you push changes to GitHub.

You're also welcome to use Bundler to install required gems. If you are using RVM (or similar), make sure they all play nicely together.

To get a local copy of https://circleci.com/docs/, run the following commands:

git clone https://github.com/circleci/circleci-docs.git
cd circleci-docs/jekyll
jekyll serve

Jekyll will build the site and start a web server, which can be viewed in your browser at http://localhost:4000/docs/.

jekyll build: Generates static files for the site in the jekyll/_site directory.

jekyll serve: Runs jekyll build, then starts an included mini webserver to serve files from 'jekyll/_site; listens to localhost:4000 by default.

jekyll serve --detach: Serves the site as before, but runs in the background so you can use the same terminal window. Jekyll will display its process ID, so you can use that to kill the process when you want to stop Jekyll. If you lose the PID, you can run pkill -f jekyll to kill all Jekyll instances.

Use this procedure to add or modify the CircleCI docs and make a pull request from your local clone.

1. To see the list of the Markdown files for CircleCI v2.0, change to the jekyll/_cci2 directory and type ls.

cd jekyll/_cci2

ls

See the CONTRIBUTING.md file in this repository for documentation style tips.

2. Add or modify the Markdown files and rebuild the site to check your work.

./jctl rebuild

For more detailed instructions on using jctl, see Jekyll Controller Commands.

3. Create a branch and switch to it.

git branch <branch-name>

git checkout <branch-name>

4. Stage and commit your changes.

git commit -a -m "commit message"

5. Download GitHub Desktop from https://desktop.github.com/ if you haven’t already and open it.

6. To add your local repository, click the + button, select Add, and choose the <my-github-username>/circleci-docs folder.

The <my-github_username>/circleci-docs repo appears under GitHub in the left pane.

7. Click <my-github_username>/circleci-docs to see the committed changes in your branch.

8. Click the Pull Request button, add a description, and click Send Pull Request to submit your changes for review.

You will get a notification when a reviewer responds to your request and after the changes are merged.

Documentation (guides, references, and associated images) is licensed as Creative Commons Attribution-NonCommercial-ShareAlike CC BY-NC-SA. The full license can be found here, and the human-readable summary here.

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