markdown-body entry-content container-lg" itemprop="text">

CircleCI Documentation

This is the public repository of https://circleci.com/docs/, 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.

Work on CircleCI Docs Locally

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.

Vagrant Setup

Prerequisites

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.

First Run

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

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

Bare Setup

Prerequisites

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.

First Run

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.

Editing Docs

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.

Jekyll Controller (JTCL)

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 Commands

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.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 413 Commits
hugo		hugo
jekyll		jekyll
scripts		scripts
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Vagrantfile		Vagrantfile
bootstrap.sh		bootstrap.sh
circle.yml		circle.yml
jctl		jctl

License

mtogstad/circleci-docs

Folders and files

Latest commit

History

Repository files navigation

CircleCI Documentation