Documentation for CircleCI.
HTML CSS Clojure Ruby JavaScript Shell
Latest commit 629a5fa Jan 17, 2017 @kimh kimh committed on GitHub Merge pull request #530 from circleci/yarn_version
Add yarn version manually

README.md

CircleCI Documentation CircleCI Build Status GitHub license CircleCi Community

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 following 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, and our support team will help you out.

Local Development

There are two ways to run a local development server: with Vagrant or without Vagrant.

With Vagrant

The easiest way to get started is by using Vagrant, which gives you a clean environment with all necessary dependencies.

Prerequisites

  • 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

First Run

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
./jctl start

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.

Once this is complete, Jekyll will automatically start in the VM. Vagrant will then begin forwarding port 4040, and you'll be able to view the docs at http://localhost:4040/docs/.

Editing Docs

All docs can be found in the jekyll/_docs directory. Make changes there, then run ./jctl rebuild to have Jekyll rebuild the site. For more detailed instructions on using jctl, see below.

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.

Without Vagrant

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

Prerequisites

  • 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
  • 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.

First Run

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/.

Editing Docs

All docs can be found in the jekyll/_docs directory. Make changes there, then re-run jekyll serve to have Jekyll rebuild and serve the site.

Jekyll Controller (jctl)

This is a Bash wrapper script to talk to Jekyll & Vagrant.

  • start: starts Jekyll; will also start Vagrant, if not already running
  • rebuild: rebuilds the site
  • stop: shuts down entire VM (including Jekyll)
  • restart: ./jctl stop && ./jctl start

Jekyll Commands

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: this 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.

License Information

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.