Skip to content

Latest commit

 

History

History
394 lines (327 loc) · 15.3 KB

README.md

File metadata and controls

394 lines (327 loc) · 15.3 KB
Raw

Jekyll Heroku Starter Kit

Minimum boilerplate code for setting up and running a Jekyll site on Heroku.

Table of Contents

1. Features

This project will setup a minimum boilerplate template for running a Jekyll site on Heroku. With this, there are some additional Jekyll plugins installed for ease of use along with a default, minimal theme.

Here's what you get.

1.1. General

  • All required files to run a Jekyll site in minutes on Heroku.
  • jekyll-theme-minimal - Default minimal theme installed.
  • static.json - used by the Heroku static buildpack.
  • Rakefile - the Heroku Ruby buildpack runs rake assets:precompile when it’s available.
  • config.ru - the config file that enables this gem to serve your app on Heroku using RackJekyll.
  • New humans.md file that outputs a file to: https://jekyll-heroku-starter-kit.herokuapp.com/humans.txt

1.2. Plugins

These plugins are installed by default:

See the _config.yml and index.md files for all the settings which have been pre-configured for you, to enable the usage of these plugins. They are all well labelled and documented.

2. Getting Started

These instructions will get your copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

2.1. Prerequisites

The following prerequisites need to be installed on your machine for this to work.

  1. Heroku Toolbelt - the CLI interface to Heroku.
  2. A package manager for your Operating System:
  3. Ruby
  4. Bundler - to manage Ruby gems (see below).

Once you have installed ruby, installing bundler is pretty straightforward. Simply run this command in a terminal window.

$ gem install bundler

3. Installing

3.1. Clone the Repository

The first step is to clone this repository to a location on your computer. For this example we will assume that your default install location is a folder called jekyll-heroku-starter-kit.

$ git clone https://github.com/justinhartman/jekyll-heroku-starter-kit

The above command will checkout the source code to the folder jekyll-heroku-starter-kit/. You can change the default location by specifying a folder name in the checkout command with:

$ git clone https://github.com/justinhartman/jekyll-heroku-starter-kit custom-folder

3.2. Creating the Heroku App

Running the heroku apps:create command will create a new app on Heroku and add a reference to a git repository on Heroku itself.

$ cd jekyll-heroku-starter-kit/
$ heroku apps:create jekyll-heroku-starter-kit
Creating ⬢ jekyll-heroku-starter-kit... done
https://jekyll-heroku-starter-kit.herokuapp.com/ | https://git.heroku.com/jekyll-heroku-starter-kit.git

You can check that the new Heroku repo has been added to your git repo with the following command.

