Jekyll Heroku Starter Kit

🧪 Comprehensive boilerplate code for setting up and running a Jekyll 4 site with a Material Design Lite theme on Heroku.

Homepage Design

Blog Design

Table of Contents

• 1. Overview
  • 1.1. Features
  • 1.2. Plugins
• 2. Getting Started
  • 2.1. Prerequisites
• 3. Installing
  • 3.1. Clone the Repository
  • 3.2. Creating the Heroku App
  • 3.3. Install the required Gems
  • 3.4. Adding Heroku Buildpacks
  • 3.5. Running Jekyll Locally
• 4. Deployment
• 5. Built With
• 6. Contributing
• 7. Code of Conduct
• 8. Versioning
• 9. Changelog
• 10. Authors
• 11. License
• 12. Acknowledgements

1. Overview

A boilerplate template to set up Jekyll 4 on a free Heroku server. Included are additional Jekyll plugins to showcase the full capabilities and it comes with an elegantly designed and crafted Material Design Lite theme.

If you are looking for version 3 of Jekyll instead of version 4, view this release which contains the boilerplate for Jekyll version 3.

Here's what you get in this package.

1.1. Features

• Latest Jekyll site running version 4.2.0.
• All the required Ruby files to run a Jekyll website on Heroku in minutes.
• jekyll-materialdocs - a beautiful Material Design Lite theme elegantly crafted, installed and configured.
• 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 which enables this gem to serve your app on Heroku using RackJekyll.
• humans.md file which outputs a human-readable file to /humans.txt
• Various plugins which enhance the functionality of Jekyll (see below for all the details).

1.2. Plugins

These plugins are installed by default:

• jekyll-feed
  • Generates an XML Feed at https://justinhartman.co/jekyll-heroku-starter-kit/feed.xml
• jekyll-seo-tag
  • View the config settings in _config.yml and index.md.
• jekyll-sitemap
  • Generates a XML Sitemap at https://justinhartman.co/jekyll-heroku-starter-kit/sitemap.xml
  • Generates a robots.txt file at https://justinhartman.co/jekyll-heroku-starter-kit/robots.txt
  • View the config settings in index.md.
• jekyll-paginate-v2
  • View the config settings in _config.yml and index.md.
• jekyll-include-cache
• jekyll-last-modified-at
  • View the config settings in index.md.
• jekyll-redirect-from
  • View the config settings in index.md.

View the _config.yml and index.md files for all the settings which are pre-configured for you. All plugins are easily labelled and well 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:
   • macOS: Homebrew
   • Windows: Chocolatey
   • Linux: apt-get or yum (distro dependent)
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 the 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 config set --local path 'vendor/bundle'
$ bundle install

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

{: .responsive-img}

4. Deployment

With everything completed in the steps above you can now deploy to Heroku. 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.

Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 4 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 1.02 KiB | 1.02 MiB/s, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Ruby app detected
remote: -----> Installing bundler 2.0.2
remote: -----> Removing BUNDLED WITH version in the Gemfile.lock
remote: -----> Compiling Ruby/Rack
remote: -----> Using Ruby version: ruby-2.6.3
remote: -----> Installing dependencies using bundler 2.0.2
remote:        Running: bundle install --without development:test --path vendor/bundle --binstubs vendor/bundle/bin -j4 --deployment
remote:        Bundle complete! 13 Gemfile dependencies, 40 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 (0.46s)
remote:        Cleaning up the bundler cache.
remote: -----> Writing config/database.yml to read from DATABASE_URL
remote: -----> Detecting rake tasks
remote: -----> Precompiling assets
remote:        Running: rake assets:precompile
remote:        Configuration file: /tmp/build_ed03c9f0880edd21c87388e3af02255f/_config.yml
remote:                    Source: /tmp/build_ed03c9f0880edd21c87388e3af02255f
remote:               Destination: /tmp/build_ed03c9f0880edd21c87388e3af02255f/_site
remote:         Incremental build: disabled. Enable with --incremental
remote:              Generating...
remote:               Jekyll Feed: Generating feed for posts
remote:                 AutoPages: Disabled/Not configured in site.config.
remote:                Pagination: Disabled in site.config.
remote:                            done in 1.057 seconds.
remote:         Auto-regeneration: disabled. Use --watch to enable.
remote:        Asset precompilation completed (1.91s)
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  8284k      0 --:--:-- --:--:-- --:--:-- 8303k
remote: -----> Installed directory to /app/bin
remote: -----> Discovering process types
remote:        Procfile declares types -> LANG, RACK_ENV, addons, console, rake, web
remote: -----> Compressing...
remote:        Done: 54.1M
remote: -----> Launching...
remote:        Released v31
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

Visit your Heroku URL (view demo here) and you should see the same site you built on your local machine, now published on Heroku.

5. Built With

• Jekyll 4.2.0
• Heroku
• ruby 2.7.3
• Homebrew 2.4.0
• Bundler version 2.2.9

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

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

10. Authors

• Justin Hartman - @justinhartman

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

11. License

This project is licensed under the MIT 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.

• 22 Digital - for the awesome development work on the theme.
• Jekyll Pygments Themes - for the github.css styling.
• @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.
• Picsum - for their amazing Lorem Picsum photos.
• Pravatar - for the profile images on the author feed.