diff --git a/docs/_docs/continuous-integration/circleci.md b/docs/_docs/continuous-integration/circleci.md new file mode 100644 index 00000000..fede484a --- /dev/null +++ b/docs/_docs/continuous-integration/circleci.md @@ -0,0 +1,92 @@ +--- +title: "CircleCI" +--- + +Building, testing, and deploying your Jekyll-generated website can quickly be done with [CircleCI][0], a continuous integration & delivery tool. CircleCI supports [GitHub][1] and [Bitbucket][2], and you can get started for free using an open-source or private repository. + +[0]: https://circleci.com/ +[1]: https://github.com/ +[2]: https://bitbucket.org/ + +## 1. Follow Your Project on CircleCI + +To start building your project on CircleCI, all you need to do is 'follow' your project from CircleCI's website: + +1. Visit the 'Add Projects' page: +1. From the GitHub or Bitbucket tab on the left, choose a user or organization. +1. Find your project in the list and click 'Build project' on the right. +1. The first build will start on its own. You can start telling CircleCI how to build your project by creating a [circle.yml][3] file in the root of your repository. + +[3]: https://circleci.com/docs/configuration/ + +## 2. Dependencies + +The easiest way to manage dependencies for a Jekyll project (with or without CircleCI) is via a [Gemfile][4]. You'd want to have Jekyll, any Jekyll plugins, [HTML Proofer](#html-proofer), and any other gems that you are using in the `Gemfile`. Don't forget to version `Gemfile.lock` as well. Here's an example `Gemfile`: + +[4]: http://bundler.io/gemfile.html + +```yaml +source 'https://rubygems.org' + +ruby '2.4.0' + +gem 'jekyll' +gem 'html-proofer' +``` + +CircleCI detects when `Gemfile` is present is will automatically run `bundle install` for you in the `dependencies` phase. + +## 3. Testing + +The most basic test that can be run is simply seeing if `jekyll build` actually works. This is a blocker, a dependency if you will, for other tests you might run on the generate site. So we'll run Jekyll, via Bundler, in the `dependencies` phase. + +``` +dependencies: + post: + - bundle exec jekyll build +``` + +### HTML Proofer + +With your site built, it's useful to run tests to check for valid HTML, broken links, etc. There's a few tools out there but [HTML Proofer][5] is popular amongst Jekyll users. We'll run it in the `test` phase with a few preferred flags. Check out the `html-proofer` [README][6] for all available flags, or run `htmlproofer --help` locally. + +[5]: https://github.com/gjtorikian/html-proofer +[6]: https://github.com/gjtorikian/html-proofer/blob/master/README.md#configuration + +```yaml +test: + post: + - bundle exec htmlproofer ./_site --check-html --disable-external +``` + +## Complete Example circle.yml File + +When you put it all together, here's an example of what that `circle.yml` file could look like: + +``` +machine: + environment: + NOKOGIRI_USE_SYSTEM_LIBRARIES: true # speeds up installation of html-proofer + +dependencies: + post: + - bundle exec jekyll build + +test: + post: + - bundle exec htmlproofer ./_site --allow-hash-href --check-favicon --check-html --disable-external + +deployment: + prod: + branch: master + commands: + - rsync -va --delete ./_site username@my-website:/var/html +``` + +## Questions? + +This entire guide is open-source. Go ahead and [edit it][7] if you have a fix or [ask for help][8] if you run into trouble and need some help. CircleCI also has an [online community][9] for help. + +[7]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration/circleci.md +[8]: https://jekyllrb.com/help/ +[9]: https://discuss.circleci.com diff --git a/docs/_docs/continuous-integration/index.md b/docs/_docs/continuous-integration/index.md new file mode 100644 index 00000000..14c5c749 --- /dev/null +++ b/docs/_docs/continuous-integration/index.md @@ -0,0 +1,9 @@ +--- +title: Continuous Integration +permalink: /docs/continuous-integration/ +--- + +Continuous Integration (CI) enables you to publish your Jekyll generated website with confidence by automating the quality assurance and deployment processes. You can quickly get started using CI with one of the providers below: + +* [Travis CI](travis-ci) +* [CircleCI](circleci) diff --git a/docs/_docs/continuous-integration.md b/docs/_docs/continuous-integration/travis-ci.md similarity index 95% rename from docs/_docs/continuous-integration.md rename to docs/_docs/continuous-integration/travis-ci.md index c2e8a31f..e76e1a60 100644 --- a/docs/_docs/continuous-integration.md +++ b/docs/_docs/continuous-integration/travis-ci.md @@ -1,15 +1,13 @@ --- -title: Continuous Integration -permalink: /docs/continuous-integration/ +title: "Travis CI" --- You can easily test your website build against one or more versions of Ruby. The following guide will show you how to set up a free build environment on -[Travis][0], with [GitHub][1] integration for pull requests. Paid -alternatives exist for private repositories. +[Travis][travis], with [GitHub][github] integration for pull requests. -[0]: https://travis-ci.org/ -[1]: https://github.com/ +[travis]: https://travis-ci.org/ +[github]: https://github.com/ ## 1. Enabling Travis and GitHub @@ -28,7 +26,7 @@ The simplest test script simply runs `jekyll build` and ensures that Jekyll doesn't fail to build the site. It doesn't check the resulting site, but it does ensure things are built properly. -When testing Jekyll output, there is no better tool than [html-proofer][2]. +When testing Jekyll output, there is no better tool than [html-proofer][html-proofer]. This tool checks your resulting site to ensure all links and images exist. Utilize it either with the convenient `htmlproofer` command-line executable, or write a Ruby script which utilizes the gem. @@ -70,7 +68,7 @@ Options are given as a second argument to `.new`, and are encoded in a symbol-keyed Ruby Hash. For more information about the configuration options, check out `html-proofer`'s README file. -[2]: https://github.com/gjtorikian/html-proofer +[html-proofer]: https://github.com/gjtorikian/html-proofer ## 3. Configuring Your Travis Builds @@ -93,7 +91,7 @@ Your `.travis.yml` file should look like this: ```yaml language: ruby rvm: -- 2.2.5 +- 2.3.3 before_script: - chmod +x ./script/cibuild # or do this locally and commit @@ -126,7 +124,7 @@ access to Bundler, RubyGems, and a Ruby runtime. ```yaml rvm: -- 2.2.5 +- 2.3.3 ``` RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This @@ -228,5 +226,5 @@ an entry in the `.gitignore` file to avoid it from being checked in again. This entire guide is open-source. Go ahead and [edit it][3] if you have a fix or [ask for help][4] if you run into trouble and need some help. -[3]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration.md +[3]: https://github.com/jekyll/jekyll/edit/master/docs/_docs/continuous-integration/travis-ci.md [4]: https://jekyllrb.com/help/