$ git config --list
remote.heroku.url=https://git.heroku.com/jekyll-heroku-starter-kit.git
remote.heroku.fetch=+refs/heads/*:refs/remotes/heroku/*
remote.origin.url=https://github.com/justinhartman/jekyll-heroku-starter-kit.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*

3.3. Install required Gems

The Gemfile in this repository contains everything needed to setup Jekyll and get your app ready for publishing to Heroku. Run the following command to install all the required dependencies.

$ bundle install --path vendor/bundle

3.4. Adding Heroku Buildpacks

We need to install a few buildpacks to tell Heroku how to handle the app. You need to install the following by executing these commands:

$ heroku buildpacks:add heroku/ruby
$ heroku buildpacks:add https://github.com/heroku/heroku-buildpack-static

3.5. Running Jekyll Locally

Once done with the above you should test your Jekyll installation to ensure that you are able to run the site on your machine. This is very important before deploying your app to Heroku.

Run the jekyll serve command to test your app.

$ bundle exec jekyll serve
Configuration file: /jekyll-heroku-starter-kit/_config.yml
Invalid theme folder: _includes
            Source: /jekyll-heroku-starter-kit
       Destination: /jekyll-heroku-starter-kit/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
         AutoPages: Disabled/Not configured in site.config.
        Pagination: Disabled in site.config.
                    done in 1.238 seconds.
 Auto-regeneration: enabled for '/jekyll-heroku-starter-kit'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

By visiting http://127.0.0.1:4000 you should see your newly built Jekyll site. This is an example of what you should be seeing.

Jekyll Site

4. Deployment

With everything setup in the steps above you can now deploy to Heroku. Simply execute the following commands to deploy a build to heroku.

$ cd jekyll-heroku-starter-kit/
$ git push heroku master

This will generate a build log that should resemble the below success.

Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 5.06 KiB | 647.00 KiB/s, done.
Total 6 (delta 3), reused 0 (delta 0)
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Ruby app detected
remote: -----> Compiling Ruby/Rack
remote: -----> Using Ruby version: ruby-2.3.3
remote: -----> Installing dependencies using bundler 1.15.2
remote:        Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment
remote:        Warning: the running version of Bundler (1.15.2) is older than the version that created the lockfile (1.16.1). We suggest you upgrade to the latest version of Bundler by running `gem install bundler`.
remote:        Fetching gem metadata from https://rubygems.org/..........
remote:        Fetching version metadata from https://rubygems.org/..
remote:        Fetching dependency metadata from https://rubygems.org/.
remote:        Using rake 12.3.1
remote:        Using public_suffix 3.0.2
remote:        Using bundler 1.15.2
remote:        Using colorator 1.1.0
remote:        Using concurrent-ruby 1.0.5
remote:        Using eventmachine 1.2.7
remote:        Using http_parser.rb 0.6.0
remote:        Using ffi 1.9.23
remote:        Using forwardable-extended 2.6.0
remote:        Using rb-fsevent 0.10.3
remote:        Using ruby_dep 1.5.0
remote:        Using kramdown 1.16.2
remote:        Using liquid 4.0.0
remote:        Using mercenary 0.3.6
remote:        Using rouge 3.1.1
remote:        Using safe_yaml 1.0.4
remote:        Fetching posix-spawn 0.3.13
remote:        Using rack 1.6.10
remote:        Using i18n 0.9.5
remote:        Using addressable 2.5.2
remote:        Using rb-inotify 0.9.10
remote:        Using em-websocket 0.5.1
remote:        Using pathutil 0.16.1
remote:        Using sass-listen 4.0.0
remote:        Using listen 3.1.5
remote:        Using sass 3.5.6
remote:        Using jekyll-watch 2.0.0
remote:        Using jekyll-sass-converter 1.5.2
remote:        Using jekyll 3.8.2
remote:        Fetching jekyll-feed 0.9.3
remote:        Fetching jekyll-include-cache 0.1.0
remote:        Installing posix-spawn 0.3.13 with native extensions
remote:        Installing jekyll-include-cache 0.1.0
remote:        Installing jekyll-feed 0.9.3
remote:        Fetching jekyll-paginate-v2 1.9.4
remote:        Using jekyll-redirect-from 0.13.0
remote:        Using jekyll-seo-tag 2.5.0
remote:        Fetching jekyll-sitemap 1.2.0
remote:        Installing jekyll-paginate-v2 1.9.4
remote:        Installing jekyll-sitemap 1.2.0
remote:        Using rack-jekyll 0.5.0
remote:        Using jekyll-theme-minimal 0.1.1
remote:        Fetching jekyll-last-modified-at 1.0.1
remote:        Installing jekyll-last-modified-at 1.0.1
remote:        Bundle complete! 12 Gemfile dependencies, 38 gems now installed.
remote:        Gems in the groups development and test were not installed.
remote:        Bundled gems are installed into ./vendor/bundle.
remote:        Bundle completed (4.39s)
remote:        Cleaning up the bundler cache.
remote:        Warning: the running version of Bundler (1.15.2) is older than the version that created the lockfile (1.16.1). We suggest you upgrade to the latest version of Bundler by running `gem install bundler`.
remote:        The latest bundler is 1.16.2, but you are currently running 1.15.2.
remote:        To update, run `gem install bundler`
remote: -----> Detecting rake tasks
remote: -----> Precompiling assets
remote:        Running: rake assets:precompile
remote:        Configuration file: /tmp/build_02fecdee16af99fdfb60e024ca330ed4/_config.yml
remote:        Invalid theme folder: _includes
remote:                    Source: /tmp/build_02fecdee16af99fdfb60e024ca330ed4
remote:               Destination: /tmp/build_02fecdee16af99fdfb60e024ca330ed4/_site
remote:         Incremental build: disabled. Enable with --incremental
remote:              Generating...
remote:                 AutoPages: Disabled/Not configured in site.config.
remote:                Pagination: Disabled in site.config.
remote:                            done in 0.556 seconds.
remote:         Auto-regeneration: disabled. Use --watch to enable.
remote:        Asset precompilation completed (1.28s)
remote:
remote: -----> Static HTML app detected
remote:   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
remote:                                  Dload  Upload   Total   Spent    Left  Speed
remote: 100  838k  100  838k    0     0  6185k      0 --:--:-- --:--:-- --:--:-- 6212k
remote: -----> Installed directory to /app/bin
remote: -----> Discovering process types
remote:        Procfile declares types -> web
remote:
remote: -----> Compressing...
remote:        Done: 25M
remote: -----> Launching...
remote:        Released v12
remote:        https://jekyll-heroku-starter-kit.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.
To https://git.heroku.com/jekyll-heroku-starter-kit.git
   4c1eff6..65eeca2  master -> master

Visit your Heroku URL (e.g. https://jekyll-heroku-starter-kit.herokuapp.com) and you should see the same site you built on your local machine, now published on Heroku.

5. Built With

6. Contributing

Please read the CONTRIBUTING.md file for details on how you can get involved in the project as well as the process for submitting bugs and pull requests.

7. Code of Conduct

Please read the CODE_OF_CONDUCT.md file for the guidelines that govern the community.

8. Versioning

We use Semantic Versioning for software versions of this project. For a list of all the versions available, see the tags and releases on this repository.

9. Change-Log

View the CHANGELOG.md file for a detailed list of changes, along with specific tasks completed for each version released to date.

10. Authors

Also see the list of contributors who have participated in this project.

11. License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for full details.

12. Acknowledgements

Special thanks go out to the following people and projects who have helped in some way to make this project a reality.

  • @justinhartman/.github - for the awesome Github project templates.
  • Andy Croll - for his post on serving a Jekyll site on Heroku.
  • Heroku - for their post on running Jekyll on their platform.