This is a public repository of CircleCI documentation. Contributions welcome!
CircleCI Documentation is a static website generated by Jekyll. If you find any errors or have documentation request, please feel free to contribute by following the instructions below. Otherwise, you can always open an Issue on this project.
There are two good ways to run a development server locally:
-
Use Vagrant. The easiest way to get going is to use Vagrant. This gives you a clean environment with all the right versions of everything we need.
-
Use your existing Ruby environment. If you already have a Ruby environment you like (eg: you have rvm set up and feel comfortable using it) and feel comfortable installing dependencies with bundler and such, you can run it directly on your machine.
If you're going the Vagrant route, the following software need to be installed:
- Git - system version should be fine
- Vagrant - download directly, use apt-get (
sudo apt-get install vagrant), or use brew (brew cask install vagrant). - VirtualBox - download directly, use apt-get (
sudo apt-get install virtualbox), or use brew (brew cask install virtualbox). Best to use version 5.0+. Another Vagrant Provider such as Docker could be used instead but VirtualBox is the default.
To get a local copy of circleci.com/docs/ up and running you can run the
following commands (NOTE: The first time you run ./jctl start, Vagrant will provision the entire VM for
you based on what's in bootstrap.sh. It'll then run Jekyll for you. The whole process can take a few minutes, but it's a one-time deal.):
git clone https://github.com/circleci/circleci-docs.git
cd circleci-docs
./jctl start
Once this is complete, Jekyll will automatically start in the VM. Vagrant starts forwarding port 4040 for you. You can simply view the docs at http://localhost:4040/docs/ .
All of the docs can be found in the jekyll/_docs directory. You can make any
changes that you need there, then run ./jctl rebuild to have Jekyll rebuild
the site. How to use jctl can be found below.
As an alternative to using JCTL, you can log into the VM directly to interact
with Jekyll. Run vagrant ssh to enter the VM directly. cd /vagrant/jekyll
will take you to where the repository files are in the VM. From there you could
run standard Jekyll commands such as jekyll server with whatever flags you
would like.
Going the bare route, the following software need to be installed:
- Git - system version should be fine
- Ruby - the version of Ruby currently being used with this project will be noted in the Gemfile. If you need to manage multiple Ruby versions, we recommend RVM though there are similar solutions you can use.
- Jekyll - Jekyll version 3.
- HTMLProofer - HTMLProofer is used for testing links, images, and the HTML. The docs site needs to pass the build and test to be deployed. You can use HTMLProofer to test things before you send changes up to GitHub.
You're welcome to also use Bundler to install the Gems needed. If you are using RVM (or similar), just make sure they all play nice together.
To get a local copy of circleci.com/docs/ up and running you can 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. It can be viewed in your
browser at . To stop Jekyll and regain controll
of your terminal, just type CTRL-C.
All of the docs can be found in the jekyll/_docs directory. You can make any
changes that you need there, then re-run jekyll serve to have Jekyll rebuild
and serve the site.
This is a Bash wrapper script to talk to Jekyll & Vagrant.
- start: Starts Jekyll. Is Vagrant isn't running, starts Vagrant as well.
- rebuild: Tells Jekyll to rebuild the site.
- stop: Shuts down the entire VM (vagrant halt), including Jekyll.
- restart: Restarts the Vagrant machine. Basically an alias of stop then start.
jekyll build - this tells Jekyll to generate the static files for the site,
and place them in the jekyll/_site directory. It does not serve the files.
jekyll serve - this first runs jekyll build, then starts up an included
mini webserver to serve the files from the 'jekyll_site directory. Listens to
localhost:4000 by default.
jekyll serve --detach - this serves the site as before, but runs in the
background so that you can still use the same terminal window. Jekyll will tell
you which process ID belongs to it before it goes so you can use that to kill
it when you want to stop Jekyll. kill -9 P_ID. If you lose the ID, you can
run pkill -f jekyll to stop all Jekyll instances.
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.