Build Jekyll with Bundler

Build Jekyll with Bundler

Jekyll 3.1.2 default theme build with bundler on GitLab Pages

Jekyll Version
Build Status

View site: https://jekyll-themes.gitlab.io/default-bundler/


Theme: Jekyll 3 Default

Original source:

This project was created with Jekyll 3.1.2 default template by running jekyll new project locally. After that, the project was pushed to this repository with the following configurations:

Building Jekyll with Bundler on GitLab

Bundler is a native dependency manager which ensures that all the gems your project needs will be loaded properly.

In order to build your Jekyll site with Bundler in your GitLab Pages projects, you will need to configure them properly to do so.

GitLab CI configuration

  • .gitlab-ci.yml
# requiring the environment of Ruby 2.3.x
image: ruby:2.3

# add bundle cache to 'vendor' for speeding up builds
cache:
  paths: 
    - vendor/

before_script:
  - bundle install --path vendor

# the 'pages' job will deploy and build your site to the 'public' path
pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public/
  artifacts:
    paths:
      - public
  only:
    - master # this job will affect only the 'master' branch

Gemfile configuration

  • Gemfile
source "https://rubygems.org"

gem 'jekyll', '3.1.2' # this is the Jekyll version we are working with
# gem 'nokogiri', '1.6.7.2'

Note: Nokogiri is a dependency that might cause errors if it's not explicitly added to the script. If you face building errors, uncomment it.

Jekyll configuration

  • _config.yml
---
# your settings

exclude: [vendor] # make sure to exclude 'vendor' from the build 

---

Note: CI is configured to bundle all gems in the vendor directory, which Jekyll will mistakenly read and explode on. That's why you need to exclude it on _config.yml.

You can also exclude Gemfile and Gemfile.lock from the builds. If you don't, they will be rendered to the public site folder. To do that, replace the line

exclude: [vendor]

for

exclude: [vendor, "Gemfile", "Gemfile.lock"]

How to test builds in all branches

Create a Test job

If you want to build Jekyll with Bundler and also perform a test job to every branch except master, and also deploy your website from master branch, this is what you need to do to your GitLab-ci file:

  • .gitlab-ci.yml
image: ruby:2.1

cache:
  paths: 
    - vendor/

before_script:
  - bundle install --path vendor

# add a job called 'test'
test:
  stage: test
  script:
    - bundle exec jekyll build -d public/
  except:
    - master # the 'test' job will affect all branches expect 'master'

pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public/
  artifacts:
    paths:
      - public # only the job 'pages' will generate the artifacts (similar to your local '_site' folder)
  only:
    - master

Test static site folder

You can also generate your site artifacts and download them when testing your builds. By doing so, you can check your site before merging your test branch with master. They will NOT override the content of the public folder if you assign a different folder to the test job. To do that, replace the job test for the code below:

# add a job called 'test' and assign a folder to store the static site
test:
  stage: test
  script:
    - bundle exec jekyll build -d test/ # replacing 'public' for 'test'
  artifacts:
    paths:
      - test # the 'test' job will generate a 'test/' folder containing your static site
  except:
    - master 

Building locally

Note: We assume you already have Jekyll 3.1.2 installed and up and running on your computer.

To work locally with this project, there are a few options. But let's keep it simple:

  • Fork, clone or download this project
  • Install Bundler if you don't have it already: gem install bundler
  • Navigate to the folder where you cloned the project cd path/to/project
  • Run bundle install
  • Adjust _config.yml according to your project
  • Serve Jekyll with bundler: bundle exec jekyll serve